@okcy/taro

基于 Taro 的 Vue 3 小程序组件库与工具集。

封装了通用 UI 组件（表单、上传、瀑布流、选项卡等）、页面模板（鉴权/安全区域）、以及路由/尺寸/校验等 composable。

安装

pnpm add @okcy/taro

入口

| 子路径 | 说明 | |--------|------| | . | 主入口（组件聚合） | | ./components | 组件入口 | | ./style.css | 组件样式（UnoCSS） |

组件

通用

| 组件 | 说明 | |------|------| | Button | 按钮组件，支持 theme / size / variant / loading / block | | Cell / CellInput | 单元格组件，用于表单展示，支持 title / icon / content / desc / tip | | Divider | 分割线 | | Label | <label> 标签容器，自动附加 ink-well 类 | | InkWell | 水波纹点击效果容器 | | Popup | 底部弹出层，使用 <page-container>，支持 title / show v-model | | SizeBox | 尺寸测量组件，通过 onChange(height, width) 回调容器尺寸 |

表单

| 组件 | 说明 | |------|------| | Form | 表单容器，管理 FormItem 注册与校验，暴露 validate / validateField / clearValidate | | useFormSubmit | 表单提交 action，校验失败自动 Taro.showToast，支持 onSuccess / onError 回调 | | Input | 文本输入，支持 v-model | | InputNumber | 数字输入，支持 min / max / step / precision | | Select | 选择器，基于 <picker mode="selector">，接收 options: { label, value }[] | | Picker / PickerSelect / PickerRegion / PickerDate | 选择器系列，支持 selector / region / date 模式 |

上传

| 组件 | 说明 | |------|------| | Upload | 图片上传组件，支持多选、最大数量限制、预览、删除 | | useUploadBase | 上传逻辑 action，封装压缩、CDN 转换、预览、删除，返回 UploadImage 组件实例 | | compressImage | 图片压缩工具函数，基于 Taro.compressImage |

数据展示

| 组件 | 说明 | |------|------| | ImageViewer | 图片预览，点击触发 Taro.previewImage | | Loading | 加载状态组件，loading=true 时显示 loading 动画 | | LoadMore | 列表加载更多，接收 pagination 对象（isLastPage / loading / error 等），自动 IntersectionObserver 触发 | | LoadingAnimation | 纯 CSS 旋转加载动画 | | Waterfall | 瀑布流布局组件，基于 <grid-view type="masonry">，响应式断点 sm(320) ~ xxl(1200) |

导航

| 组件 | 说明 | |------|------| | Tabs / TabLabel / TabContent | 选项卡，v-model 切换，激活过的面板不销毁 | | useTabs | 选项卡 action，支持滚动位置记忆、undo / redo | | TabBar / TabBarItem / TabBarItemButton | 底部导航栏，支持 fixed / safeAreaInsetBottom / theme="tag" |

页面模板

| 组件 / 类 | 说明 | |------|------| | Env | 环境判断组件，仅在 develop / trial / release 环境下渲染插槽内容 | | AbstractComponent | 页面抽象基类，提供 Admin（鉴权+权限）/ Auth（仅登录）/ Page（无鉴权）三种页面工厂方法，自动处理安全区域 | | SafeAreaFooter / Footer | 底部安全区域容器，通过 <Teleport> 挂载 | | SafeAreaFooterPlaceholder / FooterPlaceholder | 底部占位符，自动适配 iPhone 安全区域 |

工具函数与 Composable

路由

import { useRoute, useRouter } from "@okcy/taro/components";

// useRoute — 获取当前路由信息
const route = useRoute<{ id?: string }>();
// route.path, route.url, route.query

// useRouter — 封装 Taro 导航 API
const router = useRouter();
router.push("/pages/detail?id=1");
router.push({ path: "/pages/detail", query: { id: 1 } });
router.replace("/pages/login");
router.back();
router.switchTab("/pages/home");
router.reLaunch("/pages/index");

校验

import { useValidation } from "@okcy/taro/components";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(1),
  phone: z.string().regex(/^1\d{10}$/),
});

const validate = useValidation(schema);
validate.valid({ name: "", phone: "invalid" });
// onError: { name: "必填", phone: "..." }
validate.valid({ name: "ok", phone: "13800138000" });
// onSuccess: { name: "ok", phone: "13800138000" }

窗口与尺寸

import { useSize, useStorage, useShare, useObserver } from "@okcy/taro/components";

// useSize — 小程序窗口尺寸（状态栏、导航栏、胶囊、安全区域）
const { statusBarHeight, navBarHeight, capsule, headHeight, safeArea } = useSize();

// useStorage — 带持久化的 reactive ref
const token = useStorage<string>("token");

// useShare — 开启分享菜单 + 注册分享回调
useShare(() => ({ title: "...", path: "/pages/index" }));

// useObserver — IntersectionObserver 封装，用于下拉刷新 / 加载更多
const { Observer } = useObserver().onSuccess(() => loadMore());

其他工具

import {
  definePageConfig,     // Taro 4.0 definePageConfig 占位
  onClipboardData,      // 复制到剪贴板
  getCurrent,           // 获取当前页面实例
  getEventChannel,      // 获取 EventChannel
  toErrorBack,          // 提示错误并返回上一页
  toMessageBack,        // 提示成功并返回上一页
  safeDecode,           // URL 中文解码（支持双重编码）
  useActionSheet,       // ActionSheet 封装
  maskPhoneFlexible,    // 手机号脱敏
  btoa, atob,           // Base64 编解码（基于 Taro API）
} from "@okcy/taro/components";

依赖

• Vue 3、Taro (@tarojs/components, @tarojs/taro)
• @okcy/core（工具函数、emittery）
• zod（表单校验）、query-string（路由解析）
• UnoCSS + unocss-applet（样式）