主题定制

主色、中性色、圆角、字体与暗色模式

概述

ReUI 的主题系统基于 CSS 变量 + oklch 色彩空间构建。通过 applyTheme() 函数动态注入 CSS 变量到 document.documentElement，所有组件自动响应主题变化，无需重新渲染。

主题配置通过 ConfigProvider 组件或 applyTheme() / saveTheme() 函数设置，支持运行时切换，无需重启应用。

快速开始

方式一：ConfigProvider（推荐）

在应用根组件包裹 ConfigProvider，通过 theme prop 配置：

<script setup lang="ts">
import { ConfigProvider } from "@reglow/reui";
</script>

<template>
  <ConfigProvider :theme="{ mode: 'light', primaryColor: 'blue', radius: '0.5' }">
    <App />
  </ConfigProvider>
</template>

方式二：命令式调用

在任意位置调用 applyTheme() 或 saveTheme()：

import { applyTheme, saveTheme, loadAndApplyTheme } from "@reglow/reui/theme";

// 应用主题（仅当前会话）
applyTheme({ mode: "dark", primaryColor: "emerald", radius: "0.5" });

// 保存主题（持久化到 localStorage，刷新后自动恢复）
saveTheme({ mode: "dark", primaryColor: "emerald", radius: "0.5" });

// 从 localStorage 恢复主题（在应用启动时调用，避免白屏闪烁）
loadAndApplyTheme();

ThemeConfig 配置项

interface ThemeConfig {
  mode: "light" | "dark" | "auto";
  baseColor: string;
  primaryColor: string;
  radius: string;
  headingFont?: string;
  bodyFont?: string;
}
属性类型默认值说明
mode"light" | "dark" | "auto""light"主题模式，auto 跟随系统偏好
baseColorstring"zinc"中性基础色
primaryColorstring"blue"主色调
radiusstring"0.5"圆角大小（rem 倍数）
headingFontstring"system"标题字体
bodyFontstring"system"正文字体

主色调

17 种预设主色调，运行时切换即时生效：

色名色块
amber琥珀色
blue蓝色（默认）
cyan青色
emerald翠绿色
fuchsia品红色
green绿色
indigo靛蓝色
lime青柠色
orange橙色
pink粉色
purple紫色
red红色
rose玫瑰色
sky天蓝色
teal蓝绿色
violet紫罗兰色
yellow黄色
<script setup lang="ts">
import { ref } from "vue";
import { ConfigProvider } from "@reglow/reui";

const primaryColor = ref("blue");
</script>

<template>
  <ConfigProvider :theme="{ mode: 'light', primaryColor, radius: '0.5' }">
    <button @click="primaryColor = 'emerald'">切换为翠绿</button>
    <button @click="primaryColor = 'rose'">切换为玫瑰</button>
  </ConfigProvider>
</template>

基础中性色

7 种中性色方案，影响背景、边框、文字等基础色：

色名说明
neutral纯灰（无色相）
stone暖灰（微红）
zinc冷灰（微蓝，默认）
mauve紫灰
olive橄榄灰
mist薄雾灰（微蓝）
taupe褐灰
applyTheme({ mode: "light", baseColor: "stone", primaryColor: "orange", radius: "0.5" });

暗色模式

通过 mode 控制，auto 跟随系统 prefers-color-scheme：

<script setup lang="ts">
import { ref } from "vue";
import { ConfigProvider } from "@reglow/reui";

const mode = ref("light");
</script>

<template>
  <ConfigProvider :theme="{ mode, primaryColor: 'blue', radius: '0.5' }">
    <button @click="mode = mode === 'light' ? 'dark' : 'light'">
      切换 {{ mode === 'light' ? '暗色' : '亮色' }}
    </button>
  </ConfigProvider>
</template>

切换暗色模式时，applyTheme() 会自动：

  • 在 <html> 上添加/移除 .dark class
  • 替换所有 CSS 变量为暗色版本（主色、背景、边框等）

圆角

radius 控制全局圆角大小，值为 rem 倍数：

值效果
"0"直角
"0.3"小圆角
"0.5"中圆角（默认）
"0.75"大圆角
"1.0"超大圆角
applyTheme({ mode: "light", primaryColor: "blue", radius: "0.75" });

字体

内置 9 种字体方案，Web 字体会自动加载：

字体键说明
system系统默认字体（默认）
interInter
manropeManrope
geistGeist
harmonyosHarmonyOS Sans
oppoOPPO Sans
misansMiSans
alibaba阿里巴巴普惠体
notoNoto Sans SC
applyTheme({
  mode: "light",
  primaryColor: "blue",
  radius: "0.5",
  headingFont: "manrope",
  bodyFont: "inter",
});

持久化

saveTheme() 会将主题配置序列化到 localStorage（key: reui_theme_config），刷新页面后 loadAndApplyTheme() 自动恢复。

在应用入口调用 loadAndApplyTheme() 可避免白屏闪烁：

// main.ts
import { loadAndApplyTheme } from "@reglow/reui/theme";

loadAndApplyTheme(); // 在 mount 前调用

CSS 变量参考

主题引擎注入的 CSS 变量（可通过 var() 在自定义样式中引用）：

变量说明
--background / --foreground背景色 / 前景色
--card / --card-foreground卡片背景 / 卡片前景
--popover / --popover-foreground弹出层背景 / 前景
--primary / --primary-foreground主色 / 主色前景
--secondary / --secondary-foreground次要色 / 前景
--muted / --muted-foreground静音色 / 前景
--accent / --accent-foreground强调色 / 前景
--destructive / --destructive-foreground危险色 / 前景
--border边框色
--input输入框边框色
--ring焦点环色
--radius基础圆角
--font-body正文字体
--font-heading标题字体
在 Nuxt 中使用
通过 Nuxt module 自动注册全部组件
国际化
ReUI 内置轻量响应式 i18n 系统，组件内全部界面文案（占位符、按钮、空状态等）均接入，切换语言即时生效。