@TechUI/Themes 简介

TechUI Themes (主题系统) 是 TechUI 组件库的视觉灵魂。

与传统的仅依赖 CSS 预处理器（Less/Sass）变量的主题方案不同，TechUI 采用 “数据驱动 (Data-Driven)” 的设计模式。我们将主题定义为一份标准的 JavaScript 数据结构，这使得 TechUI 能够突破 DOM 的限制，实现对 Canvas、ECharts 乃至 WebGL 场景的全栈式主题覆盖。

一句话总结：一套数据，双向分发（CSS + JS），运行时零编译切换。

核心架构 双通道渲染

TechUI 的主题系统通过 TuiProvider 将配置分发到两个渲染通道，确保应用中所有角落的视觉一致性。

通道 A：CSS 变量系统 (The DOM World)

系统自动将 JS 主题树扁平化并生成 CSS 自定义属性（CSS Variables），注入到文档根节点。

• 转换规则：primary.base -> --primary-base
• 使用场景：所有的 Vue 组件、布局容器、HTML 元素。
• 优势：利用浏览器原生渲染能力，性能零开销。

通道 B：JS 响应式状态 (The Canvas World)

系统将完整的主题对象挂载到全局响应式状态 $tState.themePalette 中。

• 使用场景：ECharts 图表、Three.js 场景、OpenLayers 地图等无法读取 CSS 变量的 Canvas 画布。
• 优势：解决了传统 CSS 主题方案无法触达 Canvas 内部的痛点，实现图表颜色随主题自动变更。

内置主题

目前官方提供三套经过精心调色的标准主题：

主题标识	名称	描述
lightBlue	浅蓝 (默认)	明亮清爽，适合大多数 B 端数据管理后台。
darkBlue	深蓝	专业现代，适合指挥中心、数据大屏场景。
darkBlack	深黑	优雅神秘，高对比度，适合夜间模式或暗黑风格应用。

引入与激活

在 TechUI 中，主题是按需加载的。您需要在应用入口文件（如 main.ts）中显式引入想要使用的主题。

引入主题

// main.ts

// 引入浅色主题 (必选推荐，作为兜底)
import "@techui/themes/lightBlue";

// 引入深色主题 (可选，引入后即可切换)
import "@techui/themes/darkBlue";

单/多主题策略

系统会自动检测已注册的主题数量：

• 单主题模式：若只引入了 lightBlue，全局主题切换器会自动隐藏。
• 多主题模式：若引入了多个主题，用户可通过控制面板或 <TuiThemeToggle> 组件在它们之间实时切换，无需刷新页面。

开发指南 如何使用主题

在 CSS / Less 中调用

使用 CSS 变量，遵循扁平化命名规范。

.my-card {
  /* 格式: --分类-属性 */
  background: var(--common-bg);
  border: 1px solid var(--primary-base);
  color: var(--font-primary);
}

在 JavaScript / Vue 中调用

使用全局工具函数 $tc (Get Theme Color) 或直接访问 Store。

// 方式 A: 使用工具函数 (推荐)
const color = $tc('primary.base');

// 方式 B: 在 ECharts 配置中使用
import { computed } from 'vue';
import { useStore } from 'vuex'; // 或 pinia

const option = computed(() => {
  // 获取当前主题调色板
  const palette = $tState.themePalette;
  return {
    backgroundColor: palette.common.bg, // 动态响应主题切换
    series: [{
      itemStyle: { color: palette.primary.base }
    }]
  };
});

主题定制规则

如果您需要开发自定义主题或扩展现有主题，请务必遵守以下严格规范，以确保系统兼容性。

命名规范 (Naming)

• 小驼峰 (camelCase)：绝大多数属性（如 primary, base）。
• 蛇形后缀 (Snake Suffix)：仅用于特定状态。
• _hov (hover 悬停), _act (active 激活), _dis (disabled 禁用)
• _op1 ~ _op9 (opacity 透明度)

常用简写 (Abbreviations)

为了缩短 CSS 变量长度，我们规定了以下简写：

• background -> bg
• border -> bd
• fontColor -> fc
• highlight -> hlite

自动透明度变体 (Auto Opacity)

系统会自动为 primary, success, danger 等核心颜色的 base, bg, bd 属性生成透明度变体，您无需手动定义。

• 定义：primary: { base: '#007bff' }
• 自动生成：--primary-base_op1 (10%透明度), --primary-base_op5 (50%透明度)。

注册自定义主题

您可以使用 tTheme.register API 将自研主题注入系统。

import { tTheme } from "@techui/utils";
import { $c } from "@techui/colors";

tTheme.register({
  value: "myLuxuryGold",    // 唯一 ID
  scheme: "dark",           // 基础色系 (light/dark)
  colors: [$c.orl5, "#000"],// 预览色块
  data: {
    common: { bg: "#000000", bd: "#FFD700" }, // 遵循完整 Schema
    primary: { base: "#FFD700", ... },
    // ... 其他必要字段
  }
});