Version: 2.x

框架

项目目录结构#

├── dist                   编译结果目录
├── config                 配置目录
|   ├── dev.js             开发时配置
|   ├── index.js           默认配置
|   └── prod.js            打包时配置
├── src                    源码目录
|   ├── pages              页面文件目录
|   |   ├── index          index 页面目录
|   |   |   ├── index.js   index 页面逻辑
|   |   |   └── index.css  index 页面样式
|   ├── app.css            项目总通用样式
|   └── app.js             项目入口文件
└── package.json

入口文件#

入口文件默认是 src 目录下的 app.js。

代码示例#

一个普通的入口文件示例如下

import Taro, { Component } from '@tarojs/taro'
import Index from './pages/index'

import './app.scss'

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index'
    ],
    window: {
      backgroundTextStyle: 'light',
      navigationBarBackgroundColor: '#fff',
      navigationBarTitleText: 'WeChat',
      navigationBarTextStyle: 'black'
    }
  }

  componentWillMount () {}

  componentDidMount () {}

  componentDidShow () {}

  componentDidHide () {}

  render () {
    return (
      <Index />
    )
  }
}

可以看出入口文件也是 React 风格的写法，首先需要引用依赖 @tarojs/taro，这是 Taro 方案的基础框架，在这里我们继承了 Component 组件基类。

全局配置#

通常入口文件会包含一个 config 配置项，这个配置是整个应用的全局的配置，配置规范基于微信小程序的全局配置进行制定，所有平台进行统一。

入口文件中的全局配置，在编译后将生成全局配置文件 app.json。

配置项列表#

Taro 中全局配置所包含的配置项及各端支持程度如下

属性	类型	必填	描述	微信小程序	百度小程序	字节跳动小程序	支付宝小程序	H5	RN
pages	String Array	是	页面路径列表	✔️	✔️	✔️	✔️	✔️	✔️
window	Object	否	全局的默认窗口表现	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方
tabBar	Object	否	底部 tab 栏的表现	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方	具体支持程度见下方
networkTimeout	Object	否	网络超时时间	✔️	✘	✘	✘	✘	✘
debug	Boolean	否	是否开启 debug 模式，默认关闭	✔️	✘	✔️	✘	✘	✘
functionalPages	Boolean	否	是否启用插件功能页，默认关闭	✔️（基础库 2.1.0 以上）	✘	✘	✘	✘	✘
subPackages	Object Array	否	分包结构配置	✔️（基础库 1.7.3 以上）	✔️	✘	✘	✔️	✔️
workers	String	否	Worker 代码放置的目录	✔️（基础库 1.9.90 以上）	✘	✘	✘	✘	✘
requiredBackgroundModes	String Array	否	需要在后台使用的能力，如「音乐播放」	✔️	✘	✘	✘	✘	✘
plugins	Object	否	使用到的插件	✔️（基础库 1.9.6 以上）	✘	✘	✘	✘	✘
preloadRule	Object	否	分包预下载规则	✔️（基础库 2.3.0 以上）	✔️	✘	✘	✘	✘
resizable	Boolean	否	iPad 小程序是否支持屏幕旋转，默认关闭	✔️（基础库 2.3.0 以上）	✘	✘	✘	✘	✘
navigateToMiniProgramAppIdList	String Array	否	需要跳转的小程序列表，详见 wx.navigateToMiniProgram	✔️（基础库 2.4.0 以上）	✘	✘	✘	✘	✘
usingComponents	Object	否	全局自定义组件配置	✔️（开发者工具 1.02.1810190）	✘	✘	✘	✘	✘
permission	Object	否	小程序接口权限相关设置	✔️ 微信客户端 7.0.0	✘	✘	✘	✘	✘

pages#

用于指定小程序由哪些页面组成，每一项都对应一个页面的 路径 + 文件名 信息。文件名不需要写文件后缀，框架会自动去寻找对应位置的文件进行处理。

