主题

TechUI 拥有一套强大的全栈主题系统，通过“一套数据”同时驱动 CSS 样式和 JS 图表渲染。

详细文档

本页仅为功能速览。如需了解完整的语义结构、ECharts 集成原理及完整主题开发案例，请查阅 主题系统完整文档。

核心机制

• 数据驱动：主题是标准的 JavaScript 对象，而非单纯的 CSS 文件。
• 双向分发：系统会自动将主题数据转换为 CSS 变量（供样式使用）和 响应式状态（供 JS 逻辑使用）。
• 零编译切换：纯运行时切换，无需刷新页面，支持丝滑的转场动画。

引入与注册

在项目入口文件（main.js）中引入官方主题即可自动注册。

// 引入浅色主题 (作为默认)
import "@techui/themes/lightBlue";

// 引入深色主题 (开启切换功能)
import "@techui/themes/darkBlue";

提示：引入多个主题后，系统会自动显示主题切换控件。

开发使用

系统会自动生成语义化的 CSS 变量。变量名遵循 Kebab Case（短横线命名）。

常用变量示例：

.my-card {
  /* 通用背景与边框 */
  background: var(--common-bg);
  border: 1px solid var(--common-bd);

  /* 主色调文字 */
  color: var(--primary-base);
  
  /* 自动生成的透明度变量 (10% - 90%) */
  background: var(--primary-base_op1); /* 10% 透明度的主色背景 */
}

开发使用 JS

在 Vue 组件或 Canvas 绘图中，使用全局注入的 $tc 函数获取颜色。

import { inject, computed } from 'vue';

const { $tc, $c } = inject('$global');

// 1. 获取静态颜色字符串 (如 "#1890ff")
const color = $tc('primary.base');

// 2. 获取响应式颜色 (随主题切换自动更新)
const activeColor = computed(() => $tc('success.base', true).value);

// 3. 处理透明度 (推荐使用 $c 工具)
const maskColor = $c.fade($tc('common.bg'), 0.5);

切换控制

使用组件

直接在页面放置切换按钮，点击即可循环切换已注册的主题。或者在控制面板中进行主题切换。

<TuiThemeToggle />

<TuiThemeToggle direction="v" />

编程控制

使用 themeToggle 函数强制切换。

const { themeToggle } = inject('$global');

// 切换到深蓝主题
themeToggle('darkBlue', 'dark');

ECharts主题适配

如果开启了 features.echarts: true，图表会自动应用当前主题配色，无需额外配置。

常用语义速查

语义分类	键名 (Key)	说明
通用	common.bg, common.bg_layer	基础背景、容器背景
文字	font.base, font.weak	正文颜色、辅助文字颜色
主色	primary.base	品牌主色
功能色	success, warning, danger	状态反馈色 (包含 base, weaker, stronger 等)
图表	chart.palette	图表默认调色盘序列