Taro 常见规范和语法特性、常用 API 以及避坑指南

一、基础配置

（一）Taro 规范

在 Taro 组件中会包含类静态属性、类属性、生命周期等的类成员，其书写顺序最好遵循以下约定（顺序从上至下）。

1. static 静态方法
2. constructor
3. componentWillMount
4. componentDidMount
5. componentWillReceiveProps
6. shouldComponentUpdate
7. componentWillUpdate
8. componentDidUpdate
9. componentWillUnmount
10. 点击回调或者事件回调 比如 onClickSubmit() 或者 onChangeDescription()
11. render

推荐使用对象解构的方式来使用 state、props。

import Taro, { Component } from '@tarojs/taro'

class MyComponent extends Component {
  ......
  render () {
    const { isEnable } = this.props     // ✓ 正确
    const { myTime } = this.state     // ✓ 正确
    return (
      ......
    )
  }
}

不要以 class/id/style 作为自定义组件的属性名

     // ✗ 错误
     // ✗ 错误
     // ✗ 错误

不要使用 HTML 标签

     // ✗ 错误
    // ✗ 错误

不要在调用 this.setState 时使用 this.state

由于 this.setState 异步的缘故，这样的做法会导致一些错误，可以通过给 this.setState 传入函数来避免

this.setState({
  value: this.state.value + 1
})   // ✗ 错误
this.setState(prevState => ({ value: prevState.value + 1 }))    // ✓ 正确

map 循环时请给元素加上 key 属性

list.map(item => {
  return (
    {item.name}
  )
})

尽量避免在 componentDidMount 中调用 this.setState

因为在 componentDidMount 中调用 this.setState 会导致触发更新

不要在 componentWillUpdate/componentDidUpdate/render 中调用 this.setState

不要定义没有用到的 state

组件最好定义 defaultProps

import Taro, { Component } from '@tarojs/taro'
import { View, Text } from '@tarojs/components'

class MyComponent extends Component {
  static defaultProps = {
    isEnable: true
  }
  render () {
    return (
      
        {isEnable && Hello}
      
    )
  }
}

render 方法必须有返回值

import Taro, { Component } from '@tarojs/taro'
import { View } from '@tarojs/components'

class MyComponent extends Component {
  ......
  render () {
    return (
      Hello
    )
  }
}

值为 true 的属性可以省略书写值

JSX 属性或者表达式书写时需要注意空格

   // ✗ 错误
   // ✗ 错误
   // ✗ 错误
      // ✓ 正确

事件绑定均以 on 开头

在 Taro 中所有默认事件如 onClick、onTouchStart 等等，均以 on 开头

import Taro, { Component } from '@tarojs/taro'
import { View } from '@tarojs/components'

class MyComponent extends Component {
  clickHandler (e) {
    console.log(e)
  }  
  render () {
    const { myTime } = this.state

    return (
          // ✓ 正确
        Hello world!
      
    )
  }
}

子组件传入函数时属性名需要以 on 开头

import Tab from '../../components/Tab/Tab'

class MyComponent extends Component {
  ......
  render () {
    return (
      
            // ✓ 正确
      
    )
  }
}

不能使用 Array#map 之外的方法操作 JSX 数组

更多详细：请参考 Taro 官网规范

（二）页面生命周期

1.componentWillMount() 

页面加载时触发，一个页面只会调用一次，此时页面 DOM 尚未准备好，不能和视图层交互。

2.componentDidMount() 

页面初次渲染完成时触发，一个页面只会调用一次，可以和视图层交互。

3.shouldComponentUpdate(nextProps, nextState)

页面是否需要更新，返回 false 不继续更新

4.componentWillUpdate(nextProps, nextState)

页面即将更新

5.componentDidUpdate(prevProps, prevState)

页面更新完毕

6.componentWillUnmount()

页面卸载时触发，如 redirectTo 或 navigateBack 到其他页面时

7.componentDidShow()

页面显示/切入前台时触发

8.componentDidHide()

页面隐藏/切入后台时触发，如 navigateTo 或者底部 tab 切换到其他页面，小程序切入后台等。

以上所有的生命周期方法中，都可以通过 this.$router.params 获取打开当前页面路径中的参数。

（三）页面事件处理函数

 

1.onPullDownRefresh()：监听用户下拉刷新事件。

2.onReachBottom()：监听用户上拉触底事件。

3.onPageScroll(Object)：监听用户滑动页面事件。

注意：请避免在 onPageScroll 中过于频繁的执行 this.setState() 等引起逻辑层-渲染层通信的操作。