数组的第一项代表小程序的初始页面（首页）。小程序中新增/减少页面，都需要对 pages 数组进行修改。

如开发目录为：

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils

则需要在入口文件配置中写

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ]
  }
  ...
}

window#

用于设置小程序的状态栏、导航条、标题、窗口背景色，其配置项如下。

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor（十六进制颜色值）	#000000	导航栏背景颜色，如 #000000
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持 black / white
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持以下值：default 默认样式；custom 自定义导航栏，只保留右上角胶囊按钮
backgroundColor	String		窗口的背景色
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark / light
backgroundColorTop	String	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	String	#ffffff	底部窗口的背景色，仅 iOS 支持
enablePullDownRefresh	boolean	false	是否开启当前页面的下拉刷新。
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位为 px
pageOrientation	String	portrait	屏幕旋转设置，支持 auto / portrait / landscape 详见响应显示区域变化

各端支持程度如下

属性	微信小程序	百度小程序	字节跳动小程序	支付宝小程序	H5	RN
navigationBarBackgroundColor	✔️	✔️	✔️	✔️	✔️	✔️
navigationBarTextStyle	✔️	✔️	✔️	✘	✔️	✔️
navigationBarTitleText	✔️	✔️	✔️	✔️	✔️	✔️
navigationStyle	✔️（微信客户端 6.6.0）	✔️（百度 App 版本 11.1.0）	✔️	✘	✘	✘
backgroundColor	✔️	✔️	✔️	✘	✘	✔️
backgroundTextStyle	✔️	✔️	✔️	✘	✘	✘
backgroundColorTop	✔️（微信客户端 6.5.16）	✘	✔️	✘	✘	✘
backgroundColorBottom	✔️（微信客户端 6.5.16）	✘	✔️	✘	✘	✘
enablePullDownRefresh	✔️	✔️	✔️	✔️	✘	✘
onReachBottomDistance	✔️	✔️	✔️	✘	✘	✘
pageOrientation	✔️2.4.0 (auto) / 2.5.0 (landscape)	✘	✘	✘	✘	✘

::: 微信小程序中，关于navigationStyle

客户端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。
客户端 6.7.2 版本开始，navigationStyle: custom 对 <web-view> 组件无效
开启 custom 后，低版本客户端需要做好兼容。开发者工具基础库版本切到 1.7.0（不代表最低版本，只供调试用）可方便切到旧视觉 :::

配置示例如下：

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    window: {
      navigationBarBackgroundColor: '#ffffff',
      navigationBarTextStyle: 'black',
      navigationBarTitleText: '微信接口功能演示',
      backgroundColor: '#eeeeee',
      backgroundTextStyle: 'light'
    }
  }
  ...
}

tabBar#

如果小程序是一个多 tab 应用（客户端窗口的底部或顶部有 tab 栏可以切换页面），可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。

其配置项如下

属性	类型	必填	默认值	描述
color	HexColor（十六进制颜色值）	是		tab 上的文字默认颜色，仅支持十六进制颜色
selectedColor	HexColor（十六进制颜色值）	是		tab 上的文字选中时的颜色，仅支持十六进制颜色
backgroundColor	HexColor（十六进制颜色值）	是		tab 的背景色，仅支持十六进制颜色
borderStyle	String	是	black	tabbar 上边框的颜色，仅支持 black / white
list	Array	是		tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab
position	String	否	bottom	tabBar的位置，仅支持 bottom / top
custom	Boolean	否	false	自定义 tabBar

各端支持程度如下

属性	微信小程序	百度小程序	字节跳动小程序	支付宝小程序	H5	RN
color	✔️	✔️	✔️	✔️	✔️	✔️
selectedColor	✔️	✔️	✔️	✔️	✔️	✔️
backgroundColor	✔️	✔️	✔️	✔️	✔️	✔️
borderStyle	✔️	✔️	✔️	✘	✔️	✔️
list	✔️	✔️	✔️	✔️	✔️	✔️
position	✔️	✘	✔️	✘	✘	✘
custom	✔️（基础库 2.5.0 以上）	✘	✘	✘	✘	✘

