介绍

jzfw-ui 是一个零外部依赖、可独立分发的 uni-app x 组件库。它以纯 UCSS 编写样式、以 TS 令牌表驱动主题，不依赖 Tailwind、不依赖任何宿主框架代码，可脱离宿主项目单独使用。

设计目标

目标	说明
自包含	运行时地基（core / theme / locale / hooks / icons）全部内置，复制目录即可用
纯 UCSS	兼容 uni-app x 原生端样式子集，规避不支持的写法
强类型	模块内所有脚本均为 .uts，Props 以独立 props.uts 声明类型
可定制	主题令牌 + 透传 API（pt）双通道定制外观
多端一致	App / H5 / 小程序 / 鸿蒙条件编译适配

核心特性

1. 自包含运行时

内置以下能力，无需宿主提供任何依赖：

• core：类型判定（is）、对象（object）、单位（unit）、设备（device）、安全区、类名解析（clazz）、透传解析（pt）、uuid、路由、日期、矩形、动画、Canvas 工具
• theme：明暗令牌表（tokens）+ 颜色解析（color）
• locale：zh-cn / zh-tw / en / ja / ko / fr / es 七语种词典
• hooks：useUi、useRefs、usePager、useSize、useTouch、useCache、useZIndex 等
• icons：基于 remixicon 的字体图标码表

2. 纯 UCSS 样式约束

样式块统一 <style lang="scss" scoped>，遵循 uni-app x 原生端约束：

• ❌ 不使用 @apply
• ❌ 不使用 CSS 变量 var(--xxx)（原生端支持不完整）
• ❌ 不使用后代 / 兄弟 / 复合选择器
• ❌ 不使用 @keyframes（动画统一走 UniElement.animate()）

3. TS 主题令牌

颜色在 TS 侧通过 getColor() 解析为实际色值后写入内联 :style，UCSS 中只保留布局、尺寸、圆角等与主题无关的声明。这样明暗主题切换即时生效，且规避了原生端 CSS 变量问题。

4. 透传 API（pt）

每个组件对外暴露一个 pt 对象，可穿透定制组件内部各部位（如按钮的 label / icon / loading）的样式，突破主 API 限制。详见 [透传 API](/guide/。

组件构成

组件遵循 easycom 默认规则自动注册：uni_modules/*/components/组件名/组件名.uvue，无需修改 pages.json。每个组件目录通常包含：

jz-button/
├── jz-button.uvue   # 组件实现（模板 + 脚本 + 样式）
└── props.uts        # 对外属性类型声明（Props + PassThrough）

本手册的 Props 表格「说明」列即取自各 props.uts 的源码注释，Events / Methods 取自各 .uvue 的 defineEmits / defineExpose。

统一出口

按需从统一入口 import 运行时能力（组件无需 import，easycom 自动注册）：

import { getColor, setTheme, useSize, useUi, t, config } from "@/uni_modules/jzfw-ui";

出口聚合了 types、core、theme、locale、hooks、icons、config。

下一步

• [安装与引入](/guide/
• [快速上手](/guide/