跳到主要内容
版本：3.x

页面组件

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

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

代码示例​

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，可以访问到页面路由参数。

onUnload ()​

信息

Taro v3.4.7 开始支持。

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

一般情况下建议使用 Vue 的 onUnmounted 生命周期处理页面卸载时的逻辑。当某些特殊情况需要在页面的 onUnload 的同一个事件循环中实现逻辑时才使用它（如对小程序的生命周期执行顺序有强依赖关系时）。

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.on(getCurrentInstance().router.onShow, () => {
        console.log('onShow')
      })
    }
  }
</script>

onHide ()​

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

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

子组件的 onHide​

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

页面中某个子组件
<script>
  import { eventCenter, getCurrentInstance } from '@tarojs/taro'

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

onPullDownRefresh ()​

监听用户下拉动作。

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

onReachBottom ()​

监听用户上拉触底事件。

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

需要 enablePullDownRefresh 配置

onPageScroll (Object)​

监听用户滑动页面事件。

需要 enablePullDownRefresh 配置

参数​

Object​
参数类型说明
scrollTopNumber页面在垂直方向已滚动的距离（单位 px）

onAddToFavorites (Object)​

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

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

参数​

Object​
参数类型说明
webviewUrlString页面中包含 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'）或右上角菜单“转发”按钮的行为，并自定义转发内容。

注意：只有定义了此事件处理函数，右上角菜单才会显示“转发”按钮。对于某些特殊写法，如果定义了此事件处理函数后“转发”按钮还是不可点击，请在该页面配置中设置 enableShareAppMessage: true。

参数​

Object​
参数类型说明
fromString转发事件来源。
button：页面内转发按钮；
menu：右上角转发菜单
targetObject如果 from 值是 button，则 target 是触发这次转发事件的 button，否则为 undefined
webViewUrlString页面中包含 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，右上角菜单才会显示“分享到朋友圈”按钮。对于某些特殊写法，如果定义了此事件处理函数后“分享到朋友圈”按钮还是不可点击，请在该页面配置中设置 enableShareTimeline: true。

返回值​

事件处理函数可以返回一个 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​
参数类型说明
indexString被点击 tabItem 的序号，从 0 开始
pagePathString被点击 tabItem 的页面路径
textString被点击 tabItem 的按钮文字

onSaveExitState​

信息

Taro v3.5.0+ 开始支持

每当小程序可能被销毁之前，页面回调函数 onSaveExitState 会被调用，可以进行退出状态的保存。

只有微信小程序支持，基础库 2.7.4 开始支持。

onTitleClick ()​

只有支付宝小程序支持

点击标题触发

onOptionMenuClick ()​

只有支付宝小程序支持

点击导航栏额外图标触发

onPopMenuClick ()​

只有支付宝小程序支持

暂无说明

onPullIntercept ()​

只有支付宝小程序支持

下拉截断时触发