其中 list 接受一个数组，只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序，每个项都是一个对象，其属性值如下：

属性	类型	必填	描述
pagePath	String	是	页面路径，必须在 pages 中先定义
text	String	是	tab 上按钮文字
iconPath	String	否	图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px，不支持网络图片。当 position 为 top 时，不显示 icon。
selectedIconPath	String	否	选中时的图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px，不支持网络图片。当 position 为 top 时，不显示 icon。

networkTimeout#

只在微信小程序上支持

各类网络请求的超时时间，单位均为毫秒。

属性	类型	必填	默认值	描述
request	Number	否	60000	Taro.request 的超时时间，单位：毫秒
connectSocket	Number	否	60000	Taro.connectSocket 的超时时间，单位：毫秒
uploadFile	Number	否	60000	Taro.uploadFile 的超时时间，单位：毫秒
downloadFile	Number	否	60000	Taro.downloadFile 的超时时间，单位：毫秒

debug#

可以在开发者工具中开启 debug 模式，在开发者工具的控制台面板，调试信息以 info 的形式给出，其信息有 Page 的注册，页面路由，数据更新，事件触发等。可以帮助开发者快速定位一些常见的问题。

functionalPages#

微信小程序基础库 2.1.0 开始支持

启用插件功能页时，插件所有者小程序需要设置其 functionalPages 为 true

subPackages#

微信客户端 6.6.0 ，基础库 1.7.3 及以上版本支持
百度小程序支持
H5 和 RN 会把 subPackages 合入 pages

启用分包加载时，声明项目分包结构

workers#

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

使用 Worker 处理多线程任务时，设置 Worker 代码放置的目录

requiredBackgroundModes#

微信客户端 6.7.2 及以上版本支持

申明需要后台运行的能力，类型为数组。目前支持以下项目：

audio: 后台音乐播放

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    requiredBackgroundModes: ['audio']
  }
  ...
}

注：在此处申明了后台运行的接口，开发版和体验版上可以直接生效，正式版还需通过审核。

plugins#

微信小程序基础库 1.9.6 开始支持

声明小程序需要使用的插件

preloadRule#

微信小程序基础库 2.3.0 开始支持

声明分包预下载的规则

微信小程序文档百度小程序文档

resizable#

微信小程序基础库 2.3.0 开始支持

在 iPad 上运行的小程序可以设置支持屏幕旋转

navigateToMiniProgramAppIdList#

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

当小程序需要使用 Taro.navigateToMiniProgram 接口跳转到其他小程序时，需要先在配置文件中声明需要跳转的小程序 appId 列表，最多允许填写 10 个

usingComponents#

微信开发者工具 1.02.1810190 及以上版本支持

在此处声明的自定义组件视为全局自定义组件，在小程序内的页面或自定义组件中可以直接使用而无需再声明

permission#

微信客户端 7.0.0 及以上版本支持

微信小程序接口权限相关设置。字段类型为 Object，结构为：

属性	类型	必填	默认值	描述
scope.userLocation	PermissionObject	否		位置相关权限声明

PermissionObject 结构

属性	类型	必填	默认值	描述
desc	string	是		小程序获取权限时展示的接口用途说明。最长 30 个字符

class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    permission: {
      'scope.userLocation': {
        desc: '你的位置信息将用于小程序位置接口的效果展示'
      }
    }
  }
  ...
}

生命周期#

而且由于入口文件继承自 Component 组件基类，它同样拥有组件生命周期，但因为入口文件的特殊性，他的生命周期并不完整，具体如下

componentWillMount()#

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

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

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

参数格式如下

属性	类型	说明	微信小程序	百度小程序	字节跳动小程序	支付宝小程序	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()#

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

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

