Skip to content

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 / darkRef<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 常量显式声明。