TPower Design

Appearance

Return to top
On this page

TrinaPower Design

TrinaPower Design 是一个用于构建统一界面风格的设计系统，提供了主题管理、颜色定制和样式工具等功能。

功能特性

  • 主题管理：支持明亮/暗黑模式切换，支持主题颜色切换
  • 颜色定制：可自定义主题主色和相关颜色变量
  • 样式工具：提供 LESS 变量和样式组件
  • Vite 插件：支持构建时主题配置

安装

bash
pnpm add @trinapower/design

或使用 npm/yarn：

bash
npm install @trinapower/design
# 或
yarn add @trinapower/design

基本使用

导入样式

javascript
// 导入完整样式包
import "@trinapower/design";

// 导入cosine-fee子模块样式
import "@trinapower/design/cosine-fee";

主题管理

构建时插件配置

javascript
// vite.config.ts
import { defineConfig } from 'vite';
import { createThemePlugin } from '@trinapower/design/theme';
import { generateModifyVars } from '@trinapower/design/theme';

export default defineConfig({
  css: {
      preprocessorOptions: {
        less: {
          javascriptEnabled: true,
          // 配置全局变量
          modifyVars: generateModifyVars({ brand: VITE_GLOB_BRAND }),
        },
      },
  },
  plugins: [
    // 配置主题插件
    createThemePlugin({
      isBuild?: boolean,
      brand?: string, // 默认 admin
    })
  ]
});

运行时主题切换

javascript
import { ThemeManager } from "@trinapower/design/theme/runtime";

// 配置适配器
const adapter: ConfigAdapter = {
  // 获取当前主题模式
  getDarkMode: () => {
    // 返回本地维护的主题模式，例如从本地存储或状态管理中获取
    return "light";
  },
  // 获取当前头部背景颜色
  getHeaderBgColor: () => {
    // 返回本地维护的头部背景颜色
    return "#ffffff";
  },
  // 获取当前导航栏背景颜色
  getMenuBgColor: () => {
    // 返回本地维护的导航栏背景颜色
    return "#2468f2";
  },
  // 设置头部主题模式
  setHeaderTheme: (mode) => {
    //Todo 本地维护头部主题模式,项目内部维护实现
  },
  // 设置导航栏主题模式
  setMenuTheme: (mode) => {
    //Todo 本地维护导航栏主题模式,项目内部维护实现
  }
};

// 主题配置选项
const options: ThemeEngineOptions = {};

// 创建主题管理器实例
const themeManager = new ThemeManager(adapter, options);

// 更改主题主色
themeManager.changePrimaryColor("#1890ff");

// 切换暗黑模式
themeManager.setDarkMode("dark");

主要 API

ThemeManager

ThemeManager 是主题管理的核心类，提供了完整的主题配置和切换功能。

构造函数

  • constructor(adapter: ConfigAdapter, options?: ThemeEngineOptions): 创建主题管理器实例
    • adapter: 配置适配器，用于获取和设置主题配置
    • options: 主题引擎选项，用于自定义主题行为

主题配置

  • changePrimaryColor(color: string): 改变主题主色并更新所有相关颜色变量

    • color: 新的主色值（如 '#1890ff'）

  • setDarkMode(mode: 'light' | 'dark'): 切换主题模式

    • mode: 新的主题模式，可选值为 'light' 或 'dark'（默认值：'light'）

组件样式

  • updateHeaderBgColor(color?: string): 更新头部背景颜色

    • color: 可选，新的背景颜色值。如果未提供，则使用适配器配置的颜色

  • updateSidebarBgColor(color?: string): 更新侧边栏背景颜色

    • color: 可选，新的背景颜色值。如果未提供，则使用适配器配置的颜色

特殊模式

  • toggleGrayMode(enabled: boolean): 切换灰度模式

    • enabled: 是否启用灰度模式

  • toggleColorWeak(enabled: boolean): 切换色弱模式

    • enabled: 是否启用色弱模式

构建工具

  • createThemePlugin(options): 创建 Vite 主题插件

    • options.isBuild: 是否为构建模式
    • options.brand: 品牌标识，默认值为 'admin'

  • generateModifyVars(options): 生成 LESS 变量

    • options.brand: 品牌标识，用于生成品牌相关的颜色变量

配置选项

ThemeEngineOptions

typescript
interface ThemeEngineOptions {
  htmlRootSelector?: string; // HTML根元素选择器，默认：'#htmlRoot' 或 document.documentElement
  scopeAttr?: string; // 主题作用域属性名，默认：'data-theme'
}

ConfigAdapter

typescript
interface ConfigAdapter {
  getDarkMode(): ThemeMode; // 获取当前主题模式
  getHeaderBgColor(): string | undefined; // 获取当前头部背景颜色
  getMenuBgColor(): string | undefined; // 获取当前导航栏背景颜色
  setHeaderTheme(mode: ThemeMode): void; // 设置头部主题模式
  setMenuTheme(mode: ThemeMode): void; // 设置导航栏主题模式
}

核心常量

所有主题相关常量均可从 @trinapower/design/theme/runtime 导入：

typescript
// 默认主色
import { DEFAULT_PRIMARY_COLOR } from "@trinapower/design/theme/runtime";
// 输出: '#2468f2'

// 头部背景颜色变量
import { HEADER_BG_COLOR_VAR } from "@trinapower/design/theme/runtime";
// 输出: '--header-bg-color'

// 头部背景悬停颜色变量
import { HEADER_BG_HOVER_COLOR_VAR } from "@trinapower/design/theme/runtime";
// 输出: '--header-bg-hover-color'

// 头部菜单激活背景颜色变量
import { HEADER_MENU_ACTIVE_BG_COLOR_VAR } from "@trinapower/design/theme/runtime";
// 输出: '--header-active-menu-bg-color'

// 侧边栏暗色背景颜色变量
import { SIDER_DARK_BG_COLOR } from "@trinapower/design/theme/runtime";
// 输出: '--sider-dark-bg-color'

// 侧边栏暗色加深背景颜色变量
import { SIDER_DARK_DARKEN_BG_COLOR } from "@trinapower/design/theme/runtime";
// 输出: '--sider-dark-darken-bg-color'

// 侧边栏亮色背景颜色变量
import { SIDER_LIGHTEN_BG_COLOR } from "@trinapower/design/theme/runtime";
// 输出: '--sider-dark-lighten-bg-color'

// 主题模式常量
import { THEME } from "@trinapower/design/theme/runtime";
// 输出: { DARK: 'dark', LIGHT: 'light' }

// 默认暗黑模式
import { darkMode } from "@trinapower/design/theme/runtime";
// 输出: 'light'

// 应用预设颜色列表
import { APP_PRESET_COLOR_LIST } from "@trinapower/design/theme/runtime";
// 输出: ['#0960bd', '#0084f4', ...]

// 头部预设背景颜色列表
import { HEADER_PRESET_BG_COLOR_LIST } from "@trinapower/design/theme/runtime";
// 输出: ['#ffffff', '#151515', ...]

// 侧边栏预设背景颜色列表
import { SIDE_BAR_BG_COLOR_LIST } from "@trinapower/design/theme/runtime";
// 输出: ['#001529', '#212121', ...]

注意事项

  1. 确保在使用 ThemeManager 之前正确配置 ConfigAdapter
  2. 主题切换会动态修改 DOM 元素的样式属性，可能影响性能
  3. 建议在应用初始化时创建 ThemeManager 实例
  4. 颜色生成策略允许高度自定义主题颜色