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