Skip to main content
Version: 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,可以访问到页面路由参数。

onReady ()

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

页面首次渲染完毕时执行。从此生命周期开始可以使用 createCanvasContextcreateSelectorQuery 等 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
参数类型说明
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')或右上角菜单“转发”按钮的行为,并自定义转发内容。

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

参数

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,右上角菜单才会显示“分享到朋友圈”按钮。

返回值

事件处理函数可以返回一个 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 的按钮文字

onTitleClick ()

只有支付宝小程序支持

点击标题触发

onOptionMenuClick ()

只有支付宝小程序支持

点击导航栏额外图标触发

onPopMenuClick ()

只有支付宝小程序支持

暂无说明

onPullIntercept ()

只有支付宝小程序支持

下拉截断时触发