useTheme 主题管理
17:43说明
useTheme 管理主题与暗黑模式:切换后调色板实时同步到 $u.color 与 CSS 变量,主题与暗黑设置会持久化到本地存储。
示例
当前主题状态
展示 currentTheme 的主题名、darkMode 的设置值、isInDarkMode() 解析出的生效模式与 themes 数量。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in stateRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useTheme } from '@/uni_modules/uview-pro-x';
// 解构方式使用:const { currentTheme } = useTheme()
const { themes, currentTheme, darkMode, isInDarkMode } = useTheme();
type Row = {
desc: string;
result: string;
last: boolean;
};
const stateRows = computed((): Row[] => {
const theme = currentTheme.value;
return [
{ desc: '当前主题:', result: theme != null ? theme.name : '-', last: false },
{ desc: '暗黑设置:', result: darkMode.value, last: false },
{ desc: '生效暗黑:', result: isInDarkMode() ? 'dark' : 'light', last: false },
{ desc: '可用主题数:', result: themes.value.length.toString(), last: true }
];
});
</script>主题切换
initTheme 传入两个演示主题(列表即最终主题列表,内置主题只作同名项基线),点击单元格调用 setTheme 切换并持久化。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in themeRows"
:key="index"
:title="item.label"
:label="item.name"
:value="item.active ? '当前' : ''"
:arrow="true"
:border-bottom="!item.last"
@click="setTheme(item.name)"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { $u, useTheme, type Theme, type ThemeColor } from '@/uni_modules/uview-pro-x';
const { themes, currentTheme, initTheme, setTheme } = useTheme();
type ThemeRow = {
name: string;
label: string;
primary: string;
active: boolean;
last: boolean;
};
// 演示主题:只声明主色,其余令牌由内置基线同名项补齐
function buildDemoTheme(name: string, label: string, primary: string): Theme {
const palette: ThemeColor = { primary: primary };
const theme: Theme = { name: name, label: label, color: palette };
return theme;
}
// 传入的非空列表就是最终主题列表,内置主题不再自动追加,只作同名项的基线
initTheme([buildDemoTheme('demoPurple', '演示紫', '#7c4dff'), buildDemoTheme('demoGreen', '演示绿', '#00b578')]);
const themeRows = computed((): ThemeRow[] => {
const list = themes.value;
const current = currentTheme.value;
const currentName = current != null ? current.name : '';
const rows: ThemeRow[] = [];
for (let i = 0; i < list.length; i++) {
const item = list[i];
rows.push({
name: item.name,
label: $u.strOr(item.label, item.name),
primary: $u.strOr(item.color.primary, ''),
active: item.name == currentName,
last: i == list.length - 1
});
}
return rows;
});
</script>暗黑模式
setDarkMode 接受 light / dark / auto 三种取值,toggleDarkMode 在 dark 与 light 之间切换。
查看源码
vue
<template>
<ux-row :gutter="10">
<ux-col :span="4">
<ux-button size="small" type="primary" block text="亮色" @click="setDarkMode('light')" />
</ux-col>
<ux-col :span="4">
<ux-button size="small" type="info" block text="暗黑" @click="setDarkMode('dark')" />
</ux-col>
<ux-col :span="4">
<ux-button size="small" type="info" block text="跟随系统" @click="setDarkMode('auto')" />
</ux-col>
</ux-row>
<ux-gap :height="10" />
<ux-button size="small" type="warning" block text="切换明暗" @click="toggleDarkMode()" />
</template>
<script setup lang="ts">
import { useTheme } from '@/uni_modules/uview-pro-x';
const { darkMode, setDarkMode, toggleDarkMode } = useTheme();
// light 强制亮色 / dark 强制暗黑 / auto 跟随系统
const isLight = computed((): boolean => darkMode.value == 'light');
</script>主题 CSS 变量
从 cssVars 读取 --u-theme-mode、--u-type-primary、--u-type-success 与 --u-main-color 四个变量的当前值。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in cssVarRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useTheme } from '@/uni_modules/uview-pro-x';
const { cssVars } = useTheme();
type Row = {
desc: string;
result: string;
last: boolean;
};
// 变量表整体替换,computed 会跟随刷新;config.type 内的令牌会加 --u-type 前缀
function cssVar(key: string): string {
const value = cssVars.value[key];
if (value == null) return '-';
return value.toString();
}
const cssVarRows = computed((): Row[] => [
{ desc: '--u-theme-mode', result: cssVar('--u-theme-mode'), last: false },
{ desc: '--u-type-primary', result: cssVar('--u-type-primary'), last: false },
{ desc: '--u-type-success', result: cssVar('--u-type-success'), last: false },
{ desc: '--u-main-color', result: cssVar('--u-main-color'), last: true }
]);
</script>恢复默认
无参 initTheme() 回到内置主题,并将 darkMode 置为 light,离开页面时同样执行一次。
查看源码
vue
<template>
<ux-button size="small" type="primary" block text="恢复默认主题" @click="restoreDefault()" />
</template>
<script setup lang="ts">
import { useTheme } from '@/uni_modules/uview-pro-x';
const { currentTheme, initTheme, setTheme, setDarkMode } = useTheme();
// 无参 initTheme() 回到内置主题;再把解析后的主题名写回存储
function restoreDefault(): void {
initTheme();
setDarkMode('light');
const current = currentTheme.value;
if (current != null) setTheme(current.name);
}
// 离开页面也恢复,避免影响其他页面
onUnload((): void => {
restoreDefault();
});
</script>使用说明
以提示条说明主题状态为模块级共享、setTheme / setDarkMode 会写入本地存储、额外主题经 initTheme([...]) 注入。
查看源码
vue
<template>
<ux-alert-tips type="primary" :show-icon="true" title="const { themes, currentTheme, setTheme } = useTheme()" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="状态为模块级,跨页面共享同一份主题" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="setTheme / setDarkMode 会写入本地存储" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="initTheme([...]) 的列表即主题列表,内置主题只作同名项基线" />
</template>
<script setup lang="ts">
import { useTheme } from '@/uni_modules/uview-pro-x';
const { themes, currentTheme, cssVars, setTheme, setDarkMode, initTheme } = useTheme();
</script>API
参数
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| - | 该 Hook 不接受参数 | - | - | - |
返回值
| 字段 | 说明 | 类型 |
|---|---|---|
| themes | 可用主题列表(传入主题列表时即该列表,内置主题只作同名项基线) | Ref<Theme[]> |
| currentTheme | 当前主题 | Ref<Theme | null> |
| darkMode | 暗黑模式设置:auto / light / dark | Ref<DarkMode> |
| cssVars | 当前模式的 CSS 变量表,含 --u-theme-mode 与 -rgb 变体 | Ref<JsonObject> |
| initTheme | 初始化主题;无参回到内置主题,传入列表时列表即最终主题列表 | (theme?: UViewProXThemeOptions | null) => void |
| setTheme | 切换主题并持久化,主题未注册时直接返回 | (themeName: string) => void |
| getAvailableThemes | 获取可用主题列表的副本 | () => Theme[] |
| getCurrentTheme | 获取当前主题 | () => Theme | null |
| setDarkMode | 设置暗黑模式并持久化,立即重新应用主题 | (mode: DarkMode) => void |
| getDarkMode | 获取当前暗黑模式设置 | () => DarkMode |
| isInDarkMode | 按当前设置解析是否处于暗黑状态 | () => boolean |
| toggleDarkMode | 在 dark 与 light 之间切换 | () => void |
注意事项
auto跟随系统:App 端在#ifdef APP内监听uni.onOsThemeChange,其他平台在#ifndef APP内监听uni.onHostThemeChange,且仅在darkMode为auto时重新应用主题。setDarkMode会调用uni.setAppTheme(包在#ifdef APP内),让原生页面背景与导航栏随明暗切换;非 App 端该调用不生效。setTheme/setDarkMode都会写入本地存储并立即应用;setTheme传入未注册的主题名时直接返回,不做切换。initTheme无参时回到内置主题;传入非空主题列表时该列表就是最终主题列表,内置主题不再自动追加,只作同名项(name与BASE_THEME_NAME相同)的基线;要保留官方默认主题需在列表里显式声明{ name: BASE_THEME_NAME, color: {} }。列表内同名项后传覆盖先传。- 默认暗黑模式是
'light'(即config.defaultDarkMode),未配置时不会跟随系统;要跟随系统需显式设为'auto'(安装时defaultDarkMode: 'auto',或运行时setDarkMode('auto'))。 - 单主题形态(直接传
ThemeColor)没有darkColor/css/darkCss字段,暗色只能由亮色推导;需要精确控制暗色时改用数组形态,哪怕只注册一套主题。 - 主题项
name为空或缺失会被丢弃(库不做隐式兜底),覆盖内置主题请用BASE_THEME_NAME常量显式声明。