Taro基础教程之React

在Taro可以通过import * as React from 'react'来使用React，JSX语法没有任何限制，但和在浏览器中使用React依然有一些不同，具体体现在：

参考：https://taro-docs.jd.com/taro/docs/react/

入口组件

每一个Taro应用都需要一个入口组件用来注册应用，入口文件默认是src目录下的app.js，在Taro中使用React，入口组件必须导出一个React组件，在入口组件中我们可以设置全局状态或访问小程序入口实例的生命周期：

import React, { Component } from 'react'
// 假设我们要使用 Redux
import { Provider } from 'react-redux'

import configStore from './store'

import './app.css'

const store = configStore()

class App extends Component {
  componentDidMount () {}

  // 对应 onShow
  componentDidShow () {}

  // 对应 onHide
  componentDidHide () {}

  // 对应 onError
  componentDidCatchError () {}

  render () {
    // 在入口组件不会渲染任何内容，但我们可以在这里做类似于状态管理的事情
    return (
      <Provider store={store}>
        {this.props.children} /* this.props.children 是将要被渲染的页面 */
      </Provider>
    )
  }
}

export default App

对于一个入口文件(例如app.jsx)而言，我们可以新增一个app.config.js的文件进行全局配置，app.config.js的默认导出就是全局配置，配置规范基于微信小程序的全局配置进行制定，所有平台进行统一:

// app.config.js
export default {
  pages: [
    'pages/index/index'
  ],
  window: {
    backgroundTextStyle: 'light',
    navigationBarBackgroundColor: '#fff',
    navigationBarTitleText: 'WeChat',
    navigationBarTextStyle: 'black'
  }
}

组件生命周期

onLaunch(options)

在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应app的onLaunch

在此生命周期中通过getCurrentInstance().router.params，可以访问到程序初始化参数。

componentWillMount()

监听程序初始化，初始化完成时触发（全局只触发一次）

componentDidMount()

页面初次渲染完成时触发，一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。此生命周期可以访问getCurrentInstance().router。此生命周期可以访问Taro DOM并且更改DOM或添加事件，但无法通过Taro.createSelectorQuery查找小程序DOM。

componentDidShow(options)

在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应onShow，在 H5/RN 中同步实现

程序启动，或从后台进入前台显示时触发，微信小程序中也可以使用Taro.onAppShow绑定监听

在此生命周期中通过getCurrentInstance().router.params，可以访问到程序初始化参数

参数与componentWillMount中获取的基本一致，但百度小程序中补充entryType和appURL两个参数

componentDidHide()

在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应onHide，在H5/RN中同步实现

程序从前台进入后台时触发，微信小程序中也可以使用Taro.onAppHide绑定监听

componentDidCatchError(String error)

在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应onError，H5/RN中尚未实现

程序发生脚本错误或 API 调用报错时触发，微信小程序中也可以使用Taro.onError绑定监听

componentDidNotFound(Object)

在微信/字节跳动小程序中这一生命周期方法对应onPageNotFound，其他端尚未实现

微信小程序中，基础库 1.9.90 开始支持

程序要打开的页面不存在时触发，微信小程序中也可以使用Taro.onPageNotFound绑定监听

页面组件

每一个Taro应用都至少包括一个页面组件，页面组件可以通过Taro路由进行跳转，也可以访问小程序页面的生命周期：

import React, { Component } from 'react'
import { View, Button, Text } from '@tarojs/components'

class Index extends Component {

  config = {
    navigationBarTitleText: '首页'
  }

  // 对应 onShow
  componentDidShow () { }

  // 对应 onHide
  componentDidHide () { }

  // 对应 onPullDownRefresh，除了 componentDidShow/componentDidHide 之外，
  // 所有页面生命周期函数名都与小程序相对应
  onPullDownRefresh () {
  },

  // 对应 onPullDownRefresh
  onReachBottom () {
  },

  componentWillUnmount () { }

  render () {
    return (
      <View className='index'>
      </View>
    )
  }
}

export default Index

配置文件

和入口组件一样，对于一个页面文件(例如./pages/index/index.jsx)而言，我们可以新增一个./pages/index/index.config.js的文件进行页面配置，index.config.js的默认导出就是页面配置：

// ./pages/index/index.jsx
export default {
  navigationBarTitleText: '首页'
}

生命周期

onReady()

页面首次渲染完毕时执行，此生命周期在小程序端对应小程序页面的onReady生命周期。从此生命周期开始可以使用createCanvasContext或createselectorquery等 API 访问真实 DOM。

在非页面组件中，可以使用Taro内置的 消息机制 访问页面组件的onReady()生命周期：

import { eventCenter, getCurrentInstance } from '@tarojs/taro'
class Test extends React.Component {
  componentDidMount () {
    eventCenter.once(getCurrentInstance().router.onReady, () => {
      const query = Taro.createSelectorQuery()
      query.select('#only').boundingClientRect()
      query.exec(res => {
        console.log(res, 'res')
      })
      console.log('onReady')
    })
  }

  render () {
    return (
      <View id="only">
      </View>
    )
  }
}

onLoad(options)

页面创建时执行，此生命周期在小程序端对应小程序页面的onLoad生命周期。此生命周期可以访问getCurrentInstance().router。

componentWillMount()

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

componentDidMount()

页面初次渲染完成时触发，一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。此生命周期可以访问getCurrentInstance().router。此生命周期可以访问 Taro DOM 并且更改 DOM 或添加事件，但无法通过Taro.createSelectorQuery查找小程序 DOM。

