TechUI Docs

简中

EN

简中

EN

主题

ECharts 主题集成 ​

TechUI 的主题系统与 ECharts 深度集成。当启用了 ECharts 特性时，系统会自动将当前 TechUI 主题的配色方案（Colors）和字体配置（Fonts）转换为 ECharts 能够识别的主题 JSON，并进行动态注册。

这意味着您无需为图表单独编写复杂的样式配置，所有的图表将自动适配当前的系统主题（如深色/浅色模式切换）。

开启功能 ​

ECharts 主题集成是按需开启的。需要在应用初始化时，将 features.echarts 设置为 true。

javascript
// main.js
const params = {
  // ...其他配置
  features: {
    echarts: true, // 开启 ECharts 集成
    admin: true
  }
}
TechUIInit(params);

当此功能开启后，TuiProvider 会在以下时机自动处理 ECharts 主题：

  1. 应用初始化时。
  2. 调用 themeToggle 切换主题时。

配置数据映射 ​

TechUI 的主题文件（如 lightBlue.js）中的 chart 对象专门用于控制图表样式。系统通过内部转换器 (echartsTheme.js) 将这些语义化变量映射到 ECharts 的具体配置项。

以下是 themeData.chart 结构与 ECharts 组件的对应关系：

调色盘 (Palette) ​

控制柱状图、折线图、饼图等基础图表的默认颜色序列。

  • 配置项: chart.palette
    • 类型: Array (颜色值数组)
    • 映射逻辑: 系统会自动基于数组中的颜色，使用 $c.scale 生成更丰富的渐变色阶，赋值给 ECharts 的 color 属性。

坐标轴与线条 (Axis & Lines) ​

控制直角坐标系（Grid）、雷达图（Radar）的轴线、网格线样式。

  • 配置项: chart.line
    • weak: 用于分割线 (SplitLine) 或次要刻度。
    • base: 用于轴线 (AxisLine) 或主要边框。
    • strong: 用于仪表盘外框或强调线条。

地图与地理坐标 (Map & Geo) ​

控制地图区域的填充、边框以及交互状态。

  • 配置项: chart.map
    • bg / bd: 普通状态下的区域背景色与边框色。
    • bg_hov / bd_hov: 高亮（Emphasis）状态下的背景与边框。
    • bg_act / bd_act: 选中（Select）状态下的背景与边框。
    • fc: 地图标签文字颜色。
    • shadow: 地图阴影颜色。

视觉映射 (VisualMap) ​

控制热力图或数据范围的渐变色。

  • 配置项: chart.visual
  • 映射逻辑: 基于配置的起止颜色，生成 4 级色阶，赋值给 visualMap.color。

内部转换逻辑 ​

系统内部使用 echartsTheme.js 进行转换。它不仅使用了 chart 对象，还复用了主题中的其他通用变量，以确保图表与 UI 高度统一：

  • 背景: 使用 common.bg 作为 Tooltip 的背景色。
  • 文字: 使用 font.base 作为图表标题、图例、坐标轴标签的默认颜色；使用 font.weak 作为副标题颜色。
  • 科幻元素: 如果主题包含 scifi 配置，时间轴（Timeline）组件会引用 scifi.hlite 和 scifi.focus 颜色。

在项目中使用 ​

自动应用 ​

如果您使用的是 TechUI 封装的图表组件（如 <TuiChart> 或 <TuiMap>），它们会自动获取当前主题名称并初始化。

手动初始化 ​

如果您直接使用 ECharts 原生 API，可以通过全局配置获取当前主题名称：

javascript
import * as echarts from 'echarts';
import { inject, onMounted, ref } from 'vue';

// 在组件中
const { $globalConfig } = inject('$global');
const chartRef = ref(null);

onMounted(() => {
  // $globalConfig.theme 即为注册到 ECharts 中的主题名称（如 'lightBlue'）
  const myChart = echarts.init(chartRef.value, $globalConfig.theme);
  
  myChart.setOption({ ... });
});

响应主题切换 ​

当全局主题切换时，ECharts 实例通常需要销毁重建或重新设置配置。如果您使用了 watch 监听 $gTheme，请确保重新初始化图表：

javascript
import { watch } from 'vue';
const { $gTheme } = inject('$global');

watch($gTheme, (newTheme) => {
  if (myChart) {
    myChart.dispose();
  }
  // 使用新主题名称初始化
  myChart = echarts.init(chartRef.value, newTheme);
  myChart.setOption(option);
});