Taro Hooks 完整分类详解
Taro 提供了一系列强大的 Hooks 来帮助开发者更好地管理小程序和 H5 应用的生命周期、用户交互和系统事件。本文将按照功能类型对这些 Hooks 进行详细分类讲解。
📱 生命周期类 Hooks
页面生命周期
useLoad
页面加载时触发,只会触发一次。可以在此获取页面参数。
typescript
import { useLoad } from '@tarojs/taro'
useLoad((options) => {
console.log('页面加载完成', options)
// 获取页面参数
const { id } = options
})
useReady
页面初次渲染完成时触发,只会触发一次。
typescript
import { useReady } from '@tarojs/taro'
useReady(() => {
console.log('页面渲染完成')
// 可以安全地获取节点信息
})
useUnload
页面卸载时触发,如 redirectTo 或 navigateBack 到其他页面时。
typescript
import { useUnload } from '@tarojs/taro'
useUnload(() => {
console.log('页面即将卸载')
// 清理定时器、取消请求等
})
应用生命周期
useLaunch
小程序初始化完成时触发,全局只触发一次。
typescript
import { useLaunch } from '@tarojs/taro'
useLaunch((options) => {
console.log('小程序启动', options)
// 初始化全局数据
})
useDidShow
页面显示/切入前台时触发。
typescript
import { useDidShow } from '@tarojs/taro'
useDidShow(() => {
console.log('页面显示')
// 刷新数据、恢复播放器等
})
useDidHide
页面隐藏/切入后台时触发。
typescript
import { useDidHide } from '@tarojs/taro'
useDidHide(() => {
console.log('页面隐藏')
// 暂停播放、保存状态等
})
👆 用户交互类 Hooks
滚动相关
usePageScroll
监听用户滑动页面事件。
typescript
import { usePageScroll } from '@tarojs/taro'
usePageScroll((res) => {
console.log('滚动位置', res.scrollTop)
// 实现吸顶效果、懒加载等
})
useReachBottom
页面上拉触底事件的处理函数。
typescript
import { useReachBottom } from '@tarojs/taro'
useReachBottom(() => {
console.log('到达页面底部')
// 加载更多数据
loadMoreData()
})
usePullDownRefresh
监听用户下拉刷新事件。
typescript
import { usePullDownRefresh } from '@tarojs/taro'
usePullDownRefresh(() => {
console.log('触发下拉刷新')
// 刷新数据
refreshData().then(() => {
Taro.stopPullDownRefresh()
})
})
usePullIntercept
下拉截断时触发(仅微信小程序支持)。
typescript
import { usePullIntercept } from '@tarojs/taro'
usePullIntercept(() => {
console.log('下拉被截断')
// 可以在此处理自定义下拉刷新逻辑
})
点击事件
useTabItemTap
点击 tab 时触发(仅 TabBar 页面)。
typescript
import { useTabItemTap } from '@tarojs/taro'
useTabItemTap((item) => {
console.log('点击了 tab', item.index, item.pagePath)
// 可以在此处理 tab 点击逻辑
})
useTitleClick
点击标题时触发(仅支付宝小程序支持)。
typescript
import { useTitleClick } from '@tarojs/taro'
useTitleClick(() => {
console.log('点击了标题')
// 可以在此处理标题点击逻辑
})
useOptionMenuClick
点击导航栏额外图标时触发(仅支付宝小程序支持)。
typescript
import { useOptionMenuClick } from '@tarojs/taro'
useOptionMenuClick(() => {
console.log('点击了额外图标')
// 可以在此处理额外图标点击逻辑
})
📤 分享相关 Hooks
基础分享
useShareAppMessage
用户点击右上角菜单"转发"按钮时的处理函数。
typescript
import { useShareAppMessage } from '@tarojs/taro'
useShareAppMessage((res) => {
if (res.from === 'button') {
// 来自页面内转发按钮
console.log(res.target)
}
return {
title: '自定义转发标题',
path: '/pages/index/index?id=123',
imageUrl: '/static/share.jpg'
}
})
useShareTimeline
用户点击右上角菜单"分享到朋友圈"按钮时的处理函数(仅微信小程序支持)。
typescript
import { useShareTimeline } from '@tarojs/taro'
useShareTimeline(() => {
return {
title: '分享到朋友圈的标题',
query: 'id=123&from=timeline',
imageUrl: '/static/timeline.jpg'
}
})
useAddToFavorites
用户点击右上角菜单"收藏"按钮时的处理函数(仅微信小程序支持)。
typescript
import { useAddToFavorites } from '@tarojs/taro'
useAddToFavorites(() => {
return {
title: '收藏标题',
imageUrl: '/static/favorite.jpg',
query: 'id=123'
}
})
🔄 系统事件类 Hooks
窗口变化
useResize
窗口尺寸变化时触发。
typescript
import { useResize } from '@tarojs/taro'
useResize((res) => {
console.log('窗口尺寸变化', res.size)
// 适配不同屏幕尺寸
})
状态保存
useSaveExitState
保存当前页面状态,当用户通过系统返回按钮返回时恢复状态(仅微信小程序支持)。
typescript
import { useSaveExitState } from '@tarojs/taro'
useSaveExitState(() => {
return {
scrollTop: 100,
data: this.data
}
})
⚠️ 错误处理类 Hooks
全局错误
useError
小程序发生脚本错误或 API 调用报错时触发。
typescript
import { useError } from '@tarojs/taro'
useError((error) => {
console.error('发生错误', error)
// 错误上报
reportError(error)
})
useUnhandledRejection
小程序有未处理的 Promise 拒绝时触发。
typescript
import { useUnhandledRejection } from '@tarojs/taro'
useUnhandledRejection((res) => {
console.error('未处理的 Promise 拒绝', res.reason, res.promise)
// 可以在此处理全局错误
})
usePageNotFound
小程序要打开的页面不存在时触发。
typescript
import { usePageNotFound } from '@tarojs/taro'
usePageNotFound((res) => {
console.log('页面不存在', res.path, res.query)
// 可以重定向到 404 页面
Taro.redirectTo({ url: '/pages/404/index' })
})
🛣️ 路由相关 Hooks
useRouter
获取当前页面路由参数。
typescript
import { useRouter } from '@tarojs/taro'
const router = useRouter()
console.log('当前页面参数', router.params)
// 使用参数
const { id } = router.params
💡 最佳实践建议
1. 组合使用示例
typescript
import { useLoad, useReady, useDidShow, useDidHide } from '@tarojs/taro'
function Index() {
// 页面加载时获取参数
useLoad((options) => {
console.log('页面参数', options)
})
// 页面渲染完成后初始化
useReady(() => {
console.log('页面渲染完成')
})
// 页面显示时刷新数据
useDidShow(() => {
console.log('页面显示,刷新数据')
})
// 页面隐藏时保存状态
useDidHide(() => {
console.log('页面隐藏,保存状态')
})
}
2. 性能优化建议
- 避免在 Hooks 中执行耗时操作
- 合理使用防抖和节流
- 及时清理副作用(如定时器、事件监听)
3. 平台兼容性
- 注意不同平台的支持差异
- 使用条件编译处理平台特有功能
- 提供降级方案
📋 平台支持对照表
Hook | 微信小程序 | 支付宝小程序 | 百度小程序 | QQ小程序 | H5 | RN |
---|---|---|---|---|---|---|
useDidShow | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useDidHide | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
usePullDownRefresh | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useReachBottom | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
usePageScroll | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useResize | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useShareAppMessage | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useTabItemTap | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
useAddToFavorites | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
useShareTimeline | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
useSaveExitState | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
useLaunch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useError | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useUnhandledRejection | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
usePageNotFound | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useLoad | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useUnload | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useReady | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useRouter | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
useTitleClick | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
useOptionMenuClick | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
usePullIntercept | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |