useTheme 主题管理

主题管理 composable，提供主题切换、持久化、CSS 变量注入、暗黑模式等功能。

概述

useTheme 是 uView-Pro 的主题管理系统，支持：

多主题切换（品牌色、渐变色等）
主题持久化（保存到 Storage）
CSS 变量自动注入
暗黑模式（跟随系统 / 强制亮色 / 强制暗黑）
暗黑模式持久化

引入方式

typescript

import { useTheme } from 'uview-pro';

API

返回值

useTheme() 返回一个包含以下属性和方法的对象：

分类	属性/方法	类型	说明
响应式	`currentTheme`	`Ref<Theme \| null>`	当前主题信息
	`themes`	`Ref<Theme[]>`	所有可用主题
	`darkMode`	`Ref<DarkMode>`	暗黑模式设置
	`cssVars`	`Ref<Record<string, string>>`	CSS 变量映射
主题方法	`initTheme(themes?, defaultConfig?, isForce?)`	`function`	初始化主题系统
	`setTheme(themeName: string)`	`function`	切换主题
	`getCurrentTheme()`	`function`	获取当前主题
	`getAvailableThemes()`	`function`	获取所有可用主题
暗黑模式	`initDarkMode(darkMode?, isForce?)`	`function`	初始化暗黑模式
	`getDarkMode()`	`function`	获取暗黑模式设置
	`setDarkMode(mode: DarkMode)`	`function`	设置暗黑模式
	`isInDarkMode()`	`function`	检查是否处于暗黑模式
	`toggleDarkMode()`	`function`	切换暗黑模式

响应式引用

currentTheme

当前主题信息（响应式）。

typescript

const { currentTheme } = useTheme();

console.log(currentTheme.value?.name); // 'default'
console.log(currentTheme.value?.color); // 主题颜色配置
console.log(currentTheme.value?.darkColor); // 暗黑模式颜色配置

themes

所有可用主题列表（响应式）。

typescript

const { themes } = useTheme();

console.log(themes.value);
// [
//   { name: 'default', color: {...}, darkColor: {...} },
//   { name: 'dark', color: {...}, darkColor: {...} }
// ]

darkMode

当前暗黑模式设置（响应式）。

typescript

const { darkMode } = useTheme();

console.log(darkMode.value); // 'auto' | 'light' | 'dark'

DarkMode 类型

typescript

type DarkMode = 'auto' | 'light' | 'dark';

auto - 跟随系统
light - 强制亮色
dark - 强制暗黑

cssVars

生成的 CSS 变量映射（响应式）。

typescript

const { cssVars } = useTheme();

console.log(cssVars.value);
// {
//   '--u-type-primary': '#2979ff',
//   '--u-type-success': '#19be6b',
//   '--u-type-warning': '#ff9900',
//   '--u-type-error': '#fa3534',
//   '--u-bg-color': '#ffffff',
//   ...
// }

主题方法

initTheme(themes?, defaultConfig?, isForce?)

初始化主题系统。

typescript

const { initTheme } = useTheme();

// 使用默认内置主题
initTheme();

// 使用自定义主题
const customThemes = [
    {
        name: 'blue',
        color: {
            primary: '#1890ff',
            success: '#52c41a',
            warning: '#faad14',
            error: '#f5222d'
        }
    },
    {
        name: 'purple',
        color: {
            primary: '#722ed1',
            success: '#52c41a',
            warning: '#faad14',
            error: '#f5222d'
        }
    }
];

initTheme(customThemes, 'blue', true);

setTheme(themeName)

切换主题。

typescript

const { setTheme, currentTheme } = useTheme();

// 切换到蓝色主题
setTheme('blue');
console.log(currentTheme.value?.name); // 'blue'

// 切换到紫色主题
setTheme('purple');
console.log(currentTheme.value?.name); // 'purple'

getCurrentTheme()

获取当前主题（非响应式）。

typescript

const { getCurrentTheme } = useTheme();

const theme = getCurrentTheme();
console.log(theme?.name);
console.log(theme?.color);

