多主题配置

uView 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'
    }
})

多主题

把多套主题放在一个数组里导出，安装时传入：

// 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, {
    // 与内置官方蓝合并为 3 套
    theme: themes
})

多主题 + 默认配置

用 Themes 形态指定默认主题与默认模式：

app.use(uViewProX, {
    theme: {
        themes: themes,
        defaultTheme: 'purple',
        defaultDarkMode: 'auto',
        isForce: false
    }
})

isForce 为 true 时，defaultTheme / defaultDarkMode 优先级最高，忽略本地已保存的选择。

暗黑模式

暗黑模式由 darkMode 控制，取值 'auto'（跟随系统）/ 'light'（强制亮色）/ 'dark'（强制暗黑）。

每套主题可显式提供 darkColor；未提供时，库会以亮色令牌与内置暗色调色板按 0.6 混合自动生成暗色变体，结构色（背景、边框、字体色等）直接取内置暗色值。
App 端切换模式时会同步调用 uni.setAppTheme，使原生页面背景与导航栏联动，避免闪白 / 闪黑。
'auto' 模式下监听系统主题变化（App 端 onOsThemeChange、其他端 onHostThemeChange）自动重算。

暗黑模式单独成篇

模式优先级、暗色板生成规则、平台联动与页面侧用法，详见暗黑模式。

运行时 API

用 useTheme 读取状态与切换主题：

import { useTheme } from '@/uni_modules/uview-pro-x'

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 合并，同名会覆盖内置主题；isForce 只影响默认值优先级，不影响合并。
App 端的原生背景 / 导航栏联动依赖 uni.setAppTheme，切换模式后需保证该方法被调用（setDarkMode 内部已处理）。
暗色变体为自动混合结果，若对暗色有精确要求，请显式提供 darkColor，逐字段覆盖自动生成值。
主题名（name）用于持久化与切换，改名会导致已保存的选择失效，回退到默认主题。

多主题配置 ​

主题令牌 ​

配置方式 ​

单主题覆盖 ​

多主题 ​

多主题 + 默认配置 ​

暗黑模式 ​

运行时 API ​

CSS 变量 ​

注意事项 ​