TechUI Docs

简中

EN

简中

EN

主题

主题概览 ​

TechUI 的主题系统采用 “数据驱动” 的设计模式。与传统的仅依赖 CSS 预处理器（Less/Sass）变量的主题方案不同，TechUI 将主题定义为一份标准的 JavaScript 数据结构。

这份数据在应用运行时被 TuiProvider 解析，并分发到两个不同的渲染通道：CSS 变量 和 Vue 响应式状态。这种设计确保了无论是 DOM 元素还是 Canvas 画布（如 ECharts、Three.js），都能实时响应主题的切换。

核心架构 ​

TechUI 主题系统的运作流程如下：

  1. 定义 (Definition): 开发者创建一个包含语义化颜色定义的 JS 对象（如 lightBlue.js），并使用 tTheme.register 进行注册。
  2. 处理 (Processing): TuiProvider 组件初始化时，读取当前激活的主题数据。
  3. 分发 (Distribution):
    • 通道 A (CSS): 系统自动生成 CSS 变量（CSS Custom Properties）并注入到文档根节点。例如 primary.base 转化为 --primary-base。
    • 通道 B (JS): 系统将完整的主题树挂载到 $tState.themePalette，供组件逻辑和图表库使用。

为什么选择这种设计？ ​

语义化与标准化 ​

我们不再关注具体的色值（如 #1890ff），而是关注颜色的语义。 所有的 TechUI 主题都遵循同一套 Schema 结构（如 common, font, primary, danger）。这意味着开发者只需编写一次代码（例如 color: var(--danger-base)），即可在任何主题下完美展示，无需担心深浅色模式的适配问题。

真正的全栈主题支持 ​

传统的 CSS 主题方案难以触达 <canvas> 内部。 在数据大屏或复杂应用中，ECharts 图表、Three.js 3D 场景或 OpenLayers 地图通常需要传入具体的十六进制颜色值。TechUI 通过 $tState.themePalette 和 $tc() 函数，让 JS 侧也能像写 CSS 一样轻松获取当前主题色，从而实现图表与 UI 的无缝融合。

运行时零编译切换 ​

不需要在构建时生成多份 CSS 文件。TechUI 的主题切换是纯运行时的，切换过程就像更新一个 Vue 变量一样简单且高效。配合视图转场动画，可以实现影院级的丝滑换肤体验。

数据流向图 ​

text
[ 主题文件 (lightBlue.js) ]
          |
          v
[ tTheme.register (注册中心) ]
          |
   (应用启动 / 切换主题)
          |
          v
[ TuiProvider (核心处理) ]
          |
          +-------------------------------------+
          |                                     |
          v                                     v
[ CSS 变量系统 ]                        [ Vue 响应式系统 ]
:root {                                 $tState.themePalette
  --primary-base: #007bff;              {
  --bg-root: #ffffff;                     primary: { base: "#007bff" },
}                                         bg: { root: "#ffffff" }
          |                                     }
          |                                     |
          v                                     v
   [ DOM 组件 ]                         [ Canvas/JS 组件 ]
   div {                                echarts.init(..., {
     background: var(--bg-root);          color: [ theme.primary.base ]
   }                                    })

核心能力一览 ​

  • 双模态访问: CSS 中使用 var(--key-sub)，JS 中使用 $tc('key.sub')。
  • 自动图表适配: 开启 ECharts 特性后，自动生成并注册对应的 ECharts 主题 JSON。
  • 内置色阶算法: 基于 @techui/colors，主题文件只需定义基准色，系统可自动计算衍生的渐变色或交互状态色。
  • 三维适配: 包含 scifi（科幻）字段，专门用于配置 3D 面板和装饰性 SVG 组件的发光与高亮效果。