页面组件

每一个 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>

page.vue

<template>
  <view class="index">
    <text>{{ msg }}</text>
  </view>
</template>
<script>
import { ref } from 'vue'
export default {
  // 可以使用所有的 Vue 生命周期方法
  mounted () {},
  // onLoad
  onLoad () {},
  // onReady
  onReady () {},
  // 对应 onShow
  onShow () {},
  // 对应 onHide
  onHide () {},
  // 对应 onPullDownRefresh
  onPullDownRefresh () {},
  setup () {
    const msg = ref('Hello world')
    return {
      msg
    }
  }
}
</script>

页面组件配置

请参考 页面配置

生命周期方法

在 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

onAddToFavorites (Object)

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

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

参数

Object

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

示例代码

page.vue

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

onShareAppMessage (Object)

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

注意：只有定义了此事件处理函数，右上角菜单才会显示“转发”按钮。

参数

Object

此事件需要 return 一个 Object，用于自定义转发内容，返回内容如下：

自定义转发内容

示例代码

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，用于自定义分享内容，不支持自定义页面路径，返回内容如下：

示例代码

page.vue

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

onResize (Object)

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

onTabItemTap (Object)

点击 tab 时触发。

参数

Object

onTitleClick ()

只有支付宝小程序支持

点击标题触发

onOptionMenuClick ()

只有支付宝小程序支持

点击导航栏额外图标触发

onPopMenuClick ()

只有支付宝小程序支持

暂无说明

onPullIntercept ()

只有支付宝小程序支持

下拉截断时触发