4.onShareAppMessage(Object)：监听用户点击页面内转发按钮（Button 组件 openType='share'）或右上角菜单“转发”按钮的行为，并自定义转发内容。

5.onResize(Object)：小程序屏幕旋转时触发。

6.onTabItemTap(Object)：点击 tab 时触发。

7.componentWillPreload()：预加载钩子。

（四）路由功能

我们只需要在入口文件的 config 配置中指定好 pages，然后就可以在代码中通过 Taro 提供的 API 来跳转到目的页面。

1.路由 API

（1）Taro.navigateTo：打开新页面

（2）Taro.redirectTo：在当前页面打开

（3）Taro.switchTab：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面

（4）Taro.navigateBack：关闭当前页面，返回上一页面或多级页面

（5）Taro.reLaunch：关闭所有页面，打开到应用内的某个页面

2.路由参数

我们可以通过在所有跳转的 url 后面添加查询字符串参数进行跳转传参，代码如下：

Taro.navigateTo({
  url: '/pages/page/path/name?id=2&type=test'
})

在跳转成功的目标页的生命周期方法里就能通过 this.$router.params 获取到传入的参数，代码如下：

class C extends Taro.Component {
  componentWillMount () {
    console.log(this.$router.params) // 输出 { id: 2, type: 'test' }
  }
}

（五）静态资源引用

1.引用样式文件 和 JS 文件

可以通过 ES6 的 import 语法来引用样式文件

import './index.scss'
import { uploadImgForBase } from '../../../utils/index'

2.引用图片、音频、字体等文件

可以通过 ES6 的 import 语法来引用此类文件，拿到文件引用直接在 JSX 中进行使用

import namedPng from '../../images/path/named.png' // 引用文件
 // 使用

3.引用 JSON 文件

可以通过 ES6 的 import 语法来引用此类文件，拿到 JSON 文件输出的 JSON 数据

import namedJson from '../../json/path/named.json'
console.log(namedJson)

4.小程序样式中引用本地资源

在小程序的样式中，默认不能直接引用本地资源，只能通过网络地址、Base64 的方式来进行资源引用。Taro 提供了直接在【样式文件】中引用本地资源的方式，其原理是通过 PostCSS 的 postcss-url 插件将样式中本地资源引用转换成 Base64 格式，从而能正常加载。

Taro 默认会对 10kb 大小以下的资源进行转换，config/index.js 配置文件中，配置位于  weapp.module.postcss，具体配置如下：

// 小程序端样式引用本地资源内联
url: {
  enable: true,
  config: {
    limit: 10240 // 设定转换尺寸上限
  }
}

二、语法特性

待补充

三、常用 API

（一）设置导航栏标题

Taro.setNavigationBarTitle({
  title: '标题'
})

（二）图片

1.预览图片

Taro.previewImage({
  current: url, // 当前显示图片的http链接
  urls: urls, // 需要预览的图片http链接列表
});

2.选择图片

Taro.chooseImage(Object object)

3.获取图片信息

Taro.getImageInfo(Object object)

更多详情，请查看 微信小程序-图片 API。

（三）上传和下载

1.上传

将本地资源上传到服务器。客户端发起一个 HTTPS POST 请求，其中 content-type 为 multipart/form-data。

Taro.uploadFile(Object object)

2.下载

下载文件资源到本地。客户端直接发起一个 HTTPS GET 请求，返回文件的本地临时路径 (本地路径)，单次下载允许的最大文件为 50MB。

Taro.downloadFile(Object object)

（四）滚动

将页面滚动到目标位置，支持选择器和滚动距离两种方式定位。

Taro.pageScrollTo(option)

（五）下拉刷新

停止当前页面下拉刷新。

Taro.stopPullDownRefresh(option)

// 下拉刷新
onPullDownRefresh () {
  let timeOut = setTimeout(() => {
    ...... // 省略下拉刷新操作
    Taro.stopPullDownRefresh()
    timeOut = null
  }, 1000);
}

（六）剪贴板

设置系统剪贴板的内容。调用成功后，会弹出 toast 提示"内容已复制"，持续 1.5s。

Taro.setClipboardData({
  data: 'data',
  success: function (res) {
    wx.showToast({
      title: `已复制`,
      icon: "none",
      duration: 2000,
    });
  },
});

（七）文件

获取全局唯一的文件管理器。

Taro.getFileSystemManager()

更多内容，请查看 Taro 官网之 API。

四、避坑指南

待补充