页面组件
每一个 Taro 应用都至少包括一个页面组件,页面组件可以通过 Taro 路由进行跳转,也可以访问小程序页面的生命周期。
每一个页面组件必须是一个 .vue
文件。
代码示例
- Vue2
- Vue3
<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>
<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
,可以访问到页面路由参数。
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
参数 | 类型 | 说明 |
---|---|---|
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 |
示例代码
<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
参数 | 类型 | 说明 |
---|---|---|
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 | 使用默认截图 |
示例代码
<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 |
示例代码
<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 的按钮文字 |
onSaveExitState
Taro v3.5.0+ 开始支持
每当小程序可能被销毁之前,页面回调函数 onSaveExitState
会被调用,可以进行退出状态的保存。
只有微信小程序支持,基础库 2.7.4 开始支持。
onTitleClick ()
只有支付宝小程序支持
点击标题触发
onOptionMenuClick ()
只有支付宝小程序支持
点击导航栏额外图标触发
onPopMenuClick ()
只有支付宝小程序支持
暂无说明
onPullIntercept ()
只有支付宝小程序支持
下拉截断时触发