适用于 Semi Design 的主题

什么是 Semi

Semi Design 是由抖音前端团队，MED 产品设计团队设计、开发并维护的设计系统。它作为全面、易用、优质的现代应用 UI 解决方案，从字节跳动各业务线的复杂场景提炼而来，支撑近千计平台产品，服务内外部 10 万+ 用户。

目前 VChart 针对 Semi Design 提供了专项适配。Semi Design 的更多信息可见 Semi 官网。

安装和使用 VChart

Semi Design 目前主要适配 React 工程。可以使用以下命令安装 react-vchart：

# 使用 npm 安装
npm install @visactor/react-vchart
# 使用 yarn 安装
yarn add @visactor/react-vchart

绘制图表以及更详细的指引详见这个教程。

适用于 Semi Design 的图表主题包

为了使 VChart 在 Semi 页面环境中获得更好的体验，VisActor 额外推出了 @visactor/vchart-semi-theme 主题包。这个包有以下特性：

• 开箱即用：经过简单的配置，就可以使 VChart 样式自动融入 Semi 设计语言，也会自动适配用户通过 Semi DSM 自定义的主题包。
• 响应式：@visactor/vchart-semi-theme 支持监听页面上的亮暗模式变化以及主题切换，自动对页面上的 VChart 图表的主题进行热更新。

DEMO

完整 demo 请访问此页面。

安装

https://www.npmjs.com/package/@visactor/vchart-semi-theme

# npm
npm install @visactor/vchart-semi-theme

# yarn
yarn add @visactor/vchart-semi-theme

使用

实现默认的功能，只需要在全局执行一次 initVChartSemiTheme 方法进行初始化。这个语句通常可以放在 React 项目的入口文件中。如以下示例：

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './app.jsx';
import { initVChartSemiTheme } from '@visactor/vchart-semi-theme';

// initialization
initVChartSemiTheme();

const dom = document.querySelector('#root');
const root = createRoot(dom);
root.render(<App />);

initVChartSemiTheme 方法支持传入一个对象作为 option，其类型声明为：

interface IInitVChartSemiThemeOption {
  /** 初始亮暗色模式 */
  defaultMode?: 'light' | 'dark';
  /** 是否监听亮暗色模式自动更改图表主题，默认为 true */
  isWatchingMode?: boolean;
  /** 是否监听主题变化自动更改图表主题，默认为 false（适用于 semi 官方主题切换接口：https://semi.design/dsm/install_switcher）*/
  isWatchingThemeSwitch?: boolean;
  /** 指定 ThemeManager，一般不用指定，如果遇到多版本 vchart 共存时需要指定 */
  themeManager?: typeof ThemeManager;
}

例如，如果要开启监听用户侧的主题切换，初始化语句可以改为这样：

// initialization
initVChartSemiTheme({
  isWatchingThemeSwitch: true
});

Token 映射

在图表主题的功能上，VChart 支持数据色板和语义色板的自定义配置。@visactor/vchart-semi-theme 基于这个特性实现了和 Semi Design 的结合。

数据色板

Semi Design 为 VChart 声明了数据色板对应的 token。用户可以在 DSM 自定义主题时配置以下 token，来自定义 VChart 的数据色板。VChart 图表的数据色板会自动应用这些变量，用户则不需要介入。这个功能由 @visactor/vchart-semi-theme 主题包实现。

序号	Semi Token	默认色值
1	--semi-color-data-0	#1664FF
2	--semi-color-data-1	#B2CFFF
3	--semi-color-data-2	#1AC6FF
4	--semi-color-data-3	#94EFFF
5	--semi-color-data-4	#FF8A00
6	--semi-color-data-5	#FFCE7A
7	--semi-color-data-6	#3CC780
8	--semi-color-data-7	#B9EDCD
9	--semi-color-data-8	#7442D4
10	--semi-color-data-9	#DDC5FA
11	--semi-color-data-10	#FFC400
12	--semi-color-data-11	#FAE878
13	--semi-color-data-12	#304D77
14	--semi-color-data-13	#8B959E
15	--semi-color-data-14	#B48DEB
16	--semi-color-data-15	#EFE3FF
17	--semi-color-data-16	#009488
18	--semi-color-data-17	#59BAA8
19	--semi-color-data-18	#FF7DDA
20	--semi-color-data-19	#FFCFEE

这些 token 的对应颜色组成了 VChart 在 Semi 下默认的 20 色色板。

如文档 VChart 主题概念和设计规范 所述，VChart 数据色板也可以是动态的、渐进式的。在一般情况下，色板会根据数据项数量的范围来动态调整。数据组不超过 10 个时，采用 10 色的色板；数据组超过 10 个时，采用 20 色的色板。如果数据组超过 20 个，则会重复应用色板颜色，从第 1 个开始。

@visactor/vchart-semi-theme 会自动从上文中的 20 色色板抽 10 个颜色形成小数据量下的 10 色色板。当前逻辑是取偶数索引的颜色，也就是说默认的 10 色色板由以下 token 对应的色值组成：

序号	Semi Token	默认色值
1	--semi-color-data-0	#1664FF
2	--semi-color-data-2	#1AC6FF
3	--semi-color-data-4	#FF8A00
4	--semi-color-data-6	#3CC780
5	--semi-color-data-8	#7442D4
6	--semi-color-data-10	#FFC400
7	--semi-color-data-12	#304D77
8	--semi-color-data-14	#B48DEB
9	--semi-color-data-16	#009488
10	--semi-color-data-18	#FF7DDA

语义色板

除了上文提到的 token 以外，@visactor/vchart-semi-theme 也会自动在页面环境爬取当前 Semi 主题的其他 token 来自动生成 VChart 图表主题。这些 token 主要用于各个图表组件的样式。具体可以参阅以下文档：

• VChart 主题概念和设计规范

静态资源

该包同时包含两个静态的主题 json 资源（静态资源只适用于默认的 Semi 主题），可以按需使用。

• semiDesignLight Semi Design - light
• semiDesignDark Semi Design - dark