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/engine-chart
- Chart Engine Plugin@univerjs-pro/sheets-chart
- Sheet Chart Plugin@univerjs-pro/sheets-chart-ui
- Sheet Chart UI Plugin
Presets Installation
Follow the installation guide in Print Feature.
Piecemeal Installation
npm install @univerjs-pro/engine-chart @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/engine-chart @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+
To get full defination of facade api, please refer to FacadeAPI .
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.
Insert a Chart
FWorksheet.newChart()
method is used to create a chart builder, which returns an FChartBuilderBase
instance. You can set various properties of the chart by chaining methods.
Then call build()
to generate an IChartBuilderInfo
object, and use FWorksheet.insertChart(chartBuildInfo: IChartBuilderInfo)
method to insert the chart into the sheet.
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Create a column chart with data source A1:D6.
// The starting position is upper-left corner of cell B2.
// The width of the chart is 600 and the height is 400.
const chartInfo = fWorksheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.setWidth(600)
.setHeight(400)
.build();
await fWorksheet.insertChart(chartInfo);
Here are some member methods on FChartBuilderBase
:
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
* ```typescript
* 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 fWorksheet = fWorkbook.getActiveSheet();
// Create a line chart
const chartInfo = fWorksheet.newChart()
// As a line chart
.asLineChart()
// Set the data source A1:D6
.addRange('A1:D6')
// Set the starting position to the upper-left corner of cell B2
.setPosition(1, 1, 0, 0)
// Set the indicator line style
.setAxisPointerStyle({
indicatorLabelColor: '#ff0000',
indicatorLineType: univerAPI.Enum.ChartBorderDashType.Solid,
indicatorLineColor: '#00ff00',
indicatorLabelTextColor: '#0000ff',
})
// Set the data point size to 10
.setDataPointSize(10)
// Set the data point shape to circular
.setDataPointShape(univerAPI.Enum.LinePointShape.CIRCLE)
// Generate builder info
.build();
const fChart = await fWorksheet.insertChart(chartInfo);
// Update the chart after 3 seconds
setTimeout(() => {
if (fChart) {
// Get the first series data
const first = fChart.getSeriesData()[0];
// Set the color of the first series to red
const newChartInfo = fWorksheet.newChart(fChart)
.setSeriesStyle(first.index, {
color: '#ff0000',
})
.build();
// Update the chart
fSheet.updateChart(newChartInfo);
}
}, 3000);
We also provide the following builders to create the corresponding charts. These builders can be created by like fWorkSheet.newChart().asLineChart()
, they are derived from FChartBuilderBase
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(univerAPI.Enum.ChartType.Column);
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 |
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 |
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 |
Get Charts
The FWorksheet.getCharts()
method is used to get all the charts in the current worksheet, returning an array of FChart[]
.
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Get all charts on the active sheet.
const charts = fWorksheet.getCharts();
console.log(charts);
Here are some member methods on FChart
:
Method | Description |
---|---|
getRange | Get the chart data source range |
getSeriesData | Get the series data |
getCategoryData | Get the category data |
updateRange | Update the chart data source range |
Update Chart
The FWorksheet.updateChart(chartBuildInfo: IChartBuilderInfo)
method is used to update the chart, passing in an IChartBuilderInfo
object to update the chart configuration.
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Create a column chart with data source A1:D6.
// The starting position is upper-left corner of cell B2.
const chartInfo = fWorksheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.build();
await fWorksheet.insertChart(chartInfo);
// Get all charts on the active sheet.
const charts = fWorksheet.getCharts();
// Update the first chart after 3 seconds.
setTimeout(() => {
const newChartInfo = fWorksheet.newChart(charts[0])
.asLineChart()
.setOptions('legend.position', univerAPI.Enum.LegendPositionEnum.Right)
.build();
fWorksheet.updateChart(newChartInfo);
}, 3000);
Remove Chart
The FWorksheet.removeChart(chart: FChart)
method is used to remove a chart, passing in an FChart
object to remove the specified chart.
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// Create a column chart with data source A1:D6.
// The starting position is upper-left corner of cell B2.
const chartInfo = fWorksheet.newChart()
.setChartType(univerAPI.Enum.ChartType.Column)
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.build();
await fWorksheet.insertChart(chartInfo);
// Get all charts on the active sheet.
const charts = fWorksheet.getCharts();
// Remove the first chart after 3 seconds.
setTimeout(async () => {
await fWorksheet.removeChart(charts[0]);
console.log(fWorksheet.getCharts());
}, 3000);
Chart Theme
The FChartBuilderBase.registerChartTheme(themeName: string, theme: IEchartTheme)
method is used to register a chart theme, passing in a theme name and theme object to register a custom theme.
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 fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// register your theme
const theme = { // your theme object
'version': 1,
'themeName': 'myTheme',
'theme': {
// ... Some code is omitted for brevity
color: [
'#893448',
'#d95850',
'#eb8146',
'#ffb248',
'#f2d643',
'#ebdba4'
],
// ... Some code is omitted for brevity
visualMapColor: [
'#893448',
'#d95850',
'#eb8146',
'#ffb248',
'#f2d643',
'rgb(247,238,173)'
],
// ... Some code is omitted for brevity
'axes': []
// ... Some code is omitted for brevity
}
};
fWorksheet.registerChartTheme('myTheme', theme);
// use your theme for chart
const chartInfo = fWorksheet.newChart()
.asLineChart()
.addRange('A1:D6')
.setPosition(1, 1, 0, 0)
.setTheme('myTheme')
.build();
await fWorksheet.insertChart(chartInfo);