多主题配置
14:24uView Pro X 的主题由「令牌(token)」驱动:一组颜色令牌在运行时同时写入全局 $u.color 与 CSS 变量,组件只读令牌,因此换肤不需要改组件源码。内置一套官方蓝主题,支持注册多套主题、运行时切换与暗黑模式。
主题令牌
一套主题用 ThemeColor 描述,字段为各组颜色的完整谱系:
| 令牌组 | 字段 |
|---|---|
| 主色 | primary / primaryDark / primaryDisabled / primaryLight |
| 成功色 | success / successDark / successDisabled / successLight |
| 警告色 | warning / warningDark / warningDisabled / warningLight |
| 错误色 | error / errorDark / errorDisabled / errorLight |
| 信息色 | info / infoDark / infoDisabled / infoLight |
| 字体色 | mainColor / contentColor / tipsColor / lightColor |
| 边框与遮罩 | borderColor / dividerColor / maskColor / shadowColor |
| 背景色 | bgColor / bgWhite / bgGrayLight / bgGrayDark / bgBlack |
| 纯色 | whiteColor / blackColor |
只写需要的字段即可,未提供的字段回退到内置调色板。
配置方式
app.use 的 theme 选项有四种形态,由库内部自动归一化:
| 形态 | 类型 | 说明 |
|---|---|---|
不传 / null | - | 仅使用内置官方蓝主题 |
| 单主题覆盖 | ThemeColor | 只声明要改的令牌,其余由内置基线(官方蓝)补齐 |
| 多主题 | Theme[] | 非空数组就是最终主题列表,内置主题只作同名项的基线 |
| 多主题 + 默认配置 | Themes | 在多主题基础上指定 defaultTheme / defaultDarkMode / isForce |
单主题覆盖
只改品牌色时,直接传令牌对象即可:
app.use(uViewProX, {
theme: {
primary: '#7c3aed',
success: '#10b981',
warning: '#f59e0b',
error: '#f43f5e'
}
})单主题形态只能覆盖亮色令牌
ThemeColor 只有颜色令牌,没有 darkColor / css / darkCss / label 字段(写了不会被读取):
- 暗色只能由亮色自动推导,背景 / 边框 / 字体等结构色固定取内置暗色基线;
- 无法注入额外 CSS 变量,也无法自定义主题展示名;
- 会把
config.defaultTheme重置为uviewpro。
需要精确控制暗色时,改用数组形态,哪怕只有一套主题:
import { BASE_THEME_NAME } from '@/uni_modules/uview-pro-x-uts'
app.use(uViewProX, {
theme: [
{
name: BASE_THEME_NAME,
label: '品牌橙',
color: { primary: '#ff5a1f', primaryLight: '#fff1eb' },
darkColor: { primary: '#ff8a5c', primaryLight: '#4a2418', bgColor: '#141414' },
css: { '--u-surface': '#ffffff' },
darkCss: { '--u-surface': '#1a1a1a' }
}
]
})列表只有一项时,切换列表也只有一项,效果上等同单主题,但暗色与 CSS 变量完全可控。
多主题
把多套主题放在一个数组里导出,安装时传入:
// theme.uts
export default [
{
name: 'purple',
label: '霞光紫',
color: {
primary: '#7c3aed',
primaryDark: '#6d28d9',
primaryLight: '#f3e8ff',
success: '#10b981',
warning: '#f59e0b',
error: '#f43f5e',
info: '#6b7280'
}
},
{
name: 'green',
label: '清翠绿',
color: {
primary: '#059669',
success: '#16a34a',
warning: '#eab308',
error: '#dc2626',
info: '#78716c'
}
}
]import themes from './theme.uts'
app.use(uViewProX, {
// 列表即注册列表,内置主题不会自动追加
theme: themes
})内置主题(名称
BASE_THEME_NAME,即uviewpro)只作为同名项的基线:色板、CSS 变量与文案都从基线补齐。想让它出现在切换列表里,在数组里显式声明一个只带name的项即可:tsimport { BASE_THEME_NAME } from '@/uni_modules/uview-pro-x-uts' export default [ { name: BASE_THEME_NAME, color: {} }, // 内置官方蓝 { name: 'purple', label: '霞光紫', color: { primary: '#7c3aed' } } ]
多主题 + 默认配置
用 Themes 形态指定默认主题与默认模式:
app.use(uViewProX, {
theme: {
themes: themes,
defaultTheme: 'purple',
defaultDarkMode: 'auto',
isForce: false
}
})isForce 为 true 时,defaultTheme / defaultDarkMode 优先级最高,忽略本地已保存的选择。
暗黑模式
暗黑模式由 darkMode 控制,取值 'auto'(跟随系统)/ 'light'(强制亮色)/ 'dark'(强制暗黑)。未配置时默认为 'light',不会自动跟随系统。
- 每套主题可显式提供
darkColor;未提供时,库会以亮色令牌与内置暗色调色板按 0.6 混合自动生成暗色变体,结构色(背景、边框、字体色等)直接取内置暗色值。 - 暗色最终取值顺序:用户
darkColor→ 亮色推导值 → 基线暗色值(基线只补未在color里声明过的字段)。 - App 端切换模式时会同步调用
uni.setAppTheme,使原生页面背景与导航栏联动,避免闪白 / 闪黑。 'auto'模式下监听系统主题变化(App 端onOsThemeChange、其他端onHostThemeChange)自动重算。
暗黑模式单独成篇
模式优先级、暗色板生成规则、平台联动与页面侧用法,详见暗黑模式。
运行时 API
用 useTheme 读取状态与切换主题:
import { useTheme } from '@/uni_modules/uview-pro-x-uts'
const { currentTheme, themes, darkMode, setTheme, setDarkMode, toggleDarkMode, isInDarkMode } = useTheme()
// 切换到已注册的主题
setTheme('purple')
// 强制暗黑
setDarkMode('dark')
// 在亮 / 暗之间切换
toggleDarkMode()useTheme 返回:
| 成员 | 类型 | 说明 |
|---|---|---|
themes | Ref<Theme[]> | 全部已注册主题 |
currentTheme | Ref<Theme | null> | 当前主题 |
darkMode | Ref<DarkMode> | 当前暗黑模式设置 |
cssVars | Ref<UTSJSONObject> | 当前生成的 CSS 变量表 |
setTheme | (name: string) => void | 按名称切换主题并持久化 |
getAvailableThemes | () => Theme[] | 获取全部主题 |
getCurrentTheme | () => Theme | null | 获取当前主题 |
setDarkMode | (mode: DarkMode) => void | 设置暗黑模式并持久化 |
getDarkMode | () => DarkMode | 获取当前暗黑模式 |
isInDarkMode | () => boolean | 当前是否处于暗黑态 |
toggleDarkMode | () => void | 在亮 / 暗之间切换 |
initTheme | (theme?) => void | 初始化主题系统 |
主题选择与暗黑模式会分别持久化到本地存储(键 uview-pro-x-theme、uview-pro-x-dark-mode),下次启动自动恢复。
CSS 变量
主题生效时会生成一组 CSS 变量,组件与页面样式均可直接引用:
- 普通令牌:
--u-<kebab>,如--u-main-color、--u-bg-color。 - 类型令牌(
primary/success/warning/error/info及其派生):--u-type-<kebab>,如--u-type-primary、--u-type-primary-light。 - RGB 变体:可解析为十六进制的令牌额外生成
-rgb变量,如--u-type-primary-rgb,便于拼rgba()。 - 模式标记:
--u-theme-mode,取值为light/dark。
注意事项
- 主题令牌必须是完整 6 位十六进制(
#rrggbb)才会生成-rgb变体;rgba()等写法不参与 RGB 拆分。 - 多主题数组内部按
name去重,同名后传覆盖先传;内置主题不参与列表,只作同名项的基线,要保留官方蓝需显式声明{ name: BASE_THEME_NAME, color: {} }。isForce只影响默认值优先级,不影响列表内容。 App端的原生背景 / 导航栏联动依赖uni.setAppTheme,切换模式后需保证该方法被调用(setDarkMode内部已处理)。- 暗色变体为自动混合结果,若对暗色有精确要求,请显式提供
darkColor,逐字段覆盖自动生成值。 - 主题名(
name)用于持久化与切换,改名会导致已保存的选择失效,回退到默认主题。 name为空或缺失的主题项会被直接丢弃(库不做隐式兜底);需要覆盖内置主题时,用BASE_THEME_NAME常量显式声明。
从旧版本升级
早期版本会把内置主题自动追加到主题列表,传入 Theme[] 后总比数组多一套。现在非空数组就是最终列表:
- 列表里没有内置项时,
uviewpro不再出现在切换列表,setTheme('uviewpro')会静默忽略; - 想保留默认蓝,在数组里显式声明
{ name: BASE_THEME_NAME, color: {} }(色板、CSS 变量、文案自动从基线补齐); - 旧版本保存在本地的
uviewpro选择会自动回落到列表首项,无需手动清理(库会在检测到失效名时把 storage 校正为实际生效值); - 默认值不会写入 storage:只有用户手动调用
setTheme/setDarkMode才落库,所以修改defaultTheme/defaultDarkMode对从未切换过的用户立即生效。