Taro Hooks 完整分类详解

Taro Hooks 完整分类详解

Taro 提供了一系列强大的 Hooks 来帮助开发者更好地管理小程序和 H5 应用的生命周期、用户交互和系统事件。本文将按照功能类型对这些 Hooks 进行详细分类讲解。

📱 生命周期类 Hooks

页面生命周期

useLoad

页面加载时触发，只会触发一次。可以在此获取页面参数。

import { useLoad } from '@tarojs/taro'useLoad((options) => {console.log('页面加载完成', options)// 获取页面参数const { id } = options
})

useReady

页面初次渲染完成时触发，只会触发一次。

import { useReady } from '@tarojs/taro'useReady(() => {console.log('页面渲染完成')// 可以安全地获取节点信息
})

useUnload

页面卸载时触发，如 redirectTo 或 navigateBack 到其他页面时。

import { useUnload } from '@tarojs/taro'useUnload(() => {console.log('页面即将卸载')// 清理定时器、取消请求等
})

应用生命周期

useLaunch

小程序初始化完成时触发，全局只触发一次。

import { useLaunch } from '@tarojs/taro'useLaunch((options) => {console.log('小程序启动', options)// 初始化全局数据
})

useDidShow

页面显示/切入前台时触发。

import { useDidShow } from '@tarojs/taro'useDidShow(() => {console.log('页面显示')// 刷新数据、恢复播放器等
})

useDidHide

页面隐藏/切入后台时触发。

import { useDidHide } from '@tarojs/taro'useDidHide(() => {console.log('页面隐藏')// 暂停播放、保存状态等
})

👆 用户交互类 Hooks

滚动相关

usePageScroll

监听用户滑动页面事件。

import { usePageScroll } from '@tarojs/taro'usePageScroll((res) => {console.log('滚动位置', res.scrollTop)// 实现吸顶效果、懒加载等
})

useReachBottom

页面上拉触底事件的处理函数。

import { useReachBottom } from '@tarojs/taro'useReachBottom(() => {console.log('到达页面底部')// 加载更多数据loadMoreData()
})

usePullDownRefresh

监听用户下拉刷新事件。

import { usePullDownRefresh } from '@tarojs/taro'usePullDownRefresh(() => {console.log('触发下拉刷新')// 刷新数据refreshData().then(() => {Taro.stopPullDownRefresh()})
})

usePullIntercept

下拉截断时触发（仅微信小程序支持）。

import { usePullIntercept } from '@tarojs/taro'usePullIntercept(() => {console.log('下拉被截断')// 可以在此处理自定义下拉刷新逻辑
})

点击事件

useTabItemTap

点击 tab 时触发（仅 TabBar 页面）。

import { useTabItemTap } from '@tarojs/taro'useTabItemTap((item) => {console.log('点击了 tab', item.index, item.pagePath)// 可以在此处理 tab 点击逻辑
})

useTitleClick

点击标题时触发（仅支付宝小程序支持）。

import { useTitleClick } from '@tarojs/taro'useTitleClick(() => {console.log('点击了标题')// 可以在此处理标题点击逻辑
})

useOptionMenuClick

点击导航栏额外图标时触发（仅支付宝小程序支持）。

import { useOptionMenuClick } from '@tarojs/taro'useOptionMenuClick(() => {console.log('点击了额外图标')// 可以在此处理额外图标点击逻辑
})

📤 分享相关 Hooks

基础分享

useShareAppMessage

用户点击右上角菜单"转发"按钮时的处理函数。

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

用户点击右上角菜单"分享到朋友圈"按钮时的处理函数（仅微信小程序支持）。

import { useShareTimeline } from '@tarojs/taro'useShareTimeline(() => {return {title: '分享到朋友圈的标题',query: 'id=123&from=timeline',imageUrl: '/static/timeline.jpg'}
})

useAddToFavorites

用户点击右上角菜单"收藏"按钮时的处理函数（仅微信小程序支持）。

import { useAddToFavorites } from '@tarojs/taro'useAddToFavorites(() => {return {title: '收藏标题',imageUrl: '/static/favorite.jpg',query: 'id=123'}
})

🔄 系统事件类 Hooks

窗口变化

useResize

窗口尺寸变化时触发。

import { useResize } from '@tarojs/taro'useResize((res) => {console.log('窗口尺寸变化', res.size)// 适配不同屏幕尺寸
})

状态保存

useSaveExitState

保存当前页面状态，当用户通过系统返回按钮返回时恢复状态（仅微信小程序支持）。

import { useSaveExitState } from '@tarojs/taro'useSaveExitState(() => {return {scrollTop: 100,data: this.data}
})

⚠️ 错误处理类 Hooks

全局错误

useError

小程序发生脚本错误或 API 调用报错时触发。

import { useError } from '@tarojs/taro'useError((error) => {console.error('发生错误', error)// 错误上报reportError(error)
})

useUnhandledRejection

小程序有未处理的 Promise 拒绝时触发。

import { useUnhandledRejection } from '@tarojs/taro'useUnhandledRejection((res) => {console.error('未处理的 Promise 拒绝', res.reason, res.promise)// 可以在此处理全局错误
})

usePageNotFound

小程序要打开的页面不存在时触发。

import { usePageNotFound } from '@tarojs/taro'usePageNotFound((res) => {console.log('页面不存在', res.path, res.query)// 可以重定向到 404 页面Taro.redirectTo({ url: '/pages/404/index' })
})

🛣️ 路由相关 Hooks

useRouter

获取当前页面路由参数。

import { useRouter } from '@tarojs/taro'const router = useRouter()
console.log('当前页面参数', router.params)
// 使用参数
const { id } = router.params

💡 最佳实践建议

1. 组合使用示例

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	✅	❌	❌	❌	❌	❌