Skip to content

多主题配置 ​

14:24

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

单主题覆盖 ​

只改品牌色时,直接传令牌对象即可:

ts
app.use(uViewProX, {
    theme: {
        primary: '#7c3aed',
        success: '#10b981',
        warning: '#f59e0b',
        error: '#f43f5e'
    }
})

单主题形态只能覆盖亮色令牌

ThemeColor 只有颜色令牌,没有 darkColor / css / darkCss / label 字段(写了不会被读取):

  • 暗色只能由亮色自动推导,背景 / 边框 / 字体等结构色固定取内置暗色基线;
  • 无法注入额外 CSS 变量,也无法自定义主题展示名;
  • 会把 config.defaultTheme 重置为 uviewpro。

需要精确控制暗色时,改用数组形态,哪怕只有一套主题:

ts
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 变量完全可控。

多主题 ​

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

ts
// 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'
        }
    }
]
ts
import themes from './theme.uts'

app.use(uViewProX, {
    // 列表即注册列表,内置主题不会自动追加
    theme: themes
})

内置主题(名称 BASE_THEME_NAME,即 uviewpro)只作为同名项的基线:色板、CSS 变量与文案都从基线补齐。想让它出现在切换列表里,在数组里显式声明一个只带 name 的项即可:

ts
import { BASE_THEME_NAME } from '@/uni_modules/uview-pro-x-uts'

export default [
    { name: BASE_THEME_NAME, color: {} },   // 内置官方蓝
    { name: 'purple', label: '霞光紫', color: { primary: '#7c3aed' } }
]

多主题 + 默认配置 ​

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

ts
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 读取状态与切换主题:

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

const { currentTheme, themes, darkMode, setTheme, setDarkMode, toggleDarkMode, isInDarkMode } = useTheme()

// 切换到已注册的主题
setTheme('purple')
// 强制暗黑
setDarkMode('dark')
// 在亮 / 暗之间切换
toggleDarkMode()

useTheme 返回:

成员类型说明
themesRef<Theme[]>全部已注册主题
currentThemeRef<Theme | null>当前主题
darkModeRef<DarkMode>当前暗黑模式设置
cssVarsRef<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。

注意事项 ​

  1. 主题令牌必须是完整 6 位十六进制(#rrggbb)才会生成 -rgb 变体;rgba() 等写法不参与 RGB 拆分。
  2. 多主题数组内部按 name 去重,同名后传覆盖先传;内置主题不参与列表,只作同名项的基线,要保留官方蓝需显式声明 { name: BASE_THEME_NAME, color: {} }。isForce 只影响默认值优先级,不影响列表内容。
  3. App 端的原生背景 / 导航栏联动依赖 uni.setAppTheme,切换模式后需保证该方法被调用(setDarkMode 内部已处理)。
  4. 暗色变体为自动混合结果,若对暗色有精确要求,请显式提供 darkColor,逐字段覆盖自动生成值。
  5. 主题名(name)用于持久化与切换,改名会导致已保存的选择失效,回退到默认主题。
  6. name 为空或缺失的主题项会被直接丢弃(库不做隐式兜底);需要覆盖内置主题时,用 BASE_THEME_NAME 常量显式声明。

从旧版本升级 ​

早期版本会把内置主题自动追加到主题列表,传入 Theme[] 后总比数组多一套。现在非空数组就是最终列表:

  • 列表里没有内置项时,uviewpro 不再出现在切换列表,setTheme('uviewpro') 会静默忽略;
  • 想保留默认蓝,在数组里显式声明 { name: BASE_THEME_NAME, color: {} }(色板、CSS 变量、文案自动从基线补齐);
  • 旧版本保存在本地的 uviewpro 选择会自动回落到列表首项,无需手动清理(库会在检测到失效名时把 storage 校正为实际生效值);
  • 默认值不会写入 storage:只有用户手动调用 setTheme / setDarkMode 才落库,所以修改 defaultTheme / defaultDarkMode 对从未切换过的用户立即生效。