Version: 3.x

页面组件

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

每一个页面组件必须是一个 .vue 文件。

代码示例#

Vue2
Vue3

page.vue

<template>
  <view class="index"></view>
</template>

<script>
export default {
  name: 'Index',

  // 可以使用所有的 Vue 生命周期方法
  mounted () {},

  // onLoad
  onLoad () {},

  // onReady
  onReady () {},

  // 对应 onShow
  onShow () {},

  // 对应 onHide
  onHide () {},

  // 对应 onPullDownRefresh
  onPullDownRefresh () {}
}
</script>

<style>
.index {}
</style>

页面组件配置#

请参考页面配置

生命周期方法#

在 Vue2 和 Vue3 中，Taro 额外添加的生命周期方法的写法一致

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

onLoad (options)#

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

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

onReady ()#

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

页面首次渲染完毕时执行。从此生命周期开始可以使用 createCanvasContext 或 createSelectorQuery 等 API 访问小程序渲染层的 DOM 节点。

子组件的 onReady#

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

页面中某个子组件

<template>
  <view id="only" />
</template>

<script>
  import Taro, { eventCenter, getCurrentInstance } from '@tarojs/taro'

  export default {
    mounted () {
      eventCenter.once(getCurrentInstance().router.onReady, () => {
        console.log('onReady')

        // onReady 触发后才能获取小程序渲染层的节点
        Taro.createSelectorQuery().select('#only')
          .boundingClientRect()
          .exec(res => console.log('res: ', res))
      })
    }
  }
</script>

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

按需加载的子组件

<template>
  <view id="only" />
</template>

<script>
  import Taro from '@tarojs/taro'

  export default {
    mounted () {
      Taro.nextTick(() => {
        // 使用 Taro.nextTick 模拟 setData 已结束，节点已完成渲染
        Taro.createSelectorQuery().select('#only')
          .boundingClientRect()
          .exec(res => console.log('res: ', res))
      })
    }
  }
</script>

onShow ()#

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

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

子组件的 onShow#

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

页面中某个子组件

<script>
  import { eventCenter, getCurrentInstance } from '@tarojs/taro'

  export default {
    mounted () {
      eventCenter.once(getCurrentInstance().router.onShow, () => {
        console.log('onShow')
      })
    }
  }
</script>

onHide ()#

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

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

子组件的 onHide#

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

页面中某个子组件

<script>
  import { eventCenter, getCurrentInstance } from '@tarojs/taro'

  export default {
    mounted () {
      eventCenter.once(getCurrentInstance().router.onHide, () => {
        console.log('onHide')
      })
    }
  }
</script>

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

示例代码#

page.vue

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

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	使用默认截图

示例代码#

page.vue

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

onShareTimeline ()#

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

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

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

返回值#

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

字段	说明	默认值
title	自定义标题	当前小程序名称
query	自定义页面路径中携带的参数	当前页面路径携带的参数
imageUrl	自定义图片路径，可以是本地文件或者网络图片。支持 PNG 及 JPG，显示图片长宽比是 1:1。	默认使用小程序 Logo

示例代码#

page.vue

<script>
  export default {
    onShareAppMessage () {},
    onShareTimeline () {
      console.log('onShareTimeline')
      return {}
    }
  }
</script>

onResize (Object)#

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

onTabItemTap (Object)#

点击 tab 时触发。

参数#

Object#

参数	类型	说明
index	String	被点击 tabItem 的序号，从 0 开始
pagePath	String	被点击 tabItem 的页面路径
text	String	被点击 tabItem 的按钮文字

onTitleClick ()#

只有支付宝小程序支持

点击标题触发

onOptionMenuClick ()#

只有支付宝小程序支持

点击导航栏额外图标触发

onPopMenuClick ()#

只有支付宝小程序支持

暂无说明

onPullIntercept ()#

只有支付宝小程序支持

下拉截断时触发