@zero-bits/taro-components

针对 Taro 环境深度定制的企业级基础组件库，包含 View、Text 布局增强组件、Permission 全局权限状态管理 以及常用 Hooks。

安装

pnpm add @zero-bits/taro-components

在入口文件中引入样式：

import '@zero-bits/taro-components/index.css'

目录

• View 布局组件
• Text 文本组件
• Permission 权限管理
  • 1. 创建全局 Store
  • 2. 挂载 Provider
  • 3. 在组件中使用权限状态
• useWeappUpdate 自动更新

View 布局组件

对 @tarojs/components 的 View 进行深度封装，提供大量 Flex 布局与样式的 Props 语法糖，告别内联 style 对象，代码更简洁。

引入

import { View } from '@zero-bits/taro-components'

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-*) |

使用示例

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} />

Text 文本组件

对 @tarojs/components 的 Text 进行封装，提供字体、间距、溢出省略等 Props 语法糖。

引入

import { Text } from '@zero-bits/taro-components'

Props 一览

| 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 合并） |

同样支持所有 margin / padding 系列间距 Props，与 View 一致。

使用示例

import { Text } from '@zero-bits/taro-components'

// 标题
<Text fontSize={18} bold color="#333" lineHeight={28}>用户名称</Text>

// 两行省略
<Text clamp={2} fontSize={14} color="#666">
  这是一段很长的描述文字，超过两行之后会自动省略显示...
</Text>

// 价格文字
<Text fontSize={24} bold color="#f00" decoration="underline">¥99.00</Text>

// 骨架屏占位
<Text skeleton fontSize={14} width={120}>占位文字</Text>

Permission 权限管理

基于 useSyncExternalStore 构建的脱离 React 上下文的全局权限管理器，支持在请求拦截器中触发注销，自动驱动全站 UI 响应。

引入

import { createPermissionStore, PermissionProvider } from '@zero-bits/taro-components'
import { usePermission } from '@zero-bits/taro-components'

1. 创建全局 Store

在项目中创建 src/store/permission.ts：

import { createPermissionStore } from '@zero-bits/taro-components'

// 定义权限对象类型
interface MyPermissions {
  canAddUser: boolean
  canDeleteUser: boolean
  canExport: boolean
}

// 定义用户信息类型
interface MyUser {
  id: string
  name: string
  role: 'admin' | 'editor' | 'viewer'
}

// 初始化全局单例 Store（整个应用只需一个）
export const permissionStore = createPermissionStore<MyPermissions, MyUser>()

可以在任何模块（如请求拦截器）中直接操作：

import { permissionStore } from '@/store/permission'

// 在请求拦截器的 Token 刷新失败回调中
onRefreshFailed: () => {
  permissionStore.denied() // 触发全局登出，PermissionProvider 的 onDenied 会自动响应
}

2. 挂载 Provider

在小程序入口文件 app.tsx 中包裹 PermissionProvider：

import { PropsWithChildren } from 'react'
import Taro from '@tarojs/taro'
import { PermissionProvider } from '@zero-bits/taro-components'
import { permissionStore } from '@/store/permission'

function App({ children }: PropsWithChildren) {
  return (
    <PermissionProvider
      store={permissionStore}
      onDenied={() => {
        // 当 permissionStore.denied() 被调用时，统一执行登出跳转
        Taro.reLaunch({ url: '/pages/login/index' })
      }}
    >
      {children}
    </PermissionProvider>
  )
}

export default App

3. 在组件中使用权限状态

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,   // boolean - 是否已登录/授权
    user,        // MyUser | null - 用户信息
    permissions, // MyPermissions | null - 权限字典
    granted,     // (user, permissions) => void - 设置登录态
    denied       // () => void - 清除登录态（触发 onDenied）
  } = usePermission<MyPermissions, MyUser>()

  // 模拟登录
  const handleLogin = () => {
    granted(
      { id: 'u001', name: '张三', role: 'admin' },
      { canAddUser: true, canDeleteUser: false, canExport: true }
    )
  }

  if (!isGranted) {
    return <Button onClick={handleLogin}>点击登录</Button>
  }

  return (
    <View column pHorizontal={16}>
      <Text fontSize={16} bold>欢迎，{user?.name}</Text>

      {/* 细粒度权限控制 */}
      {permissions?.canAddUser && <Button>新增用户</Button>}
      {permissions?.canDeleteUser && <Button>删除用户</Button>}
      {permissions?.canExport && <Button>导出数据</Button>}

      <Button onClick={denied}>退出登录</Button>
    </View>
  )
}

usePermission 返回值

| 字段 | 类型 | 说明 | |---|---|---| | isGranted | boolean | 当前是否处于已授权（登录）状态 | | user | U \| null | 当前用户信息，未登录时为 null | | permissions | P \| null | 当前权限字典，未登录时为 null | | granted | (user: U, permissions: P) => void | 设置登录态与权限 | | denied | () => void | 清除登录态，触发 Provider 的 onDenied 回调 |

注意：usePermission 必须在 <PermissionProvider> 内部使用，否则会抛出错误。

useWeappUpdate 自动更新

微信小程序版本自动检测与更新提示的封装 Hook。在 app 根组件中调用一次即可，非微信环境自动跳过。

引入

import { useWeappUpdate } from '@zero-bits/taro-components'

使用示例

// app.tsx
import { useWeappUpdate } from '@zero-bits/taro-components'

function App({ children }) {
  // 挂载时自动检测更新，有新版本弹窗提示用户重启
  useWeappUpdate()

  return <PermissionProvider ...>{children}</PermissionProvider>
}

行为说明

• 检测到新版本：弹出 Modal 提示"新版本已经准备好，是否重启应用？"，用户确认后调用 applyUpdate() 重启。
• 下载失败：弹出 Modal 提示用户删除小程序后重新搜索打开。
• 非微信环境（H5 / RN 等）：process.env.TARO_ENV !== 'weapp' 时自动跳过，无任何副作用。

完整导出列表

// 主入口
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 |