kt-template-admin/skills/references/core/theme.md

主题定制详细配置

CSS 变量

框架使用 CSS 变量实现主题定制，所有颜色使用 HSL 格式。

核心变量

:root {
  /* 基础背景色 */
  --background: 0 0% 100%;
  --background-deep: 216 20.11% 95.47%;
  --foreground: 210 6% 21%;

  /* 卡片 */
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;

  /* 弹出层 */
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;

  /* 静默状态 */
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;

  /* 主题色 */
  --primary: 212 100% 45%;
  --primary-foreground: 0 0% 98%;

  /* 错误色 */
  --destructive: 0 78% 68%;
  --destructive-foreground: 0 0% 98%;

  /* 成功色 */
  --success: 144 57% 58%;
  --success-foreground: 0 0% 98%;

  /* 警告色 */
  --warning: 42 84% 61%;
  --warning-foreground: 0 0% 98%;

  /* 次要色 */
  --secondary: 240 5% 96%;
  --secondary-foreground: 240 6% 10%;

  /* 强调色 */
  --accent: 240 5% 96%;
  --accent-hover: 200deg 10% 90%;
  --accent-foreground: 240 6% 10%;

  /* 边框 */
  --border: 240 5.9% 90%;

  /* 输入框 */
  --input: 240deg 5.88% 90%;
  --input-placeholder: 217 10.6% 65%;
  --input-background: 0 0% 100%;

  /* 圆角 */
  --radius: 0.5rem;

  /* 遮罩 */
  --overlay: 0deg 0% 0% / 30%;

  /* 侧边栏 */
  --sidebar: 0 0% 100%;
  --sidebar-deep: 216 20.11% 95.47%;

  /* 顶栏 */
  --header: 0 0% 100%;
}

暗色模式变量

.dark {
  --background: 222.34deg 10.43% 12.27%;
  --background-deep: 220deg 13.06% 9%;
  --foreground: 0 0% 95%;

  --card: 222.34deg 10.43% 12.27%;
  --card-foreground: 210 40% 98%;

  --sidebar: 222.34deg 10.43% 12.27%;
  --sidebar-deep: 220deg 13.06% 9%;

  --header: 222.34deg 10.43% 12.27%;

  --border: 240 3.7% 15.9%;
  --input: 0deg 0% 100% / 10%;
}

修改主题色

// preferences.ts
import { defineOverridesPreferences } from '@vben/preferences';

export const overridesPreferences = defineOverridesPreferences({
  theme: {
    colorPrimary: 'hsl(212 100% 45%)',
    colorSuccess: 'hsl(144 57% 58%)',
    colorWarning: 'hsl(42 84% 61%)',
    colorDestructive: 'hsl(348 100% 61%)',
  },
});

切换暗色模式

export const overridesPreferences = defineOverridesPreferences({
  theme: {
    mode: 'dark',  // 'light' | 'dark'
  },
});

内置主题

export const overridesPreferences = defineOverridesPreferences({
  theme: {
    builtinType: 'violet',  // 使用紫色主题
  },
});

可用主题：

• default - 默认蓝色
• violet - 紫色
• pink - 粉色
• rose - 玫瑰色
• sky-blue - 天蓝色
• deep-blue - 深蓝色
• green - 绿色
• deep-green - 深绿色
• orange - 橙色
• yellow - 黄色
• zinc - 锌灰色
• neutral - 中性色
• slate - 石板色
• gray - 灰色
• custom - 自定义

自定义主题

1. 在 preferences.ts 设置：

export const overridesPreferences = defineOverridesPreferences({
  theme: {
    builtinType: 'my-theme',
  },
});

2. 在 CSS 文件中定义变量：

/* light 模式 */
[data-theme='my-theme'] {
  --primary: 262.1 83.3% 57.8%;
  --primary-foreground: 210 20% 98%;
  --background: 0 0% 100%;
  --foreground: 224 71.4% 4.1%;
  /* ... 其他变量 */
}

/* dark 模式 */
.dark[data-theme='my-theme'],
[data-theme='my-theme'] .dark {
  --primary-foreground: 210 20% 98%;
  --background: 224 71.4% 4.1%;
  --foreground: 210 20% 98%;
  /* ... 其他变量 */
}

特殊模式

灰色模式

export const overridesPreferences = defineOverridesPreferences({
  app: {
    colorGrayMode: true,
  },
});

色弱模式

export const overridesPreferences = defineOverridesPreferences({
  app: {
    colorWeakMode: true,
  },
});

自定义侧边栏/顶栏颜色

:root {
  --sidebar: 0 0% 100%;
  --header: 0 0% 100%;
}

.dark {
  --sidebar: 222.34deg 10.43% 12.27%;
  --header: 222.34deg 10.43% 12.27%;
}

水印功能

export const overridesPreferences = defineOverridesPreferences({
  app: {
    watermark: true,
  },
});

// 动态更新水印内容
import { useWatermark } from '@vben/hooks';

const { updateWatermark } = useWatermark();
await updateWatermark({
  content: 'hello watermark',
});