ECharts Integration

TechUI's theme system is deeply integrated with ECharts. When ECharts features are enabled, the system automatically converts the color scheme (Colors) and font configuration (Fonts) of the current TechUI theme into a theme JSON that ECharts can recognize, and dynamically registers it.

This means you do not need to write complex style configurations for charts separately; all charts will automatically adapt to the current system theme (such as dark/light mode switching).

Enabling the Function

ECharts theme integration is enabled on demand. You need to set features.echarts to true during application initialization.

// main.js
const params = {
  // ...other configurations
  features: {
    echarts: true, // Enable ECharts integration
    admin: true
  }
}
TechUIInit(params);

When this feature is enabled, TuiProvider automatically handles ECharts themes at the following times:

1. When the application initializes.
2. When themeToggle is called to switch themes.

Configuration Data Mapping

The chart object in TechUI's theme files (such as lightBlue.js) is specifically used to control chart styles. The system maps these semantic variables to specific ECharts configuration items via an internal converter (echartsTheme.js).

The following is the correspondence between the themeData.chart structure and ECharts components:

Palette

Controls the default color sequence for basic charts such as bar charts, line charts, and pie charts.

• Configuration Item: chart.palette
  • Type: Array (Array of color values)
  • Mapping Logic: The system automatically generates a richer gradient color scale based on the colors in the array using $c.scale and assigns it to the color attribute of ECharts.

Axis & Lines

Controls the styles of axes and grid lines for Cartesian coordinate systems (Grid) and Radar charts (Radar).

• Configuration Item: chart.line
  • weak: Used for split lines (SplitLine) or minor ticks.
  • base: Used for axis lines (AxisLine) or major borders.
  • strong: Used for gauge outer frames or emphasized lines.

Map & Geo

Controls the fill, border, and interaction states of map areas.

• Configuration Item: chart.map
  • bg / bd: Background color and border color of the area in the normal state.
  • bg_hov / bd_hov: Background and border in the highlighted (Emphasis) state.
  • bg_act / bd_act: Background and border in the selected (Select) state.
  • fc: Map label text color.
  • shadow: Map shadow color.

VisualMap

Controls the gradient colors for heat maps or data ranges.

• Configuration Item: chart.visual
• Mapping Logic: Generates a 4-level color scale based on the configured start and end colors, and assigns it to visualMap.color.

Internal Conversion Logic

The system uses echartsTheme.js internally for conversion. It not only uses the chart object but also reuses other common variables in the theme to ensure high consistency between charts and the UI:

• Background: Uses common.bg as the background color for Tooltips.
• Text: Uses font.base as the default color for chart titles, legends, and axis labels; uses font.weak as the subtitle color.
• Sci-Fi Elements: If the theme contains scifi configuration, the Timeline component will reference scifi.hlite and scifi.focus colors.

Usage in Projects

Automatic Application

If you are using chart components encapsulated by TechUI (such as <TuiChart> or <TuiMap>), they will automatically retrieve the current theme name and initialize.

Manual Initialization

If you use the ECharts native API directly, you can obtain the current theme name through the global configuration:

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

// In the component
const { $globalConfig } = inject('$global');
const chartRef = ref(null);

onMounted(() => {
  // $globalConfig.theme is the theme name registered in ECharts (e.g., 'lightBlue')
  const myChart = echarts.init(chartRef.value, $globalConfig.theme);
  
  myChart.setOption({ ... });
});

Responding to Theme Switching

When the global theme switches, ECharts instances usually need to be destroyed and recreated or have their configuration reset. If you use watch to listen to $gTheme, please ensure you re-initialize the chart:

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

watch($gTheme, (newTheme) => {
  if (myChart) {
    myChart.dispose();
  }
  // Initialize with the new theme name
  myChart = echarts.init(chartRef.value, newTheme);
  myChart.setOption(option);
});