@zero-bits/taro-components 1.0.0 → 1.0.2

package/README.md

@@ -1,211 +1,257 @@
-# @zero-bits/taro
+# @zero-bits/taro-components
 
-这是一个针对 Taro 环境深度定制的企业级基础库，包含极其强大的 **OnionRequest (洋葱模型网络请求引擎)** 以及 **Permission (全局权限状态控制组件)**。
+针对 Taro 环境深度定制的企业级基础组件库，包含 **View**、**Text** 布局增强组件、**Permission 全局权限状态管理** 以及常用 **Hooks**。
+
+## 安装
+
+```bash
+pnpm add @zero-bits/taro-components
+```
+
+在入口文件中引入样式：
+
+```typescript
+import '@zero-bits/taro-components/index.css'
+```
 
 ## 目录
-- [OnionRequest 请求引擎](#onionrequest-请求引擎)
-  - [1. 引擎初始化配置](#1-引擎初始化配置)
-  - [2. 在业务中的极简用法](#2-在业务中的极简用法)
-  - [3. 文件上传与二进制流支持](#3-文件上传与二进制流支持)
-  - [4. 请求主动强杀 (Abort)](#4-请求主动强杀-abort)
-- [Permission 权限组件](#permission-权限组件)
+
+- [View 布局组件](#view-布局组件)
+- [Text 文本组件](#text-文本组件)
+- [Permission 权限管理](#permission-权限管理)
   - [1. 创建全局 Store](#1-创建全局-store)
   - [2. 挂载 Provider](#2-挂载-provider)
   - [3. 在组件中使用权限状态](#3-在组件中使用权限状态)
-- [Alova CQRS 请求钩子引擎 (Hooks)](#alova-cqrs-请求钩子引擎-hooks)
-  - [1. 钩子工厂初始化](#1-钩子工厂初始化)
-  - [2. useQuery (声明式读取)](#2-usequery-声明式读取)
-  - [3. useMutation (命令式写入)](#3-usemutation-命令式写入)
+- [useWeappUpdate 自动更新](#useweappupdate-自动更新)
 
 ---
 
-## OnionRequest 请求引擎
+## View 布局组件
 
-基于洋葱模型（Koa 风格）构建的终极请求引擎，支持**无感 Token 刷新、自动提纯数据、原生 Abort 强杀防爆红、并发竞态控制、跨端 Blob/ArrayBuffer 免疫**等高级特性。
+对 `@tarojs/components` 的 `View` 进行深度封装，提供大量 Flex 布局与样式的 **Props 语法糖**，告别内联 `style` 对象，代码更简洁。
 
-### 1. 引擎初始化配置
+### 引入
 
-在项目中创建 `src/utils/request.ts` 进行初始化：
+```tsx
+import { View } from '@zero-bits/taro-components'
+```
 
-```typescript
-import Taro from '@tarojs/taro'
-import { createRequest, AbortError } from '@zero-bits/taro/onion-request'
-
-export const request = createRequest({
-  // 1. 基础配置
-  baseURL: 'https://api.your-company.com',
-  timeout: 10000,
-  
-  // 2. 动态 Token 注入
-  getToken: () => Taro.getStorageSync('access_token'),
-  authHeaderKey: 'Authorization',
-  formatAuthValue: (token) => `Bearer ${token}`,
-
-  // 3. 全局业务报错拦截 (已免疫 Abort 误杀)
-  onBizError: (err) => {
-    Taro.showToast({
-      title: err?.msg || err?.message || '网络繁忙，请稍后再试',
-      icon: 'none'
-    })
-  },
-
-  // 4. 数据提纯与业务成功判定
-  isSuccess: (data) => data.code === 0 || data.code === 200,
-  resolveData: (data) => data.data, // 业务层调用时只需拿到真正的有效数据
-
-  // 5. 终极防御：无感刷新策略
-  refreshToken: {
-    url: '/v1/auth/refresh', // 刷新 Token 的接口
-    method: 'POST', // 后端要求的方法
-    getParams: () => ({ 
-      refresh_token: Taro.getStorageSync('refresh_token') 
-    }),
-    
-    // 异步落地新 Token（此时被 401 拦截挂起的请求正在排队等待）
-    onRefreshed: async (resData) => {
-      Taro.setStorageSync('access_token', resData.data.access_token)
-      Taro.setStorageSync('refresh_token', resData.data.refresh_token)
-    },
-    
-    // 刷新失败（例如 refresh_token 也过期了），强制登出
-    onRefreshFailed: () => {
-      Taro.removeStorageSync('access_token')
-      Taro.reLaunch({ url: '/pages/login/index' })
-    }
-  }
-})
+### Props 一览
+
+#### Flex 布局
+
+| Prop | 类型 | 说明 |
+|---|---|---|
+| `row` | `boolean` | `flex-direction: row`，主轴水平 |
+| `column` | `boolean` | `flex-direction: column`，主轴垂直 |
+| `flex` | `boolean` | `flex: 1`，自动占满剩余空间 |
+| `wrap` | `boolean` | `flex-wrap: wrap`，换行 |
+| `between` | `boolean` | `justify-content: space-between` |
+| `around` | `'justify-around' \| 'content-around'` | 主轴平均分布 |
+| `justifyItems` | `'flex-start' \| 'flex-end' \| 'center'` | 主轴对齐方式 |
+| `alignItems` | `'flex-start' \| 'flex-end' \| 'center'` | 交叉轴对齐方式 |
+| `alignSelf` | `string` | 自身对齐方式 |
+| `gap` | `string \| number` | 子元素间距 |
+| `rowGap` | `string \| number` | 行间距 |
+| `columnGap` | `string \| number` | 列间距 |
+| `flexShrink` | `number \| string` | 收缩比例 |
+| `flexGrow` | `number \| string` | 放大比例 |
+| `flexBasis` | `string \| number` | 初始大小 |
+
+#### 尺寸与定位
+
+| Prop | 类型 | 说明 |
+|---|---|---|
+| `full` | `boolean` | `width: 100%; height: 100%` |
+| `width` | `string \| number` | 宽度（数字自动加 `px`） |
+| `height` | `string \| number` | 高度 |
+| `position` | `'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'` | 定位方式 |
+| `zIndex` | `number \| string` | 层级 |
+| `top / right / bottom / left` | `number \| string` | 定位偏移量 |
+| `overflow` | `'hidden' \| 'visible' \| 'scroll'` | 溢出处理 |
+
+#### 外观
+
+| Prop | 类型 | 说明 |
+|---|---|---|
+| `bgColor` | `string` | 背景色 |
+| `radius` | `string \| number` | 圆角 |
+| `border` | `boolean` | 显示边框 |
+| `borderColor` | `string` | 边框颜色 |
+| `borderWidth` | `number \| string` | 边框宽度，默认 `1` |
+| `borderStyle` | `'solid' \| 'dashed' \| 'dotted'` | 边框样式，默认 `solid` |
+| `opacity` | `number \| string` | 透明度 |
+| `hidden` | `boolean` | 隐藏（`display: none`） |
+| `hover` | `boolean` | 点击降低透明度的悬停效果 |
+| `skeleton` | `boolean` | 骨架屏闪烁效果 |
+
+#### 间距（数字自动加 `px`）
+
+| Prop | 对应 CSS |
+|---|---|
+| `margin` | `margin` |
+| `mTop` | `margin-top` |
+| `mBottom` | `margin-bottom` |
+| `mLeft` | `margin-left` |
+| `mRight` | `margin-right` |
+| `mHorizontal` | `margin-left` + `margin-right` |
+| `mVertical` | `margin-top` + `margin-bottom` |
+| `padding` | `padding` |
+| `pTop` | `padding-top` |
+| `pBottom` | `padding-bottom` |
+| `pLeft` | `padding-left` |
+| `pRight` | `padding-right` |
+| `pHorizontal` | `padding-left` + `padding-right` |
+| `pVertical` | `padding-top` + `padding-bottom` |
+
+#### 安全区域
+
+| Prop | 类型 | 说明 |
+|---|---|---|
+| `safeArea` | `'top' \| 'bottom' \| 'both'` | 自动叠加 `env(safe-area-inset-*)` |
+
+### 使用示例
 
-// 按需导出核心错误类，供页面使用
-export { AbortError }
+```tsx
+import { View } from '@zero-bits/taro-components'
+
+// 水平居中布局
+<View row alignItems="center" justifyItems="center" gap={12}>
+  <View width={40} height={40} bgColor="#f0f0f0" radius={8} />
+  <View flex column>
+    <View height={16} bgColor="#333" radius={4} />
+  </View>
+</View>
+
+// 底部安全区域
+<View safeArea="bottom" bgColor="#fff" pHorizontal={16}>
+  <Button>提交</Button>
+</View>
+
+// 绝对定位遮罩
+<View position="absolute" top={0} left={0} full bgColor="rgba(0,0,0,0.5)" />
+
+// 骨架屏占位
+<View skeleton width={200} height={20} radius={4} />
 ```
 
-### 2. 在业务中的极简用法
+---
 
-引擎在底层吞下了所有苦难（包括提纯、401 刷新等），留给业务层的只有纯粹的快乐路径 (Happy Path)：
+## Text 文本组件
 
-```typescript
-import { useEffect } from 'react'
-import { request, AbortError } from '@/utils/request'
-
-export default function Home() {
-  useEffect(() => {
-    // 1. 发起请求
-    request.get('/v1/user/profile')
-      .then((data) => {
-        // data 已经是提纯后的有效数据，没有 code/msg 外壳
-        // 且它绝对是通过了 2XX 和业务 code === 0 双重校验的
-        console.log('获取用户信息成功:', data)
-      })
-      .catch((err) => {
-        // 全局弹窗已经替你报错了，如果是主动取消，可以选择忽略
-        if (err instanceof AbortError) return
-        console.error('获取失败兜底:', err)
-      })
-  }, [])
-
-  return <View>Hello OnionRequest</View>
-}
+对 `@tarojs/components` 的 `Text` 进行封装，提供字体、间距、溢出省略等 Props 语法糖。
+
+### 引入
+
+```tsx
+import { Text } from '@zero-bits/taro-components'
 ```
 
-### 3. 文件上传与二进制流支持
+### Props 一览
 
-提供极致优雅的上传语法糖，自动识别并配置 `multipart/form-data`。并自动对下载的二进制流实现提纯免疫。
+| Prop | 类型 | 说明 |
+|---|---|---|
+| `fontSize` | `string \| number` | 字体大小 |
+| `color` | `string` | 字体颜色 |
+| `bold` | `boolean \| number \| string` | 字体粗细，`true` 等同于 `bold` |
+| `lineHeight` | `string \| number` | 行高 |
+| `textAlign` | `'left' \| 'center' \| 'right' \| 'justify'` | 对齐方式 |
+| `decoration` | `'underline' \| 'line-through' \| 'none'` | 文字装饰 |
+| `clamp` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | 溢出省略显示行数 |
+| `selectable` | `boolean` | 是否可长按选中 |
+| `bgColor` | `string` | 背景色 |
+| `width` | `string \| number` | 宽度 |
+| `height` | `string \| number` | 高度 |
+| `skeleton` | `boolean` | 骨架屏效果 |
+| `style` | `CSSProperties` | 自定义样式（与上述 Props 合并） |
 
-```typescript
-// 纯图片上传
-const res1 = await request.upload('/v1/upload', 'wxfile://tmp_xxx.jpg')
-
-// 带额外表单参数的上传
-const res2 = await request.upload('/v1/upload', 'wxfile://tmp_xxx.jpg', {
-  userId: '10086',
-  type: 'avatar'
-})
-
-// 自定义上传字段名 (比如后端要求字段名是 'avatar' 而不是默认的 'file')
-const res3 = await request.upload('/v1/upload', 'wxfile://tmp_xxx.jpg', null, { 
-  name: 'avatar' 
-})
-
-// 文件下载（二进制流）
-const res4 = await request.get('/v1/report/export', null, {
-  responseType: 'arraybuffer' // 引擎会自动探测到流并静默放行，避免提纯引发崩溃
-})
-```
+> 同样支持所有 `margin` / `padding` 系列间距 Props，与 `View` 一致。
 
-### 4. 请求主动强杀 (Abort)
+### 使用示例
 
-框架赋予了 `request` 暴露出的 Promise 直接调用 `.abort()` 的能力。支持极速切断网络层，彻底杜绝组件卸载后请求依然在后台发送的情况。
+```tsx
+import { Text } from '@zero-bits/taro-components'
 
-```typescript
-import { useEffect, useRef } from 'react'
-import { request } from '@/utils/request'
+// 标题
+<Text fontSize={18} bold color="#333" lineHeight={28}>用户名称</Text>
 
-export default function UserList() {
-  const reqRef = useRef<any>()
+// 两行省略
+<Text clamp={2} fontSize={14} color="#666">
+  这是一段很长的描述文字，超过两行之后会自动省略显示...
+</Text>
 
-  useEffect(() => {
-    reqRef.current = request.get('/v1/users')
+// 价格文字
+<Text fontSize={24} bold color="#f00" decoration="underline">¥99.00</Text>
 
-    return () => {
-      // 组件卸载时的极致防御：强杀正在排队/请求中的任务
-      reqRef.current?.abort()
-    }
-  }, [])
-}
+// 骨架屏占位
+<Text skeleton fontSize={14} width={120}>占位文字</Text>
 ```
 
 ---
 
-## Permission 权限组件
+## Permission 权限管理
+
+基于 `useSyncExternalStore` 构建的脱离 React 上下文的全局权限管理器，支持在请求拦截器中触发注销，自动驱动全站 UI 响应。
 
-基于 `useSyncExternalStore` 构建的脱离 React 上下文的全局权限管理器。支持在 `axios/request` 拦截器中触发注销，自动驱动全站 UI 响应。
+### 引入
+
+```typescript
+import { createPermissionStore, PermissionProvider } from '@zero-bits/taro-components'
+import { usePermission } from '@zero-bits/taro-components'
+```
 
 ### 1. 创建全局 Store
 
 在项目中创建 `src/store/permission.ts`：
 
 ```typescript
-import { createPermissionStore } from '@zero-bits/taro/components/Permission'
+import { createPermissionStore } from '@zero-bits/taro-components'
 
-// 定义权限类型和用户信息类型
+// 定义权限对象类型
 interface MyPermissions {
   canAddUser: boolean
   canDeleteUser: boolean
+  canExport: boolean
 }
 
+// 定义用户信息类型
 interface MyUser {
   id: string
   name: string
-  role: string
+  role: 'admin' | 'editor' | 'viewer'
 }
 
-// 初始化全局单例 Store
+// 初始化全局单例 Store（整个应用只需一个）
 export const permissionStore = createPermissionStore<MyPermissions, MyUser>()
 ```
 
-你甚至可以在网络拦截器（如上面的 OnionRequest 的 `onRefreshFailed`）中直接使用它：
+可以在任何模块（如请求拦截器）中直接操作：
+
 ```typescript
-// 当刷新失败时，清除全局登录态
+import { permissionStore } from '@/store/permission'
+
+// 在请求拦截器的 Token 刷新失败回调中
 onRefreshFailed: () => {
-  permissionStore.denied()
+  permissionStore.denied() // 触发全局登出，PermissionProvider 的 onDenied 会自动响应
 }
 ```
 
 ### 2. 挂载 Provider
 
-在小程序的入口文件（如 `app.tsx`）中包裹 Provider：
+在小程序入口文件 `app.tsx` 中包裹 `PermissionProvider`：
 
-```typescript
+```tsx
 import { PropsWithChildren } from 'react'
-import { PermissionProvider } from '@zero-bits/taro/components/Permission'
+import Taro from '@tarojs/taro'
+import { PermissionProvider } from '@zero-bits/taro-components'
 import { permissionStore } from '@/store/permission'
 
 function App({ children }: PropsWithChildren) {
   return (
-    <PermissionProvider 
+    <PermissionProvider
       store={permissionStore}
       onDenied={() => {
-        // 当收到 denied() 调用（比如从拦截器发出的），统一执行登出路由跳转
+        // 当 permissionStore.denied() 被调用时，统一执行登出跳转
         Taro.reLaunch({ url: '/pages/login/index' })
       }}
     >
@@ -213,31 +259,31 @@ function App({ children }: PropsWithChildren) {
     </PermissionProvider>
   )
 }
+
 export default App
 ```
 
 ### 3. 在组件中使用权限状态
 
-在任何子组件中，你可以极其方便地获取登录态、权限字典、用户信息，或是手动操作权限：
-
-```typescript
-import { usePermission } from '@zero-bits/taro/components/Permission'
-import { Button, View, Text } from '@tarojs/components'
+```tsx
+import { Button } from '@tarojs/components'
+import { View, Text } from '@zero-bits/taro-components'
+import { usePermission } from '@zero-bits/taro-components'
 
 export default function Dashboard() {
-  const { 
-    isGranted, 
-    user, 
-    permissions,
-    granted, 
-    denied 
-  } = usePermission()
+  const {
+    isGranted,   // boolean - 是否已登录/授权
+    user,        // MyUser | null - 用户信息
+    permissions, // MyPermissions | null - 权限字典
+    granted,     // (user, permissions) => void - 设置登录态
+    denied       // () => void - 清除登录态（触发 onDenied）
+  } = usePermission<MyPermissions, MyUser>()
 
   // 模拟登录
   const handleLogin = () => {
     granted(
-      { id: 'u1', name: 'Zou', role: 'admin' }, 
-      { canAddUser: true, canDeleteUser: false }
+      { id: 'u001', name: '张三', role: 'admin' },
+      { canAddUser: true, canDeleteUser: false, canExport: true }
     )
   }
 
@@ -246,168 +292,92 @@ export default function Dashboard() {
   }
 
   return (
-    <View>
-      <Text>欢迎您: {user?.name}</Text>
-      
+    <View column pHorizontal={16}>
+      <Text fontSize={16} bold>欢迎，{user?.name}</Text>
+
       {/* 细粒度权限控制 */}
-      {permissions.canAddUser && <Button>添加用户</Button>}
-      {permissions.canDeleteUser && <Button>删除用户</Button>}
-      
-      {/* 登出 */}
+      {permissions?.canAddUser && <Button>新增用户</Button>}
+      {permissions?.canDeleteUser && <Button>删除用户</Button>}
+      {permissions?.canExport && <Button>导出数据</Button>}
+
       <Button onClick={denied}>退出登录</Button>
     </View>
   )
 }
 ```
 
----
-
-## Axios 适配器 (Taro Request)
-
-如果您或您的团队更倾向于使用传统的 Axios 生态（或者需要复用已有的 Axios 拦截器与代码库），我们同样提供了一套极其严谨的 **Taro Axios 适配器**，完美抹平了 Web 与小程序的网络层差异。
-
-### 1. 初始化 Axios 引擎
+#### `usePermission` 返回值
 
-在项目中引入并替换 Axios 的原生 Adapter：
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `isGranted` | `boolean` | 当前是否处于已授权（登录）状态 |
+| `user` | `U \| null` | 当前用户信息，未登录时为 `null` |
+| `permissions` | `P \| null` | 当前权限字典，未登录时为 `null` |
+| `granted` | `(user: U, permissions: P) => void` | 设置登录态与权限 |
+| `denied` | `() => void` | 清除登录态，触发 Provider 的 `onDenied` 回调 |
 
-```typescript
-import { initializeRequest, request, taroAdapter, defaultTransformRequest } from '@zero-bits/taro/request'
-
-// 全局初始化
-initializeRequest({
-  baseURL: 'https://api.your-company.com',
-  timeout: 10000,
-  
-  // 核心：强制 Axios 使用 Taro 的网络底层
-  adapter: taroAdapter,
-  
-  // 推荐：使用我们深度防御后的序列化方法
-  transformRequest: [defaultTransformRequest]
-})
-
-// 按需添加 Axios 传统的拦截器
-request.interceptors.request.use(config => {
-  config.headers.Authorization = 'Bearer token123'
-  return config
-})
-```
-
-### 2. 发起请求
-
-配置完毕后，它完全等同于一个标准的 Axios 实例：
-
-```typescript
-import { request } from '@/utils/request'
-
-// GET
-const res1 = await request.get('/v1/users')
-
-// POST
-const res2 = await request.post('/v1/users', { name: 'Zou' })
-
-// 文件上传 (原生适配)
-// 只要同时包含了 filePath、name 并且 Content-Type 为 multipart/form-data，
-// 适配器底层会自动切换为 Taro.uploadFile
-const res3 = await request.post('/v1/upload', {
-  filePath: 'wxfile://tmp_xxx.jpg',
-  name: 'file',
-  type: 'avatar'
-}, {
-  headers: {
-    'Content-Type': 'multipart/form-data'
-  }
-})
-
-// 取消请求 (支持 AbortController 规范)
-const controller = new AbortController()
-request.get('/v1/long-polling', { signal: controller.signal })
-controller.abort() // 原生打断 Taro.RequestTask
-```
-
-**对比总结**：
-- 如果您是从零搭建微信小程序/Taro 项目，强烈建议使用上面的 **OnionRequest**（洋葱模型），它内置了极其强悍的防爆红、无感刷新等特性。
-- 如果您的代码库是从 Web (React/Vue) 跨端迁移过来的，含有大量的 Axios 历史逻辑，可以直接使用本节的 **Axios 适配器**。
+> **注意**：`usePermission` 必须在 `<PermissionProvider>` 内部使用，否则会抛出错误。
 
 ---
 
-## Alova CQRS 请求钩子引擎 (Hooks)
-
-基于 **Alova V3** 构建的终极 React 请求状态机。它是一个抽象工厂，**可以完美接入上述的 OnionRequest 或 Axios**。
-提供极致的 CQRS (读写分离) 体验，告别手写 `useState(loading)` 和 `try...catch`，内置防抖、竞态控制、React 并发模型防撕裂（Tearing），以及极其严苛的 TypeScript 类型约束。
+## useWeappUpdate 自动更新
 
-### 1. 钩子工厂初始化
+微信小程序版本自动检测与更新提示的封装 Hook。在 app 根组件中调用一次即可，非微信环境自动跳过。
 
-在项目中创建 `src/utils/requestHooks.ts`，将您的请求实例（Axios 或 Onion）注入工厂，生成您的专属 Hook：
+### 引入
 
 ```typescript
-import { createRequestHooks } from '@zero-bits/taro/hooks'
-import { request } from './request' // 您的 axios 或 onion 实例
-
-export const { useQuery, useMutation, alovaInst } = createRequestHooks(request, {
-  // 全局定义后端的标准响应壳字段，引擎会自动进行“启发式剥壳”
-  fieldMap: { code: 'code', data: 'data', message: 'message' } 
-})
+import { useWeappUpdate } from '@zero-bits/taro-components'
 ```
 
-### 2. useQuery (声明式读取)
-
-专用于页面初次加载或依赖变化时自动获取数据。支持依赖追踪、内置防抖。
+### 使用示例
 
 ```tsx
-import { useState } from 'react'
-import { useQuery } from '@/utils/requestHooks'
-
-export default function UserList() {
-  const [keyword, setKeyword] = useState('')
-
-  // 泛型: <返回的数据体类型, 额外响应字段类型>
-  const { data: users, loading, extra } = useQuery<User[], { total: number }>(
-    () => ({
-      url: '/api/users',
-      params: { keyword }
-    }),
-    [keyword], // keyword 改变自动防抖重新请求
-    { debounce: 500 }
-  )
+// app.tsx
+import { useWeappUpdate } from '@zero-bits/taro-components'
 
-  return (
-    <View>
-      <Input onInput={(e) => setKeyword(e.value)} />
-      {loading ? <Text>加载中</Text> : <Text>共 {extra?.total} 人</Text>}
-      {users?.map(u => <View key={u.id}>{u.name}</View>)}
-    </View>
-  )
+function App({ children }) {
+  // 挂载时自动检测更新，有新版本弹窗提示用户重启
+  useWeappUpdate()
+
+  return <PermissionProvider ...>{children}</PermissionProvider>
 }
 ```
 
-### 3. useMutation (命令式写入)
+### 行为说明
 
-专用于增删改操作（如表单提交）。完全受控，通过 `send` 手动触发，并自带 `loading` 防重复提交锁。
+- **检测到新版本**：弹出 Modal 提示"新版本已经准备好，是否重启应用？"，用户确认后调用 `applyUpdate()` 重启。
+- **下载失败**：弹出 Modal 提示用户删除小程序后重新搜索打开。
+- **非微信环境**（H5 / RN 等）：`process.env.TARO_ENV !== 'weapp'` 时自动跳过，无任何副作用。
 
-```tsx
-import { useMutation } from '@/utils/requestHooks'
-
-export default function CreateUser() {
-  // 泛型: <返回的数据体类型, [send的入参类型]>
-  const { send, loading } = useMutation<null, [string, number]>(
-    (name, age) => ({
-      url: '/api/user/create',
-      method: 'POST',
-      data: { name, age }
-    }),
-    {
-      onSuccess: (event) => console.log('保存成功', event.data),
-      onError: (event) => console.error('报错了', event.error)
-    }
-  )
+---
 
-  return (
-    <Button 
-      loading={loading} 
-      onClick={() => send('张三', 25)} // 严格类型推导，必须传 string 和 number
-    >
-      提交
-    </Button>
-  )
-}
+## 完整导出列表
+
+```typescript
+// 主入口
+import {
+  View,
+  Text,
+  PermissionProvider,
+  createPermissionStore,
+  usePermission,
+  useWeappUpdate
+} from '@zero-bits/taro-components'
+
+// 按路径导入（tree-shaking 友好）
+import { View, Text, PermissionProvider, createPermissionStore } from '@zero-bits/taro-components/components'
+import { usePermission, useWeappUpdate } from '@zero-bits/taro-components/hooks'
+
+// 样式
+import '@zero-bits/taro-components/index.css'
 ```
+
+## Peer Dependencies
+
+| 包 | 版本要求 |
+|---|---|
+| `react` | `>= 18.0.0` |
+| `react-dom` | `>= 18.0.0` |
+| `@tarojs/components` | `>= 4.2.1` |
+| `@tarojs/taro` | `>= 4.2.1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-bits/taro-components",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Taro components and utilities",
   "main": "lib/index.js",
   "module": "es/index.js",
@@ -65,4 +65,4 @@
   "dependencies": {
     "classnames": "^2.3.0"
   }
-}
+}