React
在 Taro 可以通过 import * as React from 'react'
来使用 React,JSX 语法没有任何限制,但和在浏览器中使用 React 依然有一些不同,具体体现在:
#
入口组件每一个 Taro 应用都需要一个入口组件用来注册应用,入口文件默认是 src
目录下的 app.js
,在 Taro 中使用 React,入口组件必须导出一个 React 组件,在入口组件中我们可以设置全局状态或访问小程序入口实例的生命周期:
对于一个入口文件(例如app.jsx
)而言,我们可以新增一个 app.config.js
的文件进行全局配置,app.config.js
的默认导出就是全局配置,配置规范基于微信小程序的全局配置进行制定,所有平台进行统一:
#
组件生命周期#
onLaunch(options)在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应 app 的
onLaunch
在此生命周期中通过 Current.router.params
,可以访问到程序初始化参数。
#
componentWillMount()监听程序初始化,初始化完成时触发(全局只触发一次)
参数格式如下
属性 | 类型 | 说明 | 微信小程序 | 百度小程序 | 字节跳动小程序 | 支付宝小程序 | H5 | RN |
---|---|---|---|---|---|---|---|---|
path | string | 启动小程序的路径 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
scene | number | 启动小程序的场景值 | ✔️ | ✔️ | ✔️ | ✘ | ✘ | ✘ |
query | Object | 启动小程序的 query 参数 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
shareTicket | string | shareTicket,详见获取更多转发信息 | ✔️ | ✔️ | ✔️ | ✘ | ✘ | ✘ |
referrerInfo | Object | 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {} | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
其中,场景值 scene,在微信小程序和百度小程序中存在区别,请分别参考 微信小程序文档 和 百度小程序文档
来源信息 referrerInfo 的数据结构如下
属性 | 类型 | 说明 | 微信小程序 | 百度小程序 | 字节跳动小程序 | 支付宝小程序 |
---|---|---|---|---|---|---|
appId | string | 来源小程序,或者公众号(微信中) | ✔️ | ✔️ | ✔️ | ✔️ |
extraData | Object | 来源小程序传过来的数据,微信和百度小程序在scene=1037或1038时支持 | ✔️ | ✔️ | ✔️ | ✔️ |
sourceServiceId | string | 来源插件,当处于插件运行模式时可见 | ✘ | ✘ | ✘ | ✔️(基础库版本 1.11.0) |
#
componentDidMount()页面初次渲染完成时触发,一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。此生命周期可以访问 Current.router
。此生命周期可以访问 Taro DOM 并且更改 DOM 或添加事件,但无法通过 Taro.createSelectorQuery
查找小程序 DOM。
#
componentDidShow(options)在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应
onShow
,在 H5/RN 中同步实现
程序启动,或从后台进入前台显示时触发,微信小程序中也可以使用 Taro.onAppShow
绑定监听
在此生命周期中通过 Current.router.params
,可以访问到程序初始化参数。
参数与 componentWillMount
中获取的基本一致,但百度小程序中补充两个参数如下
属性 | 类型 | 说明 | 最低版本 |
---|---|---|---|
entryType | string | 展现的来源标识,取值为 user/ schema /sys : user:表示通过home前后 切换或解锁屏幕等方式调起; schema:表示通过协议调起; sys:其它 | 2.10.7 |
appURL | string | 展现时的调起协议,仅当entryType值为 schema 时存在 | 2.10.7 |
#
componentDidHide()在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应
onHide
,在 H5/RN 中同步实现
程序从前台进入后台时触发,微信小程序中也可以使用 Taro.onAppHide
绑定监听
#
componentDidCatchError(String error)在微信/百度/字节跳动/支付宝小程序中这一生命周期方法对应
onError
,H5/RN 中尚未实现
程序发生脚本错误或 API 调用报错时触发,微信小程序中也可以使用 Taro.onError
绑定监听
#
componentDidNotFound(Object)在微信/字节跳动小程序中这一生命周期方法对应
onPageNotFound
,其他端尚未实现
微信小程序中,基础库 1.9.90 开始支持
程序要打开的页面不存在时触发,微信小程序中也可以使用 Taro.onPageNotFound
绑定监听
参数如下
属性 | 类型 | 说明 |
---|---|---|
path | string | 不存在页面的路径 |
query | Object | 打开不存在页面的 query 参数 |
isEntryPage | boolean | 是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面) |
#
页面组件每一个 Taro 应用都至少包括一个页面组件,页面组件可以通过 Taro 路由进行跳转,也可以访问小程序页面的生命周期:
#
配置文件和入口组件一样,对于一个页面文件(例如./pages/index/index.jsx
)而言,我们可以新增一个 ./pages/index/index.config.js
的文件进行页面配置,index.config.js
的默认导出就是页面配置:
#
生命周期#
onReady()页面首次渲染完毕时执行,此生命周期在小程序端对应小程序页面的 onReady
生命周期。从此生命周期开始可以使用 createCanvasContext
或 createselectorquery
等 API 访问真实 DOM。
#
onLoad(options)页面创建时执行,此生命周期在小程序端对应小程序页面的 onLoad
生命周期。此生命周期可以访问 Current.router
。
#
componentWillMount()页面加载时触发,一个页面只会调用一次,此时页面 DOM 尚未准备好,还不能和视图层进行交互
#
componentDidMount()页面初次渲染完成时触发,一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。此生命周期可以访问 Current.router
。此生命周期可以访问 Taro DOM 并且更改 DOM 或添加事件,但无法通过 Taro.createSelectorQuery
查找小程序 DOM。
#
shouldComponentUpdate(nextProps, nextState)页面是否需要更新,返回 false 不继续更新,否则继续走更新流程
#
componentWillUpdate(nextProps, nextState)页面即将更新
#
componentDidUpdate(prevProps, prevState)页面更新完毕
#
componentWillUnmount()页面卸载时触发,如 redirectTo 或 navigateBack 到其他页面时
#
componentDidShow()页面显示/切入前台时触发
#
componentDidHide()页面隐藏/切入后台时触发, 如 navigateTo 或底部 tab 切换到其他页面,小程序切入后台等
在以上所有的生命周期方法中,都可以通过 Current.router.params
获取打开当前页面路径中的参数。
#
页面事件处理函数在小程序中,页面还有在一些专属的事件处理函数,如下
#
onPullDownRefresh()监听用户下拉刷新事件
- 需要在全局配置的 window 选项中或页面配置中开启 enablePullDownRefresh
- 可以通过 Taro.startPullDownRefresh 触发下拉刷新,调用后触发下拉刷新动画,效果与用户手动下拉刷新一致。
- 当处理完数据刷新后,Taro.stopPullDownRefresh 可以停止当前页面的下拉刷新
#
onReachBottom()监听用户上拉触底事件
- 可以在全局配置的 window 选项中或页面配置中设置触发距离 onReachBottomDistance
- 在触发距离内滑动期间,本事件只会被触发一次
#
onPageScroll(Object)监听用户滑动页面事件
Object 参数说明:
参数 | 类型 | 说明 |
---|---|---|
scrollTop | Number | 页面在垂直方向已滚动的距离(单位px) |
注意:请只在需要的时候才在 page 中定义此方法,不要定义空方法。以减少不必要的事件派发对渲染层-逻辑层通信的影响。注意:请避免在 onPageScroll 中过于频繁的执行 this.setState() 等引起逻辑层-渲染层通信的操作。尤其是每次传输大量数据,会影响通信耗时。
#
onShareAppMessage(Object)监听用户点击页面内转发按钮(Button 组件 openType='share')或右上角菜单“转发”按钮的行为,并自定义转发内容。
注意:只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮
Object 参数说明:
参数 | 类型 | 说明 |
---|---|---|
from | String | 转发事件来源。 button:页面内转发按钮; menu:右上角转发菜单 |
target | Object | 如果 from 值是 button ,则 target 是触发这次转发事件的 button ,否则为 undefined |
webViewUrl | String | 页面中包含 WebView 组件时,返回当前 WebView 的url |
此事件需要 return 一个 Object,用于自定义转发内容,返回内容如下:
自定义转发内容
字段 | 类型 | 说明 |
---|---|---|
title | 转发标题 | 当前小程序名称 |
path | 转发路径 | 当前页面 path ,必须是以 / 开头的完整路径 |
imageUrl | 自定义图片路径,可以是本地文件路径、代码包文件路径或者网络图片路径。支持 PNG 及 JPG 。显示图片长宽比是 5:4 | 使用默认截图 |
示例代码
#
onResize(object)只有微信小程序支持
基础库 2.4.0 开始支持
小程序屏幕旋转时触发。详见 响应显示区域变化
#
onTabItemTap(Object)微信小程序中,基础库 1.9.0 开始支持
点击 tab 时触发
Object 参数说明:
参数 | 类型 | 说明 |
---|---|---|
index | String | 被点击 tabItem 的序号,从 0 开始 |
pagePath | String | 被点击 tabItem 的页面路径 |
text | String | 被点击 tabItem 的按钮文字 |
#
componentWillPreload()目前只有微信小程序支持
预加载钩子
#
onTitleClick()只有支付宝小程序支持,基础库 1.3.0 开始支持
点击标题触发
#
onOptionMenuClick()只有支付宝小程序支持,基础库 1.3.0 开始支持
点击导航栏额外图标触发
#
onPopMenuClick()只有支付宝小程序支持,基础库 1.11.0 开始支持
暂无说明
#
onPullIntercept()只有支付宝小程序支持,基础库 1.3.0 开始支持
下拉截断时触发
H5 暂时没有同步实现
onReachBottom
、onPageScroll
这两个事件函数,可以通过给 window 绑定 scroll 事件来进行模拟,而onPullDownRefresh
下拉刷新则暂时只能用ScrollView
组件来代替了。
页面事件函数各端支持程度如下
方法 | 作用 | 微信小程序 | 百度小程序 | 字节跳动小程序 | 支付宝小程序 | H5 | RN |
---|---|---|---|---|---|---|---|
onPullDownRefresh | 页面相关事件处理函数--监听用户下拉动作 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
onReachBottom | 页面上拉触底事件的处理函数 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
onShareAppMessage | 用户点击右上角转发 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
onPageScroll | 页面滚动触发事件的处理函数 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
onTabItemTap | 当前是 tab 页时,点击 tab 时触发 | ✔️ | ✔️ | ✔️ | ✔️ | ✘ | ✘ |
onResize | 页面尺寸改变时触发,详见 响应显示区域变化 | ✔️ | ✘ | ✘ | ✘ | ✘ | ✘ |
componentWillPreload | 预加载 | ✔️ | ✘ | ✘ | ✘ | ✘ | ✘ |
onTitleClick | 点击标题触发 | ✘ | ✘ | ✘ | ✔️ | ✘ | ✘ |
onOptionMenuClick | 点击导航栏额外图标触发 | ✘ | ✘ | ✘ | ✔️(基础库 1.3.0) | ✘ | ✘ |
onPopMenuClick | ✘ | ✘ | ✘ | ✔️(基础库 1.3.0) | ✘ | ✘ | |
onPullIntercept | 下拉截断时触发 | ✘ | ✘ | ✘ | ✔️(基础库 1.11.0) | ✘ | ✘ |
以上成员方法在 Taro 的页面中同样可以使用,书写同名方法即可,不过需要注意的,目前暂时只有小程序端支持(支持程度如上)这些方法,编译到 H5/RN 端后这些方法均会失效。
#
内置组件/PropsTaro 中使用 React,内置组件遵循小程序组件规范,所有内置组件都必须从 @tarojs/components
引入,组件的 Props 遵从大驼峰式命名规范:
#
Taro对应小程序:
#
事件在 Taro 中事件遵从小驼峰式命名规范,所有内置事件名以 on
开头,在事件处理函数中第一个参数是事件本身,可以通过调用 stopPropagation
来阻止冒泡。
#
其它限制由于小程序不支持动态引入,因此小程序中无法使用 React.lazy
API。