getAvailableThemes()

获取所有可用主题。

typescript

const { getAvailableThemes } = useTheme();

const themes = getAvailableThemes();
console.log(themes.map(t => t.name)); // ['default', 'blue', 'purple']

暗黑模式方法

initDarkMode(darkMode?, isForce?)

初始化暗黑模式。

typescript

const { initDarkMode } = useTheme();

// 默认跟随系统
initDarkMode();

// 指定暗黑模式
initDarkMode('auto');
initDarkMode('light');
initDarkMode('dark');

// 强制重新初始化
initDarkMode('auto', true);

getDarkMode()

获取当前暗黑模式设置。

typescript

const { getDarkMode } = useTheme();

const mode = getDarkMode();
console.log(mode); // 'auto' | 'light' | 'dark'

setDarkMode(mode)

设置暗黑模式。

typescript

const { setDarkMode, darkMode, isInDarkMode } = useTheme();

// 跟随系统
setDarkMode('auto');

// 强制亮色
setDarkMode('light');

// 强制暗黑
setDarkMode('dark');

console.log(darkMode.value); // 'dark'
console.log(isInDarkMode()); // true（如果系统是暗黑主题）

isInDarkMode()

检查当前是否处于暗黑模式。

typescript

const { isInDarkMode } = useTheme();

if (isInDarkMode()) {
    console.log('当前是暗黑模式');
} else {
    console.log('当前是亮色模式');
}

toggleDarkMode()

切换暗黑模式（在 light 和 dark 之间切换）。

typescript

const { toggleDarkMode, isInDarkMode } = useTheme();

// 切换
toggleDarkMode();

console.log(isInDarkMode()); // 切换后的状态

使用示例

基础主题切换

html

<script setup lang="ts">
import { useTheme } from '@/uni_modules/uview-pro/libs/hooks/useLocale';

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

// 主题切换
const onThemeChange = (e: any) => {
    const index = e.detail.value;
    setTheme(themes.value[index].name);
};

// 暗黑模式切换
const onDarkModeChange = (e: any) => {
    const modes = ['auto', 'light', 'dark'];
    setDarkMode(modes[e.detail.value]);
};
</script>

<template>
    <view class="settings">
        <!-- 主题选择 -->
        <picker :value="currentThemeIndex" :range="themeNames" @change="onThemeChange">
            <view class="row">
                <text>主题</text>
                <text>{{ currentTheme?.name }}</text>
            </view>
        </picker>

        <!-- 暗黑模式 -->
        <picker :value="darkModeIndex" :range="darkModeOptions" @change="onDarkModeChange">
            <view class="row">
                <text>暗黑模式</text>
                <text>{{ darkMode }}</text>
            </view>
        </picker>

        <!-- 状态显示 -->
        <view>当前是否暗黑: {{ isInDarkMode() ? '是' : '否' }}</view>
    </view>
</template>

初始化完整主题系统

html

<script setup lang="ts">
import { useTheme } from 'uview-pro';

const { initTheme, initDarkMode, currentTheme, darkMode } = useTheme();

// 定义主题
const themes = [
    {
        name: 'default',
        color: {
            primary: '#2979ff',
            success: '#19be6b',
            warning: '#ff9900',
            error: '#fa3534',
            info: '#909399'
        },
        darkColor: {
            primary: '#2979ff',
            success: '#19be6b',
            warning: '#ff9900',
            error: '#fa3534',
            info: '#909399'
        }
    },
    {
        name: 'dark-theme',
        color: {
            primary: '#4caf50',
            success: '#4caf50',
            warning: '#ff9800',
            error: '#f44336',
            info: '#2196f3'
        },
        darkColor: {
            primary: '#81c784',
            success: '#81c784',
            warning: '#ffb74d',
            error: '#e57373',
            info: '#64b5f6'
        }
    }
];

// 初始化
onMounted(() => {
    initTheme(themes, 'default', true);
    initDarkMode('auto');
});
</script>

结合 CSS 变量使用

