React
Taro 支持使用 React 进行开发,但和在浏览器中使用 React 稍有不同,具体体现在:
#
入口组件每一个 Taro 应用都需要一个入口组件用来注册应用,入口文件默认是 src
目录下的 app.js
。
在 Taro 中使用 React,入口组件必须导出一个 React 组件。在入口组件中我们可以设置全局状态或访问小程序入口实例的生命周期:
#
入口配置我们可以新增一个 app.config.js
文件进行全局配置,app.config.js
的默认导出就是全局配置。
配置规范基于微信小程序的全局配置进行制定,所有平台进行统一:
注意:
app.config.js
里 require 或 import 引用的 js 文件目前没有经过 Babel 编译语法。- 多端差异化逻辑可以使用
process.env.TARO_ENV
变量作条件判断以实现。
#
onLaunch (options)在小程序环境中对应 app 的
onLaunch
。
在此生命周期中通过访问 options
参数或调用 getCurrentInstance().router
,可以访问到程序初始化参数。
#
参数#
options属性 | 类型 | 说明 |
---|---|---|
path | string | 启动小程序的路径 |
scene | number | 启动小程序的场景值 |
query | Object | 启动小程序的 query 参数 |
shareTicket | string | shareTicket,详见获取更多转发信息 |
referrerInfo | Object | 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {} |
#
options.referrerInfo属性 | 类型 | 说明 |
---|---|---|
appId | string | 来源小程序,或者公众号(微信中) |
extraData | Object | 来源小程序传过来的数据,微信和百度小程序在scene=1037或1038时支持 |
sourceServiceId | string | 来源插件,当处于插件运行模式时可见 |
options 参数的字段在不同小程序中可能存在差异,如:
#
componentDidShow (options)程序启动,或切前台时触发。
和 onLaunch
生命周期一样,在此生命周期中通过访问 options
参数或调用 getCurrentInstance().router
,可以访问到程序初始化参数。
参数与 onLaunch
中获取的基本一致,但百度小程序中补充两个参数如下:
属性 | 类型 | 说明 |
---|---|---|
entryType | string | 展现的来源标识,取值为 user/ schema /sys : user:表示通过home前后 切换或解锁屏幕等方式调起; schema:表示通过协议调起; sys:其它 |
appURL | string | 展现时的调起协议,仅当entryType值为 schema 时存在 |
#
componentDidHide ()程序切后台时触发。
#
onPageNotFound (Object)程序要打开的页面不存在时触发。
#
参数#
Object属性 | 类型 | 说明 |
---|---|---|
path | string | 不存在页面的路径 |
query | Object | 打开不存在页面的 query 参数 |
isEntryPage | boolean | 是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面) |
#
页面组件每一个 Taro 应用都至少包括一个页面组件,页面组件可以通过 Taro 路由进行跳转,也可以访问小程序页面的生命周期。
#
页面配置对于每一个页面文件(例如 ./pages/index/index.jsx
),我们可以新增一个 ./pages/index/index.config.js
的文件进行页面配置,index.config.js
的默认导出就是页面配置。
配置规范基于微信小程序的页面配置进行制定,所有平台进行统一:
注意:
app.config.js
里 require 或 import 引用的 js 文件目前没有经过 Babel 编译语法。- 多端差异化逻辑可以使用
process.env.TARO_ENV
变量作条件判断以实现。
#
路由参数在页面组件中,可以通过 getCurrentInstance().router
获取当前页面的路由参数:
#
生命周期触发机制Taro 3 在小程序逻辑层上实现了一份遵循 Web 标准 BOM 和 DOM API。因此 React 使用的 document.appendChild
、document.removeChild
等 API 其实是 Taro 模拟实现的,最终的效果是把 React 的虚拟 DOM 树渲染为 Taro 模拟的 Web 标准 DOM 树。
因此在 Taro3 中,React 的生命周期触发时机和我们平常在 Web 开发中理解的概念有一些偏差。
#
React 的生命周期React 组件的生命周期方法在 Taro 中都支持使用。
触发时机:
#
1. componentWillMount ()onLoad 之后,页面组件渲染到 Taro 的虚拟 DOM 之前触发。
#
2. componentDidMount ()页面组件渲染到 Taro 的虚拟 DOM 之后触发。
此时能访问到 Taro 的虚拟 DOM(使用 React ref、document.getElementById 等手段),并支持对其进行操作(设置 DOM 的 style 等)。
但此时不代表 Taro 的虚拟 DOM 数据已经完成从逻辑层 setData
到视图层。因此这时无法通过 createSelectorQuery
等方法获取小程序渲染层 DOM 节点。 只能在 onReady 生命周期中获取。
#
小程序页面的方法小程序页面的方法,在 Taro 的页面中同样可以使用:在 Class Component 中书写同名方法、在 Functional Component 中使用对应的 Hooks。
注意:
- 小程序页面方法在各端的支持程度不一。
- 使用了 HOC 包裹的小程序页面组件,必须处理 forwardRef 或使用继承组件的方式而不是返回组件的方式,否则小程序页面方法可能不会被触发。
#
onLoad (options)在小程序环境中对应页面的
onLoad
。
在此生命周期中通过访问 options
参数或调用 getCurrentInstance().router
,可以访问到页面路由参数。
#
onReady ()在小程序环境中对应页面的
onReady
。
从此生命周期开始可以使用 createCanvasContext
或 createSelectorQuery
等 API 访问小程序渲染层的 DOM 节点。
#
子组件的 onReady只在页面组件才会触发 onReady
生命周期。子组件可以使用 Taro 内置的消息机制监听页面组件的 onReady()
生命周期:
但是当子组件是按需加载的时候,页面 onReady
早已触发。如果此按需加载的子组件需要获取小程序渲染层的 DOM 节点,因为错过了页面 onReady
,只能尝试使用 Taro.nextTick
模拟:
#
componentDidShow ()在小程序环境中对应页面的
onShow
。
页面显示/切入前台时触发。
#
子组件的 onShow只在页面组件才会触发 onShow
生命周期。子组件可以使用 Taro 内置的消息机制监听页面组件的 onShow()
生命周期:
#
componentDidHide ()在小程序环境中对应页面的
onHide
。
页面隐藏/切入后台时触发。
#
子组件的 onHide只在页面组件才会触发 onHide
生命周期。子组件可以使用 Taro 内置的消息机制监听页面组件的 onHide()
生命周期:
#
onPullDownRefresh ()监听用户下拉动作。
- 需要在全局配置的 window 选项中或页面配置中设置
enablePullDownRefresh: true
。 - 可以通过 Taro.startPullDownRefresh 触发下拉刷新,调用后触发下拉刷新动画,效果与用户手动下拉刷新一致。
- 当处理完数据刷新后,Taro.stopPullDownRefresh 可以停止当前页面的下拉刷新.
#
onReachBottom ()监听用户上拉触底事件。
- 可以在全局配置的 window 选项中或页面配置中设置触发距离
onReachBottomDistance
。 - 在触发距离内滑动期间,本事件只会被触发一次
H5 暂时没有同步实现,可以通过给 window 绑定 scroll 事件来进行模拟
#
onPageScroll (Object)监听用户滑动页面事件。
H5 暂时没有同步实现,可以通过给 window 绑定 scroll 事件来进行模拟
#
参数#
Object参数 | 类型 | 说明 |
---|---|---|
scrollTop | Number | 页面在垂直方向已滚动的距离(单位px) |
#
onAddToFavorites (Object)监听用户点击右上角菜单“收藏”按钮的行为,并自定义收藏内容。
Taro 3.0.3 版本开始支持。 只有微信小程序支持,本接口为 Beta 版本,安卓 7.0.15 版本起支持,暂只在安卓平台支持。
#
参数#
Object参数 | 类型 | 说明 |
---|---|---|
webviewUrl | String | 页面中包含web-view组件时,返回当前web-view的url |
此事件处理函数需要 return 一个 Object,用于自定义收藏内容:
字段 | 说明 | 默认值 |
---|---|---|
title | 自定义标题 | 页面标题或账号名称 |
imageUrl | 自定义图片,显示图片长宽比为 1:1 | 页面截图 |
query | 自定义query字段 | 当前页面的query |
#
示例代码#
onShareAppMessage (Object)监听用户点击页面内转发按钮(Button 组件 openType='share')或右上角菜单“转发”按钮的行为,并自定义转发内容。
注意:
- 当
onShareAppMessage
没有触发时,请在页面配置中设置enableShareAppMessage: true
- 只有定义了此事件处理函数,右上角菜单才会显示“转发”按钮
#
参数#
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 | 使用默认截图 |
#
示例代码#
onShareTimeline ()监听右上角菜单“分享到朋友圈”按钮的行为,并自定义分享内容。
Taro 3.0.3 版本开始支持 只有微信小程序支持,基础库 2.11.3 开始支持,本接口为 Beta 版本,暂只在 Android 平台支持
注意:
- 当
onShareTimeline
没有触发时,请在页面配置中设置enableShareTimeline: true
- 只有定义了此事件处理函数,右上角菜单才会显示“分享到朋友圈”按钮
#
返回值事件处理函数可以返回一个 Object,用于自定义分享内容,不支持自定义页面路径,返回内容如下:
字段 | 说明 | 默认值 |
---|---|---|
title | 自定义标题 | 当前小程序名称 |
query | 自定义页面路径中携带的参数 | 当前页面路径携带的参数 |
imageUrl | 自定义图片路径,可以是本地文件或者网络图片。支持 PNG 及 JPG,显示图片长宽比是 1:1。 | 默认使用小程序 Logo |
#
onResize (Object)小程序屏幕旋转时触发。详见 响应显示区域变化。
#
onTabItemTap (Object)点击 tab 时触发。
#
参数#
Object参数 | 类型 | 说明 |
---|---|---|
index | String | 被点击 tabItem 的序号,从 0 开始 |
pagePath | String | 被点击 tabItem 的页面路径 |
text | String | 被点击 tabItem 的按钮文字 |
#
onTitleClick ()只有支付宝小程序支持
点击标题触发
#
onOptionMenuClick ()只有支付宝小程序支持
点击导航栏额外图标触发
#
onPopMenuClick ()只有支付宝小程序支持
暂无说明
#
onPullIntercept ()只有支付宝小程序支持
下拉截断时触发
#
内置组件Taro 中使用小程序规范的内置组件进行开发,如 <View />
、<Text />
、<Button />
等。
在 React 中使用这些内置组件前,必须从 @tarojs/components
进行引入,组件的 props 遵从大驼峰式命名规范:
小程序写法:
对应 Taro 的写法:
#
事件在 Taro 中事件遵从小驼峰式(camelCase)命名规范,所有内置事件名以 on
开头。
在事件回调函数中,第一个参数是事件本身,回调中调用 stopPropagation
可以阻止冒泡。
#
Taro 3 在小程序端的事件机制在 Taro 1 & 2 中,Taro 会根据开发者是否使用了 e.stopPropagation()
,来决定在小程序模板中绑定的事件是以 bind
还是以 catch
形式。因此事件冒泡是由小程序控制的。
但是在 Taro 3,我们在小程序逻辑层实现了一套事件系统,包括事件触发和事件冒泡。在小程序模板中绑定的事件都是以 bind
的形式。
一般情况下,这套在逻辑层实现的小程序事件系统是可以正常工作的,事件回调能正确触发、冒泡、停止冒泡。
但是,小程序模板中绑定的 catchtouchmove
事件除了可以阻止回调函数冒泡触发外,还能阻止视图的滚动穿透,这点 Taro 的事件系统是做不到的。
#
阻止滚动穿透上一点中,我们介绍了 Taro 3 的事件机制。因为事件都以 bind
的形式进行绑定,因此不能使用 e.stopPropagation()
阻止滚动穿透。
针对滚动穿透,目前总结了两种解决办法:
#
一、样式使用样式解决:禁止被穿透的组件滚动。
这也是最推荐的做法。
#
二、catchMoveTaro 3.0.21 版本开始支持
但是地图组件本身就是可以滚动的,即使固定了它的宽高。所以第一种办法处理不了冒泡到地图组件上的滚动事件。
这时候可以为 View
组件增加 catchMove 属性:
#
Hooks#
其它限制- 由于小程序不支持动态引入,因此小程序中无法使用
React.lazy
API。 - 所有组件的
id
必须在整个应用中保持唯一(即使他们在不同的页面),否则可能导致事件不触发的问题,#7317