# @visactor/vchart-semi-theme
## Description
The extension [Semi Design](https://github.com/DouyinFE/semi-design) themes for [VChart](https://github.com/VisActor/VChart).
## What is Semi
Semi Design is a design system designed, developed and maintained by the Douyin front-end team and the MED product design team. As a comprehensive, easy-to-use, and high-quality modern enterprise-level application UI solution, it is refined from the complex scenes of Bytedance various business lines, supports nearly a thousand platform products, and serves 100,000+ internal and external users.
After nearly two years of iteration, Semi Design has become a cross-departmental infrastructure after various types of business landing verification, and has formed a rich tool chain and ecology around the component library. In order to allow the increasingly mature design system to serve more users and to further explore the usage scenarios, we decided to open source Semi and use the power of the community to continuously improve and expand the capability boundary.
Currently, VChart provides specialized adaptation for Semi Design. More information about Semi Design can be found on the [website](https://semi.design/).
## Installing and Using VChart
Semi Design is currently mainly adapted to React projects. In React projects, you can use the following command to install react-vchart:
```bash
# npm
npm install @visactor/react-vchart
# yarn
yarn add @visactor/react-vchart
```
The method of drawing charts and more detailed guidance can be found in [this tutorial](https://visactor.io/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react).
## Chart Theme Package for Semi Design
In order to provide a better experience for VChart in the Semi page environment, VisActor has launched an additional theme package called `@visactor/vchart-semi-theme`. This package has the following features:
- Ready to use out of the box: With simple configuration, VChart styles can be automatically integrated into the Semi design language and also automatically adapted to theme packages customized by users through Semi DSM.
- Responsive: `@visactor/vchart-semi-theme` supports listening for changes of light/dark mode and theme switching on the page, and automatically updates the theme of the charts on the page.
### DEMO
For a complete demo, please visit the [codeSandBox page](https://vp4y9p.csb.app/).
### Installation
[https://www.npmjs.com/package/@visactor/vchart-semi-theme](https://www.npmjs.com/package/@visactor/vchart-semi-theme)
```bash
# npm
npm install @visactor/vchart-semi-theme
# yarn
yarn add @visactor/vchart-semi-theme
```
### Usage
To access the default functionality, simply execute the `initVChartSemiTheme` method once globally for initialization. This statement can usually be placed in the entry file of a React project. As an example:
```javascript
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();
```
The `initVChartSemiTheme` method supports passing in an object as a parameter, whose type declaration is:
```typescript
interface IInitVChartSemiThemeOption {
/** Initial light/dark mode */
defaultMode?: 'light' | 'dark';
/** Whether to listen for the light/dark mode switching and automatically change the chart theme. The default setting is true */
isWatchingMode?: boolean;
/** Whether to listen for theme switching and automatically change the chart theme. The default setting is false (applicable to the official theme switching interface of Semi: https://semi.design/dsm/install_switcher) */
isWatchingThemeSwitch?: boolean;
/** Specify a ThemeManager, usually not specified. If multiple versions of vchart coexist, it needs to be specified */
themeManager?: typeof ThemeManager;
}
```
For example, if you want to enable listening for theme switching on the user side, the initialization statement can be changed as follows:
```javascript
// initialization
initVChartSemiTheme({
isWatchingThemeSwitch: true
});
```
### Token Mapping
In terms of functional design of chart themes, VChart supports custom configuration of data palettes and semantic color palettes. Based on this feature, the combination of VChart and Semi Design has been implemented by `@visactor/vchart-semi-theme`.
#### Data Palette
Semi Design declared the corresponding token for the data palette for VChart. Users can configure the following tokens when customizing themes in DSM to customize the data palette for VChart. The data palette of charts will automatically apply these variables, and users do not need to intervene. This feature is implemented by `@visactor/vchart-semi-theme`.
Index |
Semi Token |
Default Color |
1 |
--semi-color-data-0
|
|
2 |
--semi-color-data-1
|
|
3 |
--semi-color-data-2
|
|
4 |
--semi-color-data-3
|
|
5 |
--semi-color-data-4
|
|
6 |
--semi-color-data-5
|
|
7 |
--semi-color-data-6
|
|
8 |
--semi-color-data-7
|
|
9 |
--semi-color-data-8
|
|
10 |
--semi-color-data-9
|
|
11 |
--semi-color-data-10
|
|
12 |
--semi-color-data-11
|
|
13 |
--semi-color-data-12
|
|
14 |
--semi-color-data-13
|
|
15 |
--semi-color-data-14
|
|
16 |
--semi-color-data-15
|
|
17 |
--semi-color-data-16
|
|
18 |
--semi-color-data-17
|
|
19 |
--semi-color-data-18
|
|
20 |
--semi-color-data-19
|
|
The corresponding colors of these tokens form VChart's default 20 color palette in Semi Design.
As described in the [document](https://visactor.io/vchart/guide/tutorial_docs/Theme/Theme_Concept_and_Design_Rules), the VChart data palette can also be dynamic and progressive. In general, the color palette will be dynamically adjusted based on the range of data item quantities. When there are no more than 10 data groups, a 10 color palette should be used; When there are more than 10 data groups, a 20 color palette is used. If there are more than 20 data groups, the palette colors will be applied repeatedly, starting from the first one.
`@visactor/vchart-semi-theme` will automatically draw 10 colors from the 20 color palette mentioned earlier to form a 10 color palette that is compatible with small amounts of data. The current method is to take even indexed colors, which means that the default 10 color palette consists of the color values corresponding to the following tokens:
序号 |
Semi Token |
默认色值 |
1 |
--semi-color-data-0
|
|
2 |
--semi-color-data-2
|
|
3 |
--semi-color-data-4
|
|
4 |
--semi-color-data-6
|
|
5 |
--semi-color-data-8
|
|
6 |
--semi-color-data-10
|
|
7 |
--semi-color-data-12
|
|
8 |
--semi-color-data-14
|
|
9 |
--semi-color-data-16
|
|
10 |
--semi-color-data-18
|
|
#### Semantic Color Palette
In addition to the tokens mentioned earlier, `@visactor/vchart-semi-theme` will also automatically crawl other tokens of the current Semi theme in the page environment to generate a VChart chart theme. These tokens are mainly used for the styles of various chart components. You can refer to the following document for details:
- [VChart Theme Concept and Design Rules](https://visactor.io/vchart/guide/tutorial_docs/Theme/Theme_Concept_and_Design_Rules)
### Static resources
This package contains both static theme JSON resources (static resources only apply to the default Semi theme), which can be used on demand.
- [semiDesignLight](https://raw.githubusercontent.com/VisActor/vchart-theme/main/packages/vchart-semi-theme/public/semiDesignLight.json) Semi Design - light
- [semiDesignDark](https://raw.githubusercontent.com/VisActor/vchart-theme/main/packages/vchart-semi-theme/public/semiDesignDark.json) Semi Design - dark
## Debug
Run the following command from any location in the project to start the dev server:
```bash
rush semi
```