更新记录

1.0.1（2026-09-05） 下载此版本

更新组件

1.0.0（2026-09-04） 下载此版本

第一阶段发布：运行时地基 + 12 个核心组件。

地基

• core：类型判定（is）、对象操作（object）、类名解析（clazz）、透传解析（pt）、单位换算（unit）、设备判定（device）、窗口与安全区度量（rect）、uuid（id）。全部自包含，不依赖宿主 .cool。
• theme：明暗双主题令牌表（primary=teal、surface=zinc、语义色），颜色经 getColor 在 TS 侧解析后写入内联 style，不使用 CSS 变量；支持跟随系统主题。
• locale：内置 7 语种词典（zh-cn/zh-tw/en/ja/ko/fr/es），t/$t/setLocale/getLocale/registerLocale，语言代码自动归一化。
• hooks：useCache（缓存刷新键）、useSize（字号缩放）、useParent（父组件查找）、useTouch（手势判定）、useZIndex（弹层层级分配）。
• icons：remixicon 字体资产随模块分发，启动时构建一次注册表，getIcon 走 Map 命中，未注册图标只告警一次；支持 registerIcon/registerIcons 扩充。
• config：响应式全局配置（fontSize 缩放、zIndex 基数）。

组件

• 基础：jz-text、jz-icon、jz-button、jz-image、jz-tag、jz-loading。
• 布局：jz-badge、jz-row、jz-col、jz-safe-area、jz-empty、jz-popup。

规范

• 纯 UCSS：无 @apply、无 scoped、无 CSS 变量、无后代/兄弟选择器、无 @keyframes（动画改用 UniElement.animate()）。
• 文字样式收敛到 <text>/<button>；类名统一 jz- 前缀；jz-col 栅格改为内联百分比宽度，移除 SCSS 批量生成类。
• 全脚本采用 .uts，符合 uni-app x 强类型规范（先定义后使用、显式布尔、下标访问前校验边界、跨端遍历用 toMap()）。

平台兼容性

uni-app x(5.24)

jzfw-ui

零外部依赖、可独立分发的 uni-app x 组件库。以纯 UCSS 编写样式、以 TS 令牌表驱动主题，不依赖 Tailwind、不依赖任何宿主框架代码（@/.cool、@cool-vue/*、cool-ui 一律不引用），可脱离 cool-unix 单独使用。

当前为第一阶段：运行时地基 + 12 个核心组件。后续阶段（表单 / 布局反馈 / 数据展示 / 其他）沿用地基逐步补齐。

特性

• 自包含：内置 core（类型判定、对象、单位、设备、安全区、类名解析、透传解析、uuid）、theme（明暗令牌表 + 颜色解析）、locale（7 语种词典）、hooks、icons。
• 纯 UCSS：样式块统一 <style lang="scss" scoped>，无 @apply、无 CSS 变量、无后代/兄弟/复合选择器、无 @keyframes（动画走 UniElement.animate()）。
• TS 主题令牌：颜色在 TS 侧解析后写入内联 :style，规避原生端对自定义 CSS 变量支持不完整的问题。
• 透传 API（pt）：保留通过一个 pt 对象穿透定制组件内部各部位样式的能力。
• 全脚本 UTS：模块内所有脚本均为 .uts，符合 uni-app x 强类型规范。

安装

将 jzfw-ui 目录放入项目 uni_modules/ 下即可。组件遵循 easycom 默认规则自动注册（uni_modules/*/components/组件名/组件名.uvue），无需修改 pages.json 的 easycom 配置，模板中直接使用 <jz-button> 等标签。

引入图标字体

图标基于 remixicon 字体，需在 App.uvue 的 <style> 中引入一次：

/* App.uvue */
@import "@/uni_modules/jzfw-ui/icons/index.scss";

初始化（推荐）

在 App.uvue 的 onLaunch 中初始化主题与语言监听：

<script setup lang="uts">
    import { initTheme, initLocale } from "@/uni_modules/jzfw-ui";

    onLaunch(() => {
        initTheme();
        initLocale();
    });
</script>

主题

import { setTheme, toggleTheme, isDark, getColor } from "@/uni_modules/jzfw-ui";

setTheme("dark"); // "light" | "dark"
toggleTheme(); // 明暗切换
isDark.value; // 当前是否暗色
getColor("primary"); // 语义别名 -> 实际色值
getColor("surface-700"); // 令牌全名 -> 实际色值
getColor("#ff0000"); // 字面色值原样返回

内置令牌：primary（teal 50~950）、surface（zinc 0~950）、语义色 success/warn/error，以及 info/dark/light/disabled/foreground/background/border/mask 等别名。明暗主题下别名取值不同，色板全名取值一致。

全局配置

import { config } from "@/uni_modules/jzfw-ui";

config.fontSize = 1.1; // 全局字号缩放系数，null 表示不缩放
config.zIndex = 600; // 弹层层级基数

多语言

内置 zh-cn / zh-tw / en / ja / ko / fr / es 七语种词典（首批覆盖通用文案）。

import { setLocale, getLocale, t, registerLocale } from "@/uni_modules/jzfw-ui";

setLocale("en");
t("暂无数据"); // 英文环境返回 "No data available"
registerLocale("en", [["暂无数据", "Nothing here"]]); // 覆盖/扩充文案

自定义图标

内置码表仅收录首批组件用到的图标，完整 remixicon 码表可自行注入：

import { registerIcon, registerIcons } from "@/uni_modules/jzfw-ui";

registerIcon("home-line", "ee1b");
registerIcons([["star-line", "f185"], ["star-fill", "f186"]]);

组件清单（第一阶段）

各组件 Props 明细见对应目录下的 props.uts。

平台

• App-Android / App-iOS：完整支持
• Web(H5) / 各小程序：条件编译适配
• 主题跟随系统：App 端监听 onOsThemeChange / onAppThemeChange，小程序端监听 onHostThemeChange，H5 端由宿主调用 setTheme 桥接