多主题与暗黑模式
说明
本文适用于 uView Pro 版本 0.4.1 及以上,支持单主题、多主题、暗黑模式等。
本文面向 uView Pro 组件库使用者,帮助你在 Uni-app 项目中完整启用 uView Pro 的多主题与暗黑模式能力,重点围绕 useTheme 的 API 和最佳实践展开。
核心能力
- 一次性初始化:在应用入口通过
initTheme注入自定义主题,支持多套配置并自动生成暗黑色板。 - 响应式主题状态:
useTheme暴露currentTheme、themes、darkMode、cssVars等 ref,可直接用于模板。 - 暗黑模式策略:支持
auto跟随系统、light、dark三种模式,且可在运行时主动切换。 - 颜色获取:CSS 场景使用
$u-*SCSS 变量,内联样式使用$u.color.xxx或useTheme().cssVars/useColor()返回值,确保实时响应。
生成主题
通过【主题配置工具ThemeGenerate】生成主题文件 uview-pro.theme.ts
- 生成后复制到
src/uview-pro.theme.ts,默认导出一个数组,每个元素描述一套主题:
export default [
{
name: 'midnight-black',
label: '午夜黑',
color: {
primary: '#ff7a18',
// ... 亮色色板
},
darkColor: {
primaryLight: '#ffb066'
// 留空的暗色会由系统智能生成
}
},
// 其他主题...
];- 只提供
color也可以,缺失的darkColor会自动按规则补齐;若部分暗色需要自定义,只需在darkColor中填写对应键,其余仍会自动生成。
注册主题
基础使用
在 unis.scss中引入uview-pro/theme.scss
@import 'uview-pro/theme.scss';在 main.ts 中注册 uView Pro
import { createSSRApp } from 'vue';
import App from './App.vue';
import themes from '@/uview-pro.theme';
import uViewPro from '@/uni_modules/uview-pro';
export function createApp() {
const app = createSSRApp(App);
app.use(uViewPro, { theme: themes }); // 只需传入一次
return { app };
}install内部会调用useTheme().initTheme,无需手动再次初始化,确保主题数据全局唯一。
使用系统单主题
如果你只使用一套主题、需要修改主题色,可以直接传入颜色令牌:
import { createSSRApp } from 'vue';
import App from './App.vue';
import uViewPro from '@/uni_modules/uview-pro';
export function createApp() {
const app = createSSRApp(App);
app.use(uViewPro, {
theme: {
primary: '#000000',
// ...其余颜色令牌
}
});
return { app };
}- 只需写想覆盖的颜色令牌,未写的键沿用内置色板(含暗黑色,按规则自动推导)。
- 从 v0.6.24+ 起,同一个对象里还可以声明
css/darkCss(自定义全局变量,见下文「自定义全局变量」)、darkColor(自定义暗黑色)以及name/label/description(主题元信息)。 - 单主题形态只会产出 1 个主题项,
name缺省时沿用内置主题名(BASE_THEME_NAME)。
自定义单/多主题
如果你是多主题并在初始化时设置默认主题和暗黑模式,可以进行如下配置:
注意
版本支持v0.4.13+
import { createSSRApp } from 'vue';
import App from './App.vue';
import themes from '@/uview-pro.theme';
import uViewPro from '@/uni_modules/uview-pro';
export function createApp() {
const app = createSSRApp(App);
app.use(uViewPro, {
theme: {
themes: themes,
defaultTheme: 'purple', // 默认主题名称
defaultDarkMode: 'auto' // 默认暗黑模式:auto、light、dark
}
});
return { app };
}从 v0.6.24+ 起,themes 列表只包含你声明的主题,内置默认主题不再自动混入。想让「官方蓝」出现在切换列表里,显式声明一个同名主题即可(color 留空会自动继承基线色板):
import { BASE_THEME_NAME } from 'uview-pro';
export default [
{ name: BASE_THEME_NAME, label: '官方蓝默认', color: {} },
{ name: 'purple', label: '霞光紫', color: { primary: '#7c3aed' } }
];迁移提示
0.6.24 之前,Theme[] 会自动把内置主题追加到列表首位,主题数量总比数组多一项。升级后如果依赖这个行为(例如切回官方蓝),请按上面的写法显式补一项。
监听主题切换
uView Pro 内置了虚拟根组件能力,通过 UniRoot 插件自动为每个页面注入全局根组件,无需额外安装第三方插件。详见:虚拟根组件。
TIP
如果你不使用内置的虚拟根组件,也可以自己定义一个全局根组件,但必须使用 u-config-provider 组件包裹内部所有页面。
配置
在 vite.config.ts 中引入内置插件:
import { defineConfig } from 'vite';
import { UniRoot } from 'uview-pro/plugins';
import Uni from '@dcloudio/vite-plugin-uni';
export default defineConfig({
plugins: [
UniRoot(), // 放在其他插件之前
Uni(),
],
});import { defineConfig } from 'vite';
import { UniRoot } from './src/uni_modules/uview-pro/plugins';
import Uni from '@dcloudio/vite-plugin-uni';
export default defineConfig({
plugins: [
UniRoot(), // 放在其他插件之前
Uni(),
],
});TIP
若存在改变 pages.json 的插件,请将 UniRoot 放置其后。
使用
在 src/ 目录下创建 App.root.vue:
<script setup lang="ts">
import { useTheme } from 'uview-pro';
const { darkMode, themes, currentTheme } = useTheme();
</script>
<template>
<u-config-provider
:dark-mode="darkMode"
:current-theme="currentTheme?.name"
:themes="themes"
>
<slot />
</u-config-provider>
</template><slot />是页面内容的渲染位置,必须保留。u-config-provider负责把 CSS 变量注入到页面,同时监听主题/模式切换事件,具体 API 见 u-config-provider 文档。
在项目中使用
以上配置完成后需重新编译项目即可生效使用
在 scss 中使用:
<style lang="scss" scoped>
.title{
color: $u-type-primary;
/* 或使用 css 变量 */
color: var(--u-type-primary);
}
</style>在 vue/ts 中使用:
import { ref, onMounted } from 'vue';
import {$u} from 'uview-pro'
const color = ref('');
onMounted(() => {
color.value = uni.$u.color['primary'];
// 或
color.value = $u.color['primary'];
});自定义全局变量(css / darkCss)
除了内置的颜色令牌,还可以在主题对象上用 css / darkCss 声明任意自定义变量。初始化时会与色板一起注入为 CSS 变量,页面用 var() 或 useTheme().cssVars 读取,切换主题 / 暗黑模式时自动更新。
从 v0.6.24+ 起,库还会无条件注入一组基线变量:--u-background / --u-surface / --u-text(亮色、暗黑各一套),任何主题都能直接使用;你自己的业务变量不在这组基线里,仍需在主题或顶层 css 中声明。
// src/uview-pro.theme.ts
export default [
{
name: 'green',
label: '清翠绿',
color: { primary: '#059669' /* …其余色板 */ },
// 亮色模式下的自定义变量:直接写 -- 开头的标准 CSS 变量名
css: {
'--app-banner-height': '96px',
'--u-app-card-radius': '16px',
'--u-brand-gradient': 'linear-gradient(135deg, #059669 0%, #34d399 100%)',
'--u-brand-accent': '#10b981' // hex 值会额外生成 --u-brand-accent-rgb
},
// 暗黑模式下的覆盖值,未声明的键沿用 css
darkCss: {
'--app-banner-height': '80px',
'--u-app-card-radius': '10px'
}
}
];单主题写法
单主题不需要写成数组,把 css / darkCss 与颜色令牌写在同一个对象里即可:
注意
版本支持v0.6.24+
app.use(uViewPro, {
theme: {
primary: '#2979ff',
css: {
'--u-brand-accent': '#2979ff',
'--u-app-card-radius': '16px'
},
darkCss: {
'--u-brand-accent': '#8ab4ff',
'--u-app-card-radius': '10px'
}
}
});color令牌未写的键自动继承内置色板,因此只需写要覆盖的键;name/label/description/darkColor/css/darkCss与颜色令牌同级,不会被当作颜色处理。
多主题写法
共享变量写一处:所有主题都要用的变量放在顶层 css / darkCss,主题自身的同名 key 优先:
app.use(uViewPro, {
theme: {
themes: [
{ name: 'purple', label: '霞光紫', color: { primary: '#7c3aed' } },
{ name: 'green', label: '清翠绿', color: { primary: '#059669' } }
],
defaultTheme: 'green',
defaultDarkMode: 'auto',
css: {
'--app-banner-height': '96px',
'--u-app-card-radius': '16px'
},
darkCss: {
'--app-banner-height': '80px',
'--u-app-card-radius': '10px'
}
}
});每个主题各自声明:变量需要随主题变化时,写在对应主题对象上(数组写法同样支持):
export default [
{
name: 'purple',
color: { primary: '#7c3aed' },
css: { '--u-brand-accent': '#8b5cf6' }
},
{
name: 'green',
color: { primary: '#059669' },
css: { '--u-brand-accent': '#10b981' }
}
];变量生效优先级(低 → 高):库内置基线变量(--u-background / --u-surface / --u-text)v0.6.24+ → 与内置主题同名的项继承内置主题的 css / darkCss → 顶层共享 css / darkCss → 主题自身的 css / darkCss。
推荐写法
css / darkCss 的 key 请直接写 --u-xxx 这样的标准 CSS 变量名:注入时原样使用,与页面里的 var(--u-xxx)、cssVars['--u-xxx'] 一一对应,不需要心算转换。
不写 -- 的驼峰 key(如 appCardRadius)会被自动转成 --u-app-card-radius,但它只是兼容旧写法的便捷规则;命名被改写、且以 primary / success / info / error / warning 开头的 key 还会被额外加上 --u-type- 前缀,容易出现“变量名对不上”的困惑,新代码建议不要使用。
命名与取值规则
| 写法 | 注入结果 | 说明 |
|---|---|---|
'--u-app-card-radius': '16px' | --u-app-card-radius | 推荐写法,key 原样注入 |
'--app-banner-height': '96px' | --app-banner-height | 不带 u- 前缀也可以,适合业务自有变量 |
appCardRadius: '16px' | --u-app-card-radius | 兼容旧写法:自动转 --u- + kebab-case |
primaryBorderRadius: '8px' | --u-type-primary-border-radius | 以 primary / success / info / error / warning 开头的 key 会被加 --u-type- 前缀,与预期不符,避免使用 |
值为 #RRGGBB | 额外生成 <变量名>-rgb | 如 --u-brand-accent-rgb: 16, 185, 129,便于 rgba(var(--x-rgb), 0.15) |
| 其它值 | 按字符串原样注入 | 可放渐变、字体、尺寸等 |
在页面中使用
.card {
border-radius: var(--u-app-card-radius, 8px);
background: var(--u-brand-gradient);
color: var(--u-brand-accent);
box-shadow: 0 4px 12px rgba(var(--u-brand-accent-rgb), 0.2);
}import { useTheme } from 'uview-pro';
const { cssVars } = useTheme();
cssVars.value['--u-app-card-radius']; // '16px',暗黑模式下为 '10px'<!-- 需要子树级下发变量时,可直接绑定 cssVars -->
<view :style="cssVars">
<slot />
</view>多端生效范围
- H5 / App:变量写入
document.documentElement,页面内全局可用。 - 小程序等无
document的平台:变量通过u-config-provider根节点的行内样式下发,请先按上文监听主题切换配置虚拟根组件;局部子树也可直接绑定:style="cssVars"。 theme.scss已在:root, page上提供内置变量的默认值兜底,自定义变量建议在var()中写回退值,如var(--u-app-card-radius, 8px)。
注意事项
- 暗黑模式下
darkCss按 key 覆盖css,未在darkCss中声明的键沿用css的值 v0.6.24+(旧版本在darkCss非空时会整体忽略css)。 - 自定义变量不会生成 SCSS 变量(
$u-xxx是构建期静态值),页面里请用var()或cssVars。 - 不建议把自定义键写进
color:ThemeColor只声明固定的颜色令牌,且自定义键会被暗黑模式自动推导逻辑当作颜色处理。 - 尺寸类变量建议用
px/%,避免rpx在 H5 注入到document时不被换算。
useTheme API
const {
currentTheme, // Ref<Theme | null>
themes, // Ref<Theme[]>
darkMode, // Ref<'light' | 'dark' | 'auto'>
cssVars, // Ref<Record<string, string>>
setTheme,
getCurrentTheme,
getAvailableThemes,
initTheme,
getDarkMode,
setDarkMode,
isInDarkMode,
toggleDarkMode
} = useTheme();- currentTheme / themes:直接在模板中使用,例如
currentTheme?.name、themes.map(...)。 - cssVars:包含诸如
--u-type-primary,--u-bg-color等变量,可配合v-bind绑定到行内样式。 - setTheme(name):切换到指定主题,内部会持久化到
Storage,下次启动自动恢复。 - initTheme(list, defaultConfig?, isForce?, globalCss?):大多数场景无需手动调用;只有当你在运行时动态获取主题列表时,需要显式调用一次。
globalCss传{ css, darkCss }可把共享变量广播到全部主题v0.6.24+。 - getDarkMode / setDarkMode:读写当前暗黑策略;
setDarkMode('auto')会立即跟随系统主题。 - toggleDarkMode():在
light与dark间快速切换,常用于快捷开关。 - isInDarkMode():返回布尔值,表示当前是否处于暗黑渲染状态(
auto时会考虑系统设置)。
响应式颜色
- SCSS / CSS:继续使用
$u-xxx变量,例如
.card {
background-color: $u-bg-white;
border-color: $u-border-color;
}- 模板行内样式:使用
$u.color.xxx或useTheme().cssVars
<view :style="{ color: $u.color.primary }">按钮</view>
<view :style="{ backgroundColor: `rgba(var(--u-type-primary-rgb), 0.15)` }" />
<view :style="{ backgroundColor: `var(--u-type-primary)` }" />- 组合式 API:
useColor()(可选)提供getColor(name),在脚本逻辑中获取实时颜色值。
构建主题切换 UI 示例
<script setup lang="ts">
import { useTheme } from 'uview-pro';
const { themes, currentTheme, setTheme, darkMode, setDarkMode, toggleDarkMode } = useTheme();
</script>
<template>
<picker :range="themes" range-key="label" @change="e => setTheme(themes[e.detail.value].name)">
<view>当前主题:{{ currentTheme?.label }}</view>
</picker>
<u-switch :checked="darkMode === 'dark'" @change="toggleDarkMode" />
<u-button @click="setDarkMode('auto')">跟随系统</u-button>
</template>系统暗黑模式与持久化
- 首次进入应用时,如果
darkMode设置为auto,库会读取uni.getSystemInfoSync().theme并立即同步。 - 随后通过
uni.onThemeChange/window.matchMedia监听系统变化,保持与系统一致。 - 主题、暗黑模式均存储在本地 Storage,实现跨页面、重启仍然生效。
常见问题
- Q: 为什么动态写入 style 的颜色没有更新?
A: 确保使用$u.color.xxx或useTheme().cssVars,而不是硬编码十六进制。 - Q: 只传入一个主题对象是否可行?
A: 可以。扁平对象会以内置主题为模板生成唯一主题项,未写的颜色自动继承,仍具备暗黑模式;从 v0.6.24+ 起,同一个对象里还能直接写css/darkCss声明自定义变量。 - Q: 为什么
themes列表比我写的少一项?
A: 从 v0.6.24+ 起,内置默认主题不再自动混入列表,themes只包含你声明的主题。需要官方蓝参与切换时显式补一项:{ name: BASE_THEME_NAME, color: {} }。 - Q: 怎么让「官方蓝」出现在主题切换列表里?
A: 从uview-pro导入BASE_THEME_NAME,在数组里写{ name: BASE_THEME_NAME, label: '官方蓝默认', color: {} };color留空即完整继承基线色板与暗色,位置可放在任意处。 - Q: 多个主题想共用一组自定义变量,需要每个主题都写一遍吗?
A: 不需要。改用theme: { themes: [...], css: {...}, darkCss: {...} }的对象写法,把共用变量写在顶层即可。 - Q: 如何为特定主题手动定制暗黑色?
A: 在darkColor中写入需要覆盖的键(例如primaryLight),其余键仍由系统生成,保证一致性。
完成以上步骤即可获得统一、响应式、可扩展的主题与暗黑体验。若需更复杂的用例,可结合 useTheme 返回的 cssVars 做自定义动画或渐变效果。
推荐阅读
暂无推荐文章
