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
  • 在触发距离内滑动期间,本事件只会被触发一次

需要 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 的按钮文字

onTitleClick ()

只有支付宝小程序支持

点击标题触发

onOptionMenuClick ()

只有支付宝小程序支持

点击导航栏额外图标触发

onPopMenuClick ()

只有支付宝小程序支持

暂无说明

onPullIntercept ()

只有支付宝小程序支持

下拉截断时触发