Skip to content

多主题与暗黑模式 ​

说明

本文适用于 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,默认导出一个数组,每个元素描述一套主题:
ts
export default [
  {
    name: 'midnight-black',
    label: '午夜黑',
    color: {
      primary: '#ff7a18',
      // ... 亮色色板
    },
    darkColor: {
      primaryLight: '#ffb066'
      // 留空的暗色会由系统智能生成
    }
  },
  // 其他主题...
];
  • 只提供 color 也可以,缺失的 darkColor 会自动按规则补齐;若部分暗色需要自定义,只需在 darkColor 中填写对应键,其余仍会自动生成。

注册主题 ​

基础使用 ​

在 unis.scss中引入uview-pro/theme.scss

scss
@import 'uview-pro/theme.scss';

在 main.ts 中注册 uView Pro

ts
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,无需手动再次初始化,确保主题数据全局唯一。

使用系统单主题 ​

如果你只使用一套主题、需要修改主题色,可以直接传入颜色令牌:

ts
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+

ts
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 留空会自动继承基线色板):

ts
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 中引入内置插件:

ts
import { defineConfig } from 'vite';
import { UniRoot } from 'uview-pro/plugins';
import Uni from '@dcloudio/vite-plugin-uni';

export default defineConfig({
  plugins: [
    UniRoot(), // 放在其他插件之前
    Uni(),
  ],
});
ts
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:

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 中使用:

html
<style lang="scss" scoped>
	.title{
		color: $u-type-primary;
    /* 或使用 css 变量 */
    color: var(--u-type-primary);
	}
</style>

在 vue/ts 中使用:

js
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 中声明。

ts
// 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+

ts
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 优先:

ts
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'
    }
  }
});

每个主题各自声明:变量需要随主题变化时,写在对应主题对象上(数组写法同样支持):

ts
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)
其它值按字符串原样注入可放渐变、字体、尺寸等

在页面中使用 ​

scss
.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);
}
ts
import { useTheme } from 'uview-pro';

const { cssVars } = useTheme();
cssVars.value['--u-app-card-radius']; // '16px',暗黑模式下为 '10px'
vue
<!-- 需要子树级下发变量时,可直接绑定 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 ​

ts
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 变量,例如
scss
.card {
  background-color: $u-bg-white;
  border-color: $u-border-color;
}
  • 模板行内样式:使用 $u.color.xxx 或 useTheme().cssVars
vue
<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 示例 ​

vue
<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 做自定义动画或渐变效果。

推荐阅读

暂无推荐文章

最后更新于: