@kernelift/theme

@kernelift/theme 是 Kernelift 的独立主题管理包。

它提供：

• 主题模式管理（light / dark / system）
• 与 Element Plus 对齐的 CSS 变量映射
• 默认主题配置与品牌主题覆盖
• 颜色层级生成与合并工具

安装

pnpm add @kernelift/theme

快速开始

import { useTheme } from '@kernelift/theme';

const {
  theme,
  isDark,
  setTheme,
  styleConfig,
  updateLightConfig,
  updateDarkConfig
} = useTheme('light');

setTheme('dark');

updateLightConfig({
  colors: {
    primary: { base: '#409eff' }
  }
});

存储前缀配置

如果需要与业务平台编码对齐存储键前缀，可通过 ThemeStorageOptions 传入：

import { useTheme } from '@kernelift/theme';

useTheme('light', 'dark', undefined, undefined, {
  useStoragePrefix: true,
  storagePrefix: 'my-platform'
});

存储行为与优先级

useTheme 的初始化遵循以下逻辑：

默认行为（forceOverride 为 false 或未传）

| localStorage 状态 | 行为 | |------------------|------| | 有值 | 使用 storage 的值，不写入传入值 | | 无值 | 使用传入值并写入 localStorage |

优先级：

1. localStorage 已存储值（最高优先级）
2. defaultTheme 入参
3. 系统主题偏好（prefers-color-scheme）
4. light（兜底）

强制覆盖（forceOverride 为 true）

无论如何都将传入值写入 localStorage，覆盖已有值。

useTheme('dark', 'dark', '#409eff', '#66b1ff', {
  forceOverride: true // 强制覆盖
});

使用示例

基础用法

import { useTheme } from '@kernelift/theme';

// localStorage 有值 → 使用 storage
// localStorage 无值 → 使用 'light' 并写入
const { theme, isDark } = useTheme('light');

设置默认主题色

import { useTheme } from '@kernelift/theme';

// localStorage 有值 → 不覆盖已有配置
// localStorage 无值 → 使用默认主色并写入
const { styleConfig } = useTheme(
  'light',          // 默认主题模式
  'dark',           // 暗色模式类名
  '#004493',        // 亮色主题默认主色
  '#fe7b0d'         // 暗色主题默认主色
);

强制覆盖场景

import { useTheme } from '@kernelift/theme';

// 用于品牌升级、配置迁移等场景
// 无论 localStorage 是否有值，都会写入传入值
const { theme, styleConfig } = useTheme('dark', 'dark', '#004493', '#fe7b0d', {
  forceOverride: true
});

API 文档

useTheme 参数

function useTheme(
  defaultTheme?: ThemeMode,           // 默认主题模式
  darkModeClass?: string,             // 暗色模式 CSS 类名，默认 'dark'
  defaultPrimaryColor?: string,       // 亮色主题默认主色
  defaultDarkPrimaryColor?: string,   // 暗色主题默认主色
  storageOptions?: ThemeStorageOptions // 存储配置选项
)

ThemeStorageOptions

interface ThemeStorageOptions {
  /** 是否启用存储前缀 */
  useStoragePrefix?: boolean;
  /** 存储前缀值 */
  storagePrefix?: string;
  /** 是否强制覆盖已有存储值 */
  forceOverride?: boolean;
}

返回值

{
  // 主题状态
  theme: Ref<ThemeMode>;              // 当前主题模式
  appliedTheme: ComputedRef<'light' | 'dark'>; // 实际应用的主题
  isDark: ComputedRef<boolean>;       // 是否暗色主题
  isLight: ComputedRef<boolean>;      // 是否亮色主题
  isSystem: ComputedRef<boolean>;     // 是否系统主题
  
  // 主题操作
  setTheme: (mode: ThemeMode) => void;    // 设置主题模式
  loadThemeMode: () => void;               // 加载主题模式
  
  // 样式配置
  styleConfig: Ref<BaseStyleConfig>;      // 完整样式配置
  currentConfig: ComputedRef<ThemeModeConfig>; // 当前主题配置
  updateLightConfig: (config) => void;    // 更新亮色配置
  updateDarkConfig: (config) => void;     // 更新暗色配置
  resetStyleConfig: () => void;           // 重置样式配置
  
  // 设计风格
  designStyle: Ref<string>;               // 设计风格
  setThemeStyle: (style: string) => void; // 设置主题风格
  setDesignStyle: (style: string) => void; // 设置设计风格
  
  // 清理
  cleanupSystemThemeListener: () => void; // 清理系统主题监听
}

CSS 变量使用

标准 CSS 变量

主题系统会自动设置以下 CSS 变量（同时设置 --kl-* 和 --el-*）：

/* 主题色 */
--kl-color-primary
--kl-color-primary-light-3
--kl-color-primary-light-5
--kl-color-primary-light-7
--kl-color-primary-light-8
--kl-color-primary-light-9
--kl-color-primary-dark-2

/* 文本颜色 */
--kl-text-color-primary
--kl-text-color-regular
--kl-text-color-secondary
--kl-text-color-placeholder
--kl-text-color-disabled

/* 背景色 */
--kl-bg-color
--kl-bg-color-page
--kl-bg-color-overlay

/* 边框颜色 */
--kl-border-color
--kl-border-color-light
--kl-border-color-lighter
--kl-border-color-extra-light
--kl-border-color-dark
--kl-border-color-darker

/* 填充色 */
--kl-fill-color
--kl-fill-color-light
--kl-fill-color-lighter
--kl-fill-color-extra-light
--kl-fill-color-dark
--kl-fill-color-darker
--kl-fill-color-blank

/* 圆角 */
--kl-border-radius-base
--kl-border-radius-small
--kl-border-radius-round
--kl-border-radius-circle

在组件中使用

<template>
  <div class="my-component">
    <!-- 使用主题变量 -->
    <h1>标题</h1>
    <p>内容</p>
  </div>
</template>

<style scoped>
.my-component {
  color: var(--kl-text-color-primary);
  background-color: var(--kl-bg-color);
  border: 1px solid var(--kl-border-color);
  border-radius: var(--kl-border-radius-base);
}

.my-component h1 {
  color: var(--kl-color-primary);
}

.my-component p {
  color: var(--kl-text-color-regular);
}
</style>

与 @kernelift/core 集成

@kernelift/core 已经内置了对 @kernelift/theme 的支持：

import { createKernelift, ThemePlugin } from '@kernelift/core';

app.use(
  createKernelift({
    plugins: [
      {
        plugin: ThemePlugin,
        options: {
          defaultTheme: 'light',
          defaultPrimaryColor: '#004493',
          defaultDarkPrimaryColor: '#fe7b0d'
        }
      }
    ]
  })
);

从 core 包导入

// ✅ 推荐方式：从 core 导入（保持 API 一致性）
import { useTheme } from '@kernelift/core';

// ✅ 也可以直接从 theme 包导入
import { useTheme } from '@kernelift/theme';

STORAGE_KEYS 复用

// theme 包定义主题相关的键
import { STORAGE_KEYS } from '@kernelift/theme';
// { THEME, STYLE_CONFIG, DESIGN_STYLE }

// core 包复用并扩展
import { STORAGE_KEYS } from '@kernelift/core';
// { THEME, STYLE_CONFIG, DESIGN_STYLE, LANGUAGE, SYSTEM_INFO, ... }

迁移指南

从旧版本迁移

如果你的项目直接使用 localStorage 操作主题配置：

旧代码：

localStorage.setItem('theme', 'dark');
const theme = localStorage.getItem('theme');

新代码：

import { useTheme, STORAGE_KEYS } from '@kernelift/theme';

const { theme, setTheme } = useTheme();
setTheme('dark'); // 自动持久化

与 Element Plus 兼容

主题系统会自动同步 --kl-* 和 --el-* 变量：

import { useTheme } from '@kernelift/theme';

const { updateLightConfig } = useTheme();

// 同时更新 --kl-color-primary 和 --el-color-primary
updateLightConfig({
  colors: {
    primary: { base: '#409eff' }
  }
});

导出内容

Composable

• useTheme - 主题管理 composable

类型定义

• ThemeMode - 主题模式类型
• BaseStyleConfig - 完整主题配置
• ThemeModeConfig - 单一主题配置
• SemanticColorConfig - 语义色配置
• ColorConfig - 颜色配置
• TextColorConfig - 文本颜色配置
• BorderColorConfig - 边框颜色配置
• BgColorConfig - 背景色配置
• FillColorConfig - 填充色配置
• BorderRadiusConfig - 圆角配置
• ThemeStorageOptions - 存储选项

默认配置

• defaultBaseStyleConfig - 完整默认配置
• defaultLightConfig - 默认亮色配置
• defaultDarkConfig - 默认暗色配置
• brandLightConfig - 品牌亮色配置
• brandDarkConfig - 品牌暗色配置

工具函数

• createSemanticColor - 创建语义色配置
• deepMergeThemeConfig - 深度合并主题配置
• mixColor - 颜色混合
• generateColorLevels - 生成颜色层级
• completeSemanticColor - 完善语义色配置
• normalizeColor - 标准化颜色值
• normalizeCssValue - 标准化 CSS 值

常量

• STORAGE_KEYS - 存储键名
• BASE_STYLE_CSS_VARS - CSS 变量名枚举
• KL_TO_EL_VAR_MAP - kl 到 el 变量映射