shouldComponentUpdate(nextProps, nextState)

页面是否需要更新，返回false不继续更新，否则继续走更新流程

componentWillUpdate(nextProps, nextState)

页面即将更新

componentDidUpdate(prevProps, prevState)

页面更新完毕

componentWillUnmount()

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

componentDidShow()

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

componentDidHide()

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

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

页面事件处理函数

在小程序中，页面还有在一些专属的事件处理函数，如下

onPullDownRefresh()

监听用户下拉刷新事件

• 需要在全局配置的window选项中或页面配置中开启enablePullDownRefresh
• 可以通过Taro.startPullDownRefresh触发下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致
• 当处理完数据刷新后，Taro.stopPullDownRefresh可以停止当前页面的下拉刷新

onReachBottom()

监听用户上拉触底事件

• 可以在全局配置的 window 选项中或页面配置中设置触发距离 onReachBottomDistance
• 在触发距离内滑动期间，本事件只会被触发一次

onPageScroll(Object)

监听用户滑动页面事件

Object 参数说明：

注意：请只在需要的时候才在page中定义此方法，不要定义空方法。以减少不必要的事件派发对渲染层-逻辑层通信的影响
注意：请避免在onPageScroll中过于频繁的执行this.setState()等引起逻辑层-渲染层通信的操作。尤其是每次传输大量数据，会影响通信耗时

onShareAppMessage(Object)

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

注意：只有定义了此事件处理函数，右上角菜单才会显示“转发”按钮

Object 参数说明：

此事件需要return一个Object，用于自定义转发内容，返回内容如下：

自定义转发内容

示例代码

// page.js
export default class Index extends Component {
  onShareAppMessage (res) {
    if (res.from === 'button') {
      // 来自页面内转发按钮
      console.log(res.target)
    }
    return {
      title: '自定义转发标题',
      path: '/page/user?id=123'
    }
  }
}

onResize(Object)

只有微信小程序支持，基础库 2.4.0 开始支持

小程序屏幕旋转时触发。详见 响应显示区域变化

onTabItemTap(Object)

微信小程序中，基础库 1.9.0 开始支持

点击tab时触发

Object参数说明：

onAddToFavorites(Object)

Taro 3.0.3 版本开始支持，只有微信小程序支持，本接口为 Beta 版本，安卓 7.0.15 版本起支持，暂只在安卓平台支持

监听用户点击右上角菜单“收藏”按钮的行为，并自定义收藏内容。

Object参数说明：

此事件处理函数需要return一个Object，用于自定义收藏内容：

示例代码

onAddToFavorites(res) {
  // webview 页面返回 webviewUrl
  console.log('WebviewUrl: ', res.webviewUrl)
  return {
    title: '自定义标题',
    imageUrl: 'http://demo.png',
    query: 'name=xxx&age=xxx',
  }
}

onShareTimeline()

Taro 3.0.3 版本开始支持，只有微信小程序支持，基础库 2.11.3 开始支持，本接口为 Beta 版本，暂只在 Android 平台支持

监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。

注意：只有定义了此事件处理函数，右上角菜单才会显示“分享到朋友圈”按钮

自定义转发内容

事件处理函数返回一个Object，用于自定义分享内容，不支持自定义页面路径，返回内容如下：

// page.js
class Index extends Component {
  onShareTimeline () {
    console.log('onShareTimeline')
  }
}

componentWillPreload()

目前只有微信小程序支持

预加载钩子

onTitleClick()

只有支付宝小程序支持，基础库 1.3.0 开始支持

点击标题触发

onOptionMenuClick()

只有支付宝小程序支持，基础库 1.3.0 开始支持

点击导航栏额外图标触发

onPopMenuClick()

只有支付宝小程序支持，基础库 1.11.0 开始支持

暂无说明

onPullIntercept()

只有支付宝小程序支持，基础库 1.3.0 开始支持

下拉截断时触发

H5 暂时没有同步实现onReachBottom、onPageScroll这两个事件函数，可以通过给window绑定scroll事件来进行模拟，而onPullDownRefresh下拉刷新则暂时只能用ScrollView组件来代替了。

注：以上成员方法在 Taro 的页面中同样可以使用，书写同名方法即可，不过需要注意的，目前暂时只有小程序端支持（支持程度如上）这些方法，编译到 H5/RN 端后这些方法均会失效。

内置组件/Props

Taro 中使用 React，内置组件遵循小程序组件规范，所有内置组件都必须从@tarojs/components引入，组件的Props遵从大驼峰式命名规范：

Taro

import { View } from '@tarojs/components'
<View hoverClass='test' />

对应小程序:

<view hover-class='' />

事件

在 Taro 中事件遵从小驼峰式命名规范，所有内置事件名以on开头，在事件处理函数中第一个参数是事件本身，可以通过调用stopPropagation来阻止冒泡。

function Comp () {
  // 只有 onClick 对应 bindtap
  // 其余内置事件名
  function clickHandler (e) {
    e.stopPropagation() // 阻止冒泡
  }

  function scrollHandler () {
    //
  }
  return <ScrollView onClick={clickHandler} onScroll={scrollHandler} />
}

Hooks

Hooks 文档：https://taro-docs.jd.com/taro/docs/hooks

其它限制

由于小程序不支持动态引入，因此小程序中无法使用 React.lazy API。