在此生命周期中也可以通过 this.$router.params，访问到程序初始化参数，与 componentWillMount 中一致

componentDidShow()#

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

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

在此生命周期中通过 this.$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.getApp(Object)#

可以用来获取到程序 App 实例，在各个端均有实现

微信小程序端可以传入一个 Object 参数，格式如下

属性	类型	说明	基础库最低版本
allowDefault	Boolean	在 App 未定义时返回默认实现。当App被调用时，默认实现中定义的属性会被覆盖合并到App中。一般用于独立分包	2.2.4

入口文件 render 方法说明#

入口文件需要包含一个 render 方法，一般返回程序的第一个页面，但值得注意的是不要在入口文件中的 render 方法里写逻辑及引用其他页面、组件，因为编译时 render 方法的内容会被直接替换掉，你的逻辑代码不会起作用。

页面#

Taro 项目的页面一般都放在 src 中的 pages 目录下，如果页面包含 js 以及 css，建议页面以文件夹的形式进行组织，例如 index 页面包含 index.js 和 index.scss，则在 pages 目录下新建 index 目录。

指定页面#

页面创建好后如果需要渲染展示，则需要在项目入口文件 app.js 中 config 的 pages 数组中进行指定，例如上面提到的 index 页面，需要如下进行配置，页面配置需要指定到页面具体的 js 文件，可以不带 .js 后缀

// ...
class App extends Component {
  // 项目配置
  config = {
    pages: [
      'pages/index/index'
    ]
  }
  // ...
}

代码示例#

一个普通的页面文件示例如下

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

export default class Index extends Component {
  config = {
    navigationBarTitleText: '首页'
  }

  componentWillMount () { }

  componentDidMount () { }

  componentWillUnmount () { }

  componentDidShow () { }

