taro-hooks

taro-hooks#

资源概述#

taro-hooks 是一个为 Taro 框架量身打造的 React/Vue Hooks 库，将小程序原生 API 封装为符合直觉的 Hooks 接口，同时集成 ahooks 通用 Hooks 集。支持 React、Vue3 Composition API，兼容微信/支付宝/百度/抖音/QQ/京东/鸿蒙等 Taro 全端目标。

核心特点：

• Taro API Hooks 化：将 Taro.request、Taro.getStorage、Taro.getLocation 等原生 API 封装为 useRequest、useStorage、useLocation 等 Hooks
• 框架双支持：React/PReact/Nerv 和 Vue3 Composition API 均可使用
• 集成 ahooks：扩展通用 Hooks（useToggle、useDebounce、useThrottle 等），无需额外安装
• 完整 TypeScript 类型：全量类型定义，IDE 自动补全
• 按需引入：ESM 产物，支持 tree-shaking

项目数据（2026-08-08）：

• GitHub：452⭐ / 36 forks / MIT License
• npm：最新版 2.2.0 / 48 versions / 周下载约 800-1200
• 活跃度：最后推送 2025-04-06，v2 版本开发中
• 文档站点：https://next-taro-hooks.pages.dev
• 社区：Discord 频道

设计规范#

架构设计#

taro-hooks 采用 monorepo 结构（pnpm workspaces），核心包与插件分离：

Hook 命名约定#

• API Hooks：use + API名称（如 useRequest、useStorage、useLocation）
• UI Hooks：use + 交互类型（如 useToast、useModal、useActionSheet）
• 设备 Hooks：use + 设备名（如 useNetworkType、useVibrate、useSystemInfo）

使用条件#

• 必须配合 Taro 3.x+ 使用（不适用于原生小程序开发）
• 需要安装对应框架的编译插件
• React 项目需要 React 16.8+（Hooks 支持）
• Vue 项目需要 Vue 3.x（Composition API）

审核规范#

taro-hooks 是开发工具库，不涉及平台审核。使用时需注意：

• 小程序后台需配置 request 合法域名（使用 useRequest 时）
• 网络请求需 HTTPS（所有小程序平台通用要求）
• 部分 Hooks（如 useLocation）需在小程序 app.json 中声明 requiredPrivateInfos

开发指南#

快速上手#

1. 安装依赖

# 安装核心包
npm install taro-hooks

# React 项目：安装 React 插件
npm install @taro-hooks/plugin-react

# Vue3 项目：安装 Vue 插件
npm install @taro-hooks/plugin-vue

2. 配置 Taro 编译器

// config/index.js (React)
const config = {
  // ...其他配置
  framework: 'react',
  plugins: ['@taro-hooks/plugin-react']
}

// config/index.js (Vue3)
const config = {
  framework: 'vue3',
  plugins: ['@taro-hooks/plugin-vue']
}

3. 使用 Hooks

import { useRequest, useEnv, useToast } from 'taro-hooks'

function MyPage() {
  const { env } = useEnv()
  const [showToast] = useToast()
  const { data, loading, error, run } = useRequest('/api/userInfo', {
    manual: true
  })

  const handleFetch = async () => {
    const result = await run()
    if (result) {
      showToast({ title: '获取成功' })
    }
  }

  return (
    <View>
      <Text>当前环境: {env}</Text>
      <Button onClick={handleFetch} loading={loading}>
        获取用户信息
      </Button>
    </View>
  )
}

Vue3 Composition API 用法#

import { useRequest } from 'taro-hooks'

export default {
  setup() {
    const { data, loading, run } = useRequest('/api/list', {
      manual: true
    })

    return { data, loading, run }
  }
}

常见陷阱#

1. 必须安装框架插件 — 只装 taro-hooks 不装 @taro-hooks/plugin-react / plugin-vue 会导致编译错误
2. Taro 版本兼容 — taro-hooks v2 需配合 Taro 3.6+，老版本 Taro 需用 taro-hooks v1
3. ahooks 依赖 — taro-hooks 内置 ahooks 扩展，不需要额外安装 ahooks（同时安装可能版本冲突）
4. useRequest manual 模式 — 设置 manual: true 后需手动调用 run() 才会发请求
5. Vue2 不支持 — taro-hooks 只支持 Vue3 Composition API，Vue2 Options API 无法使用
6. H5 环境差异 — 部分 Hooks（如 useVibrate）在 H5 环境下可能无效或行为不同

生态资源#

相关框架#

对比参考#

社区资源#

• GitHub Issues — 问题反馈
• Discord 频道 — 社区交流
• npm：taro-hooks

版本更新#

v2.2.0（最新稳定版，2025-04-06）#

• React 和 Vue3 双框架支持
• ahooks 集成扩展
• useRequest 独立抽象
• 完整 TypeScript 类型定义
• 48 个发布版本

v1.x（旧版，Taro 2.x 兼容）#

• 仅支持 React
• 维护模式（仅 bugfix）

版本选择建议#