Chart 0.5.0+
Facade API | Has Paid Plan | Univer Server | Univer on Node.js | Preset |
---|---|---|---|---|
✅ | ✅ | - | ✅ | UniverSheetsAdvancedPreset |
Chart Feature provide the ability to insert floating charts based on range data in spreadsheets.
This feature includes the following plugin packages:
@univerjs-pro/sheets-chart
- Chart plugin@univerjs-pro/sheets-chart-ui
- Chart UI plugin
Presets Installation
Follow the installation guide in Print Feature.
Piecemeal Installation
npm install @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import SheetsChartEnUS from '@univerjs-pro/sheets-chart/locale/en-US';
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui';
import SheetsChartUIEnUS from '@univerjs-pro/sheets-chart-ui/locale/en-US';
import '@univerjs-pro/sheets-chart-ui/facade';
import '@univerjs-pro/sheets-chart-ui/lib/index.css';
const univer = new Univer({
theme: defaultTheme,
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: merge(
SheetsChartEnUS,
SheetsChartUIEnUS
),
},
});
univer.registerPlugin(UniverSheetsChartPlugin);
univer.registerPlugin(UniverSheetsChartUIPlugin);
Univer on Node.js Piecemeal Installation
npm install @univerjs-pro/sheets-chart
import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import SheetsChartEnUS from '@univerjs-pro/sheets-chart/locale/en-US';
const univer = new Univer({
theme: defaultTheme,
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: merge(
SheetsChartEnUS,
),
},
});
univer.registerPlugin(UniverSheetsChartPlugin);
Chart Introduction
Charts are a way to visualize data, helping users understand data more intuitively. In Sheets, you can use the chart feature to convert data into charts, making it easier to display relationships and trends in the data.
We provide the following types of charts:
- Line Chart: Line charts are used to show trends in data over time, suitable for time series data.
- Column Chart: Column charts are used to show the size relationship of data, suitable for comparing data.
- Pie Chart/Doughnut Chart/Rose Chart: Pie charts are used to show the proportion of data, suitable for displaying the relative proportions of data.
- Scatter Chart: Scatter charts are used to show the distribution of data, suitable for displaying the correlation of data.
- Area Chart: Area charts are used to show the cumulative relationship of data, suitable for displaying trends in data.
- Bar Chart/Stacked Bar Chart/Percentage Stacked Bar Chart: Bar charts are used to show the size relationship of data, suitable for comparing data.
- Radar Chart: Radar charts are used to show the multidimensional relationship of data, suitable for displaying multidimensional analysis of data.
- Combination Chart: Combination charts are used to show the relationship of multiple sets of data, suitable for comparing multiple sets of data.
In Sheets, you can choose different types of charts as needed to better display the data. We will continue to optimize the chart feature based on user feedback, providing more types of charts to better meet user needs.
Following is the enumeration type of Univer chart. You can get all supported types of charts and configuration options by viewing these enumerations:
Show Enumerate
export enum ChartAttributeBits {
Stack = 1 << 30,
PercentStack = 1 << 29 | ChartAttributeBits.Stack,
Horizontal = 1 << 28,
}
export enum ChartTypeBits {
None = 0,
Line = 1 << 1,
Column = 1 << 2,
ColumnStacked = ChartTypeBits.Column | ChartAttributeBits.Stack,
ColumnPercentStacked = ChartTypeBits.Column | ChartAttributeBits.PercentStack,
Bar = 1 << 2 | ChartAttributeBits.Horizontal,
BarStacked = ChartTypeBits.Bar | ChartAttributeBits.Stack,
BarPercentStacked = ChartTypeBits.Bar | ChartAttributeBits.PercentStack,
Pie = 1 << 3,
Doughnut = 1 << 8 | ChartTypeBits.Pie,
Area = 1 << 4,
AreaStacked = ChartTypeBits.Area | ChartAttributeBits.Stack,
AreaPercentStacked = ChartTypeBits.Area | ChartAttributeBits.PercentStack,
Radar = 1 << 5,
Scatter = 1 << 6,
Combination = 1 << 7,
}
Facade API 0.5.2+
In Univer Sheets, you can use the Facade API to create, configure, and manage charts. The Facade API is a programming interface for charts, making it easier for you to use the chart feature.
Chart Builder
We provide a ChartBuilder to set various properties of the chart, and then create the chart by calling the build method of the ChartBuilder. Here is an example of setting up a line chart:
import { ChartTypeBits, LegendPositionEnum } from '@univerjs-pro/sheets-chart';
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
// Get the builder needed to build
const fChartBuilder = fSheet.newChart();
// Set the corresponding properties
const chartBuildInfo = fChartBuilder
.addRange('Sheet1!A1:B4')
.setChartType(ChartTypeBits.Line)
.setPosition(5, 5, 0, 0)
.setXAxisTitle('Sales Performance')
.setOptions('legend.position', LegendPositionEnum.Right)
.build();
// Insert into the corresponding sheet
fSheet.insertChart(chartBuildInfo);
On FWorksheet, we have mixed in the following APIs to operate charts:
Method | Description |
---|---|
insertChart | Insert a chart |
updateChart | Update chart configuration |
newChart | New a chart builder |
getCharts | Get the list of charts in the current sheet |
removeChart | Remove a chart |
registerChartTheme | Register a chart theme |
Here are some member methods on ChartBuilder:
Method | Description |
---|---|
addRange | Specify the data source range for the chart |
setPosition | Set the chart position using row and column anchors |
setAbsolutePosition | Set the chart position using pixel values |
setChartType | Set the chart type |
setWidth | Set the chart width |
setHeight | Set the chart height |
setOptions | Set chart options |
setTransposeRowsAndColumns | Transpose rows and columns |
setTheme | Set the theme |
setXAxisTitle | Set the X-axis title |
setYAxisTitle | Set the Y-axis title |
setRightYAxisTitle | Set the right Y-axis title |
setXAxisTextStyle | Set the X-axis title style |
setYAxisTextStyle | Set the Y-axis title style |
setRightYAxisTextStyle | Set the right Y-axis title style |
setInvalidValueStrategy | Set the display mode for empty cells |
setAxisPointerStyle | Sets the axis pointer style |
setALLSeriesStyle | Sets styles for all series |
setSeriesStyle | Sets the series style by series index |
build | Generate builder info for inserting/updating the chart |
Currently, we support the following configuration options, you can refer to IChartBuildOptions for the corresponding configuration:
Show configuration
export interface IChartBuildOptions {
/**
* @property {string} [title] The title of the chart.
*/
title?: {
/**
* @property {string} [titlePosition] The position of the chart title.
*/
position?: TitlePositionEnum;
} & IChartTextStyle;
/**
* @property {string} [legend] The legend of the chart.
*/
legend?: {
/**
* @property {string} [legendPosition] The position of the legend.The possible values are 'top', 'bottom', 'left', 'right' & 'hide'.
*/
position?: LegendPositionEnum;
/**
* @property {number} [fontSize] The font size of the legend.
*/
fontSize?: number;
/**
* @property {string} [color] The font color of the legend.
*/
color?: string;
/**
* @property {string} [bold] The font style of the legend.
*/
bold?: boolean;
/**
* @property {string} [italic] The font weight of the legend.
*/
italic?: boolean;
/**
* @property {SelectModeEnum} [selectMode] The select mode of the legend.The possible values are 'single', 'multiple' & 'close'.
*/
selectMode?: SelectModeEnum;
};
/**
* @property {string} [xAxisTitle] The x-axis title of the chart.
* @example
* ```ts
* chartBuilder.setOptions('xAxisTitle.content', 'xAxis Title text')
* .setOptions('xAxisTitle.font', 1)
* .setOptions('xAxisTitle.fontSize', 12)
* .setOptions('xAxisTitle.fontColor', '#ff0000')
* .build();
* ```
*/
xAxisTitle?: IChartTextStyle;
/**
* @property {string} [rightYAxisTitle] The right y-axis title of the chart.
*/
yAxisTitle?: IChartTextStyle;
/**
* @property {string} [rightYAxisTitle] The right y-axis title of the chart.
*/
rightYAxisTitle?: IChartTextStyle;
xAxis?: IAxisOptions;
yAxis?: IAxisOptions;
yRightAxis?: IAxisOptions;
axisPointer?: {
/**
* @property {string} [indicatorLineType] The line type of the axis pointer.
*/
indicatorLineType?: string;
/**
* @property {ChartBorderDashType} [indicatorLineColor] The line color of the axis pointer.The maybe values are 'solid', 'dotted', 'dashed'.
*/
indicatorLineColor?: ChartBorderDashType;
/**
* @property {string} [indicatorLabelColor] The line width of the axis pointer.
*/
indicatorLabelColor?: string;
/**
* @property {string} [indicatorLabelTextColor] The font color of the axis pointer.
*/
indicatorLabelTextColor?: string;
};
allSeriesStyle?: IAllSeriesStyle;
seriesStyleMap?: {
[id: string]: ISeriesStyle;
};
/**
* @property {string} [area] The area of line/area chart.
*/
area?: {
lineStyle: AreaLineStyle;
};
/**
* @property {string} [backgroundColor] The background color of the chart.
*/
backgroundColor?: string;
/**
* @property {string} [borderColor] The border color of the chart.
*/
borderColor?: string;
/**
* @property {boolean} [gradientFill] Whether to use gradient fill.This property does not work in line charts.
*/
gradientFill?: boolean;
/**
* @property {string} [theme] The theme of the chart.
*/
theme?: string;
/**
* @property {InvalidValueType} [invalidValueType] The display mode for empty cells.
*/
invalidValueType?: InvalidValueType;
}
Configuration options are set through the setOptions method, there are the following two methods:
setOptions(optionPath, optionVal)
:setOptions('legend.color', '#ff0000')
setOptions('', IChartBuildOptions)
:setOptions('', { legend: { color: '#ff0000', bold: true } })
Use facade create a line chart
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
// Create a builder for a line chart
const chartBuilder = fSheet.newChart().asLineChart();
const chartInfo = chartBuilder.addRange('A1:D6')
// Set position
.setPosition(1, 1, 0, 0)
// Set axis pointer
.setAxisPointerStyle({
indicatorLabelColor: '#ff0000',
indicatorLineType: 'solid', // ChartBorderDashType.Solid
indicatorLineColor: '#00ff00',
indicatorLabelTextColor: '#0000ff',
})
// Set data point size
.setDataPointSize(8)
// Set data point shape
.setDataPointShape('triangle')
// Trigger build
.build();
// Pass the build result to create the chart
const fChart = await fSheet.insertChart(chartInfo);
// Wait for the insert to complete and render
setTimeout(() => {
if (fChart) {
const chartBuilder = fSheet.newChart(fChart);
// Get the series data
const first = fChart.getSeriesData()[0];
// Set the color of the first series to red
chartBuilder.setSeriesStyle(first.index, {
color: '#ff0000',
}).build();
// Update info to chart
fSheet.updateChart(chartBuilder);
}
}, 1000);
Other builders 0.5.2+
We also provide the following builders to create the corresponding charts. These builders can be created by like fSheet.newChart().asLineChart()
, they are derived from ChartBuilder and have some specific configurations:
const lineChartBuilder = fWorkSheet.newChart().asLineChart();
const pieChartBuilder = fWorkSheet.newChart().asPieChart();
const radarChartBuilder = fWorkSheet.newChart().asRadarChart();
// Or you can use the following method to create a chart builder
const chartBuilder = fWorkSheet.newChart()
.setChartType(ChartTypeBits.Column);
- LineChartBuilder
Method | Description |
---|---|
setLineStyle | Set the line style, ‘line’ - straight line, ‘smooth’ - smooth line, ‘step’ - step line |
setDataPointShape | Set the data point shape, refer to LinePointShape for supported shapes |
setDataPointColor | Set the data point color |
setDataPointSize | Set the data point size |
build | Generate builder info for inserting/updating the chart |
- PieChartBuilder
Method | Description |
---|---|
setDoughnutHole | Set the size of the doughnut hole, range is 0-1 |
setBorderColor | Set the color value of the pie chart sectors |
setHasPaddingAngle | Set whether the pie chart sectors have padding angles (separation) |
setIsHalfPie | Set whether it is a half pie chart |
setRosePie | Set whether it is a rose chart |
setShowLabelLine | Show label lines |
build | Generate builder info for inserting/updating the chart |
- RadarChartBuilder
Method | Description |
---|---|
setShape | Set the default shape of the radar chart, currently supported values are: ‘polygon’ - polygon, ‘circle’ - circle |
setFill | Whether to fill the radar chart |
build | Generate builder info for inserting/updating the chart |
Chart Theme 0.5.2+
Univer chart is implemented based on the echarts library, so you can use the echart theme builder tool to create your custom theme. You can create your own theme on this website and download it as a configuration file. Use the following API to use your custom theme:
const theme = {}; // your theme object
// Register your downloaded theme
fSheet.registerChartTheme('myTheme', theme);
// Use the theme
const chartBuilder = fSheet.newChart().asLineChart();
const chartInfo = chartBuilder
.setTheme('myTheme') // The theme name is how we look up the theme. If not found, the default theme will be used
.addRange('A1:B8')
.build();
fSheet.insertChart(chartInfo);