  componentDidHide () { }

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

页面配置#

Taro 的页面同样是继承自 Component 组件基类，每一个页面都拥有自己配置 config，这个配置是针对当前页面配置，配置规范基于微信小程序的页面配置进行制定，所有平台进行统一。

页面文件中的 config 配置，在编译后将生成全局配置文件 app.json。

页面的配置只能设置全局配置中部分 window 配置项的内容，页面中配置项会覆盖全局配置的 window 中相同的配置项。

配置示例：

export default class Index extends Component {
  config = {
    navigationBarBackgroundColor: '#ffffff',
    navigationBarTextStyle: 'black',
    navigationBarTitleText: '首页',
    backgroundColor: '#eeeeee',
    backgroundTextStyle: 'light'
  }

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

配置项列表#

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor（十六进制颜色值）	#000000	导航栏背景颜色，如 #000000
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持 black / white
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持以下值：default 默认样式；custom 自定义导航栏，只保留右上角胶囊按钮
backgroundColor	String		窗口的背景色
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark / light
backgroundColorTop	String	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	String	#ffffff	底部窗口的背景色，仅 iOS 支持
enablePullDownRefresh	boolean	false	是否开启当前页面的下拉刷新。
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位为 px
pageOrientation	String	portrait	屏幕旋转设置，支持 auto / portrait / landscape 详见响应显示区域变化
disableScroll	Boolean	false	设置为 true 则页面整体不能上下滚动。只在页面配置中有效，无法在 app.json 中设置
disableSwipeBack	Boolean	false	禁止页面右滑手势返回
usingComponents	Object	否	页面自定义组件配置

各端支持程度如下

属性	微信小程序	百度小程序	字节跳动小程序	支付宝小程序	H5	RN
navigationBarBackgroundColor	✔️	✔️	✔️	✔️	✔️	✔️
navigationBarTextStyle	✔️	✔️	✔️	✘	✔️	✔️
navigationBarTitleText	✔️	✔️	✔️	✔️	✔️	✔️
navigationStyle	✔️（微信客户端 6.6.0）	✔️（百度 App 版本 11.1.0）	✔️	✘	✘	✔️
backgroundColor	✔️	✔️	✔️	✘	✘	✔️
backgroundTextStyle	✔️	✔️	✔️	✘	✘	✔️
backgroundColorTop	✔️（微信客户端 6.5.16）	✘	✔️	✘	✘	✘
backgroundColorBottom	✔️（微信客户端 6.5.16）	✘	✔️	✘	✘	✘
enablePullDownRefresh	✔️	✔️	✔️	✔️	✘	✘
onReachBottomDistance	✔️	✔️	✔️	✘	✘	✘
pageOrientation	✔️2.4.0 (auto) / 2.5.0 (landscape)	✘	✘	✘	✘	✘
disableScroll	✔️	✘	✘	✘	✘	✔️
disableSwipeBack	✔️	✘	✘	✘	✘	✘
usingComponents	✔️	✔️	✔️	✔️	✘	✘

其中，usingComponents 一般不需要配置，只有在需要与引用原生小程序组件的时候才需要配置。

页面说明#

页面的样式文件建议放在与页面 JS 的同级目录下，然后通过 ES6 规范 import 进行引入，支持使用 CSS 预编译处理器，目前提供了 sass 预编译插件 @tarojs/plugin-sass，需要自行在本地进行安装。

页面 JS 要求必须有一个 render 函数，函数返回 JSX 代码，具体 JSX 代码的写法请参考 JSX 章节。

生命周期#

由于页面 JS 也继承自 Component 组件基类，所以页面同样拥有生命周期，页面的生命周期方法如下：

componentWillMount()#

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

componentDidMount()#

页面初次渲染完成时触发，一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互

shouldComponentUpdate(nextProps, nextState)#

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

componentWillUpdate(nextProps, nextState)#

页面即将更新

componentDidUpdate(prevProps, prevState)#

页面更新完毕

componentWillUnmount()#

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

componentDidShow()#

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

componentDidHide()#

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

在以上所有的生命周期方法中，都可以通过 this.$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	使用默认截图

示例代码

export default class Index extends Component {
  config = {
    navigationBarTitleText: '首页'
  }

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

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

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 端后这些方法均会失效。

组件#

Taro 支持组件化开发，组件代码可以放在任意位置，不过建议放在 src 下的 components 目录中。一个组件通常包含组件 JS 文件以及组件样式文件，组织方式与页面类似。

组件配置#

一般来说，Taro 组件不需要任何配置，但当你在 Taro 组件中引用原生小程序组件代码时，则需要通过配置 config 来实现。

配置项如下

属性	类型	必填	描述
usingComponents	Object	否	组件自定义组件配置

usingComponents 中通过 组件名: 组件相对路径 这种 key/value 的方式定义引用的组件。

代码示例#

import Taro, { Component } from '@tarojs/taro'
import { View, Image, Button } from '@tarojs/components'
import './tab.scss'

class Tab extends Component {

  onNewTodo = () => {
    // dosth
  }

  componentWillMount () { }

  componentDidMount () { }

  componentWillUnmount () { }

  componentWillReceiveProps () { }

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

组件说明#

组件的样式文件可以需要在组件中通过 import 语法进行引入。

Taro 的组件同样是继承自 Component 组件基类，与页面类似，组件也必须包含一个 render 函数，返回 JSX 代码。

生命周期#

由于组件 JS 也继承自 Component 组件基类，所以页面同样拥有生命周期，页面的生命周期方法如下：

componentWillMount()#

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

componentDidMount()#

组件初次渲染完成时触发，一个组件只会调用一次，代表组件已经准备妥当，可以和视图层进行交互

componentWillReceiveProps(nextProps)#

已经装载的组件接收到新属性前调用

shouldComponentUpdate(nextProps, nextState)#

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

componentWillUpdate(nextProps, nextState)#

组件即将更新

componentDidUpdate(prevProps, prevState)#

组件更新完毕

componentWillUnmount()#

组件卸载时触发

具体生命周期的使用以及组件类的说明可以查看组件说明章节。