页面组件

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

代码示例

• Class Component
• Functional Component

page.js

import React, { Component } from 'react'
import { View } from '@tarojs/components'
class Index extends Component {
  // 可以使用所有的 React 生命周期方法
  componentDidMount () {}
  // onLoad
  onLoad () {}
  // onReady
  onReady () {}
  // 对应 onShow
  componentDidShow () {}
  // 对应 onHide
  componentDidHide () {}
  // 对应 onPullDownRefresh，除了 componentDidShow/componentDidHide 之外，
  // 所有页面生命周期函数名都与小程序相对应
  onPullDownRefresh () {}
  render () {
    return (
      <View className='index' />
    )
  }
}
export default Index

page.js

import React, { useEffect } from 'react'
import { View } from '@tarojs/components'
import {
  useReady,
  useDidShow,
  useDidHide,
  usePullDownRefresh
} from '@tarojs/taro'
function Index () {
  // 可以使用所有的 React Hooks
  useEffect(() => {})
  // 对应 onReady
  useReady(() => {})
  // 对应 onShow
  useDidShow(() => {})
  // 对应 onHide
  useDidHide(() => {})
  // Taro 对所有小程序页面生命周期都实现了对应的自定义 React Hooks 进行支持
  // 详情可查阅：【Hooks】
  usePullDownRefresh(() => {})
  return (
    <View className='index' />
  )
}
export default Index

页面组件配置

请参考 页面配置

生命周期方法

页面组件除了支持 React 的生命周期方法外，还根据小程序的标准，额外支持以下生命周期：

onLoad (options)

在小程序环境中对应页面的 onLoad。

在此生命周期中通过访问 options 参数或调用 getCurrentInstance().router，可以访问到页面路由参数。

onReady ()

在小程序环境中对应页面的 onReady。

从此生命周期开始可以使用 createCanvasContext 或 createSelectorQuery 等 API 访问小程序渲染层的 DOM 节点。

子组件的 onReady

只在页面组件才会触发 onReady 生命周期。子组件可以使用 Taro 内置的消息机制监听页面组件的 onReady() 生命周期：

页面中某个子组件

import React from 'react'
import { View } from '@tarojs/components'
import Taro, { eventCenter, getCurrentInstance } from '@tarojs/taro'
class Test extends React.Component {
  $instance = getCurrentInstance()
  componentWillMount () {
    const onReadyEventId = this.$instance.router.onReady
    eventCenter.once(onReadyEventId, () => {
      console.log('onReady')
      // onReady 触发后才能获取小程序渲染层的节点
      Taro.createSelectorQuery().select('#only')
        .boundingClientRect()
        .exec(res => console.log(res, 'res'))
    })
  }
  render () {
    return (
      <View id="only">
      </View>
    )
  }
}

但是当子组件是按需加载的时候，页面 onReady 早已触发。如果此按需加载的子组件需要获取小程序渲染层的 DOM 节点，因为错过了页面 onReady，只能尝试使用 Taro.nextTick 模拟：

按需加载的子组件

import React from 'react'
import { View } from '@tarojs/components'
import Taro from '@tarojs/taro'
class Test extends React.Component {
  componentDidMount () {
    Taro.nextTick(() => {
      // 使用 Taro.nextTick 模拟 setData 已结束，节点已完成渲染
      Taro.createSelectorQuery().select('#only')
        .boundingClientRect()
        .exec(res => console.log(res, 'res'))
    })
  }
  render () {
    return (
      <View id="only" />
    )
  }
}

componentDidShow ()

在小程序环境中对应页面的 onShow。

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

子组件的 onShow

只在页面组件才会触发 onShow 生命周期。子组件可以使用 Taro 内置的消息机制监听页面组件的 onShow() 生命周期：

页面中某个子组件

import React from 'react'
import { View } from '@tarojs/components'
import { eventCenter, getCurrentInstance } from '@tarojs/taro'
class Test extends React.Component {
  $instance = getCurrentInstance()
  componentWillMount () {
    const onShowEventId = this.$instance.router.onShow
    // 监听
    eventCenter.on(onShowEventId, this.onShow)
  }
  componentWillUnmount () {
    const onShowEventId = this.$instance.router.onShow
    // 卸载
    eventCenter.off(onShowEventId, this.onShow)
  }
  onShow = () => {
    console.log('onShow')
  }
  render () {
    return (
      <View id="only" />
    )
  }
}

componentDidHide ()

在小程序环境中对应页面的 onHide。

页面隐藏/切入后台时触发。

子组件的 onHide

只在页面组件才会触发 onHide 生命周期。子组件可以使用 Taro 内置的消息机制监听页面组件的 onHide() 生命周期：

页面中某个子组件

import React from 'react'
import { View } from '@tarojs/components'
import { eventCenter, getCurrentInstance } from '@tarojs/taro'
class Test extends React.Component {
  $instance = getCurrentInstance()
  componentWillMount () {
    const onHideEventId = this.$instance.router.onHide
    // 监听
    eventCenter.on(onHideEventId, this.onHide)
  }
  componentWillUnmount () {
    const onHideEventId = this.$instance.router.onHide
    // 卸载
    eventCenter.off(onHideEventId, this.onHide)
  }
  onHide = () => {
    console.log('onHide')
  }
  render () {
    return (
      <View id="only" />
    )
  }
}

onPullDownRefresh ()

监听用户下拉动作。

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

onReachBottom ()

监听用户上拉触底事件。

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

H5 暂时没有同步实现，可以通过给 window 绑定 scroll 事件来进行模拟

onPageScroll (Object)

监听用户滑动页面事件。

H5 暂时没有同步实现，可以通过给 window 绑定 scroll 事件来进行模拟

参数

Object

onAddToFavorites (Object)

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

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

参数

Object

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

示例代码

page.js

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

onShareAppMessage (Object)

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

注意：

1. 当 onShareAppMessage 没有触发时，请在页面配置中设置 enableShareAppMessage: true
2. 只有定义了此事件处理函数，右上角菜单才会显示“转发”按钮

参数

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'
    }
  }
}

page.config.js

export default {
  // 当 `onShareAppMessage` 没有触发时，可以尝试配置此选项
  enableShareAppMessage: true
}

onShareTimeline ()

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

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

注意：

1. 当 onShareTimeline 没有触发时，请在页面配置中设置 enableShareTimeline: true
2. 只有定义了此事件处理函数，同时监听了 onShareAppMessage，右上角菜单才会显示“分享到朋友圈”按钮

返回值

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

示例代码

page.js

class Index extends Component {
  onShareAppMessage () {}
  onShareTimeline () {
    console.log('onShareTimeline')
    return {}
  }
}

page.config.js

export default {
  // 当 `onShareAppMessage` 没有触发时，可以尝试配置此选项
  enableShareAppMessage: true,
  // 当 `onShareTimeline` 没有触发时，可以尝试配置此选项
  enableShareTimeline: true
}

onResize (Object)

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

onTabItemTap (Object)

点击 tab 时触发。

参数

Object

onTitleClick ()

只有支付宝小程序支持

点击标题触发

onOptionMenuClick ()

只有支付宝小程序支持

点击导航栏额外图标触发

onPopMenuClick ()

只有支付宝小程序支持

暂无说明

onPullIntercept ()

只有支付宝小程序支持

下拉截断时触发