html

<script setup lang="ts">
import { useTheme } from 'uview-pro';

const { cssVars, isInDarkMode } = useTheme();

// 动态样式对象
const dynamicStyle = computed(() => ({
    '--primary-color': cssVars.value['--u-type-primary'],
    '--bg-color': cssVars.value['--u-bg-color'],
    '--text-color': cssVars.value['--u-main-color']
}));
</script>

<template>
    <view :style="dynamicStyle" class="container">
        <view class="card">
            <text class="title">卡片标题</text>
            <text class="desc">卡片内容描述</text>
        </view>
    </view>
</template>

<style>
.container {
    background-color: var(--bg-color);
    color: var(--text-color);
}

.card {
    background-color: var(--u-bg-color);
    border: 1px solid var(--u-border-color);
}

.title {
    color: var(--primary-color);
}
</style>

暗黑模式监听

typescript

<script setup lang="ts">
import { useTheme } from 'uview-pro';
import { onShow } from '@dcloudio/uni-app';

const { isInDarkMode } = useTheme();

// 监听页面显示时的暗黑模式状态
onShow(() => {
    if (isInDarkMode()) {
        console.log('当前是暗黑模式');
        // 可以在这里执行暗黑模式相关的初始化操作
    }
});

// 监听主题变化
watch(() => isInDarkMode(), (dark) => {
    if (dark) {
        uni.showToast({ title: '已进入暗黑模式', icon: 'none' });
    } else {
        uni.showToast({ title: '已切换到亮色模式', icon: 'none' });
    }
});
</script>

主题持久化

主题设置会自动保存到本地存储：

主题设置：uview-pro-theme
暗黑模式：uview-pro-dark-mode

typescript

<script setup lang="ts">
import { useTheme } from 'uview-pro';

const { setTheme, setDarkMode } = useTheme();

// 切换主题（会自动保存）
const changeTheme = (name: string) => {
    setTheme(name);
    // 已在内部保存到 Storage，下次打开应用会应用相同主题
};

// 切换暗黑模式（会自动保存）
const changeDarkMode = (mode: 'auto' | 'light' | 'dark') => {
    setDarkMode(mode);
    // 已在内部保存到 Storage
};
</script>

注意事项

主题和暗黑模式设置会自动持久化到 Storage
isInDarkMode() 返回布尔值，表示当前实际显示状态
darkMode 是设置值，isInDarkMode() 是实际显示状态
CSS 变量会自动注入到页面，无需手动设置
建议在 App.vue 或入口文件中调用 initTheme 初始化
暗黑模式切换会触发响应式更新，UI 自动适配

HarmonyOS APP

useTheme 主题管理 ​

概述 ​

引入方式 ​

API ​

返回值 ​

响应式引用 ​

currentTheme ​

themes ​

darkMode ​

DarkMode 类型 ​

cssVars ​

主题方法 ​

initTheme(themes?, defaultConfig?, isForce?) ​

setTheme(themeName) ​

getCurrentTheme() ​

getAvailableThemes() ​

暗黑模式方法 ​

initDarkMode(darkMode?, isForce?) ​

getDarkMode() ​

setDarkMode(mode) ​

isInDarkMode() ​

toggleDarkMode() ​

使用示例 ​

基础主题切换 ​

初始化完整主题系统 ​

结合 CSS 变量使用 ​

暗黑模式监听 ​

主题持久化 ​

注意事项 ​

useTheme 主题管理

概述

引入方式

API

返回值

响应式引用

currentTheme

themes

darkMode

DarkMode 类型

cssVars

主题方法

initTheme(themes?, defaultConfig?, isForce?)

setTheme(themeName)

getCurrentTheme()

getAvailableThemes()

暗黑模式方法

initDarkMode(darkMode?, isForce?)

getDarkMode()

setDarkMode(mode)

isInDarkMode()

toggleDarkMode()

使用示例

基础主题切换

初始化完整主题系统

结合 CSS 变量使用

暗黑模式监听

主题持久化

注意事项