主题系统
jzfw-ui 的颜色不写死在 UCSS 中，而是以 TS 令牌表维护，运行时通过 getColor() 解析为实际色值后写入内联 :style。这样既规避了原生端对 CSS 变量支持不完整的问题，也让明暗主题切换即时生效。
API
从统一入口导入：
uts
import {
setTheme, toggleTheme, toggleAutoTheme, initTheme,
theme, isDark, isAuto,
getColor, getAdaptiveColor,
getForegroundColor, getBackgroundColor, getBorderColor, getMaskColor,
getTokens
} from "@/uni_modules/jzfw-ui";主题状态
| 名称 | 类型 | 说明 |
|---|---|---|
theme | Ref<Theme> | 当前主题（"light" | "dark"） |
isDark | ComputedRef<boolean> | 是否暗色主题，组件内所有明暗分支的唯一判据 |
isAuto | Ref<boolean> | 是否处于自动主题（跟随系统），仅 App 端有意义 |
主题方法
| 方法 | 签名 | 说明 |
|---|---|---|
setTheme | (value: Theme) => void | 设置主题。App 端须经 uni.setAppTheme 成功后再落地 |
toggleTheme | () => void | 在明暗主题之间切换 |
toggleAutoTheme | () => void | 切换自动主题模式（仅 App 有效）：开启跟随系统，关闭锁定当前 |
initTheme | () => void | 初始化主题监听，建议在 App.uvue 的 onLaunch 调用一次 |
uts
setTheme("dark"); // "light" | "dark"
toggleTheme(); // 明暗切换
isDark.value; // 当前是否暗色颜色解析
| 方法 | 说明 |
|---|---|
getColor(name) | 按优先级解析颜色名 → 实际色值 |
getAdaptiveColor(lightName, darkName) | 明暗主题分别取色，等价 getColor(isDark ? darkName : lightName) |
getForegroundColor() | 当前主题默认前景色 = getColor("foreground") |
getBackgroundColor() | 当前主题默认背景色 = getColor("background") |
getBorderColor() | 当前主题默认边框色 = getColor("border") |
getMaskColor() | 当前主题遮罩色 = getColor("mask") |
getTokens() | 返回当前主题的完整令牌表 Map<string, string> |
getColor(name) 的解析优先级：
- 空串 → 返回当前主题的默认前景色
- 语义别名 →
primary/success/warn/error/info/dark/light/disabled/foreground/background/border/mask - 令牌全名 →
primary-500、surface-700等色板全名（不随主题变化） - 原样返回 →
#fff、rgb(...)、rgba(...)等字面色值
uts
getColor("primary"); // 明暗主题均返回 #14b8a6
getColor("info"); // 浅色 #71717a，深色 #d4d4d8
getColor("surface-700"); // 令牌全名，取值固定
getColor("#ff0000"); // #ff0000令牌表
主色 primary（teal 色板）
primary-50 ~ primary-950，取值固定不随主题变化。语义别名 primary = #14b8a6（teal-500）。
| 令牌 | 色值 | 令牌 | 色值 |
|---|---|---|---|
| primary-50 | #f0fdfa | primary-600 | #0d9488 |
| primary-100 | #ccfbf1 | primary-700 | #0f766e |
| primary-200 | #99f6e4 | primary-800 | #115e59 |
| primary-300 | #5eead4 | primary-900 | #134e4a |
| primary-400 | #2dd4bf | primary-950 | #042f2e |
| primary-500 | #14b8a6 |
中性色 surface（zinc 色板）
surface（= zinc-0 #ffffff）、surface-50 ~ surface-950，取值固定。
| 令牌 | 色值 | 令牌 | 色值 |
|---|---|---|---|
| surface | #ffffff | surface-600 | #52525b |
| surface-50 | #fafafa | surface-700 | #3f3f46 |
| surface-100 | #f4f4f5 | surface-800 | #27272a |
| surface-200 | #e4e4e7 | surface-900 | #18181b |
| surface-300 | #d4d4d8 | surface-950 | #09090b |
| surface-400 | #a1a1aa | surface-500 | #71717a |
语义状态色（明暗共用）
| 别名 | 色值 |
|---|---|
| success | #22c55e |
| warn | #eab308 |
| error | #ef4444 |
明暗自适应别名
以下别名在明暗主题下取值不同：
| 别名 | 浅色 (light) | 深色 (dark) |
|---|---|---|
| primary | #14b8a6 | #14b8a6 |
| info | #71717a (surface-500) | #d4d4d8 (surface-300) |
| dark | #3f3f46 (surface-700) | #d4d4d8 (surface-300) |
| light | #fafafa (surface-50) | #fafafa (surface-50) |
| disabled | #a1a1aa (surface-400) | #71717a (surface-500) |
| foreground | #3f3f46 (surface-700) | #ffffff |
| background | #ffffff | #18181b (surface-900) |
| border | #e4e4e7 (surface-200) | #3f3f46 (surface-700) |
| mask | rgba(0,0,0,0.5) | rgba(0,0,0,0.7) |
别名优先级低于色板全名，因此
primary-500永远取色板值。
在组件属性中使用颜色
多数组件的 color / backgroundColor 等属性都接受上述任意一种取值（语义别名 / 令牌全名 / 字面色值）：
html
<jz-icon name="home-line" color="primary"></jz-icon>
<jz-text value="文本" color="surface-500"></jz-text>
<jz-tag type="error" color="#ff6b6b">自定义色</jz-tag>平台差异
- App 端：
setTheme经uni.setAppTheme成功后落地；initTheme监听onOsThemeChange/onAppThemeChange；toggleAutoTheme可跟随或锁定系统主题。 - 小程序端：
initTheme监听onHostThemeChange；主题由宿主决定。 - H5 端：
onHostThemeChange存在打包丢失问题，需由宿主在合适时机调用setTheme桥接。