Class: FChartBuilderBase
The base class for chart builder.The chart builder is used to create a chart in the sheet.For line chart , radar chart and pie chart, you use the LineChartBuilder, RadarChartBuilder and PieChartBuilder classes respectively.
Extends
FBase
.IPieChartBuilderMixin
.IRadarChartBuilderMixin
.ILineChartBuilderMixin
Extended by
Properties
Property | Type |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
Methods
addRange()
addRange(range): this
Adds a range to the chart this builder modifies
Parameters
Parameter | Type | Description |
---|---|---|
range | string | IRange | The range string or object to add for chart source data.The should be not a single cell. |
Returns
this
-this builder, for chaining
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder
// set the source data range of the chart
.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
.build();
fSheet.insertChart(chartInfo);
asLineChart()
asLineChart(): LineChartBuilder
Returns
asPieChart()
asPieChart(): PieChartBuilder
Returns
asRadarChart()
asRadarChart(): RadarChartBuilder
Returns
build()
build(): IChartBuilderInfo
Builds the chart to reflect all changes made to it.
Returns
-The chart builder info.
Description
This method does not automatically draw the chart on top of the spreadsheet. A new chart must be inserted via sheet.insertChart(chart), and an existing chart should be updated via sheet.updateChart(chart).
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
.setWidth(600)
.setHeight(400)
.build();
fSheet.insertChart(chartInfo);
clearRange()
clearRange(): this
Clears the range from the chart this builder modifies
Returns
this
-this builder, for chaining
getChartType()
getChartType(): ChartTypeBits
Gets the chart type of the chart this builder modifies.
Returns
ChartTypeBits
ChartType - The chart type of the chart this builder modifies.
Description
The chart type of the chart this builder modifies. The chart type (ChartTypeBits) can be found from package @univerjs-pro/sheets-chart. Please pay attention to the type of the chart you are creating, a Pie chart have a property of Doughnut is donut chart, and a Pie chart have a property of Rose is rose pie chart.But the chart builder will not change the chart type to the corresponding chart type.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const charts = fSheet.getCharts();
if(charts.length > 0) {
const chart = charts[0];
const chartBuilder = chart.getChartBuilder();
const chartType = chartBuilder.getChartType();
console.log(chartType); // The chart type of first chart.
}
setAbsolutePosition()
setAbsolutePosition(x, y): this
Sets the position, changing where the chart appears on the sheet by pixel.
Parameters
Parameter | Type | Description |
---|---|---|
x | number | The x-coordinate of the chart’s top left-hand corner. |
y | number | The y-coordinate of the chart’s top left-hand corner. |
Returns
this
-this builder, for chaining.
Description
The chart’s start anchor position is the top left-hand corner of the chart. This api is opposite to setPosition.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
// set the chart's top left-hand corner is at (100, 200) pixels.
.setAbsolutePosition(100, 200)
.build();
fSheet.insertChart(chartInfo);
setAllSeriesStyle()
setAllSeriesStyle(allSeriesStyle): this
Sets styles for all series.
Parameters
Parameter | Type | Description |
---|---|---|
allSeriesStyle | IAllSeriesStyle | The style for all series. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setALLSeriesStyle({
chartType: ChartTypeBits.Line,
rightYAxis: false,
color: '#ff0000',
fillOpacity: 0.5,
border: {
color: '#00ff00',
opacity: 0.5,
width: 1,
dashType: ChartBorderDashType.Solid,
},
})
.build();
fSheet.insertChart(chartInfo);
setAxisPointerStyle()
setAxisPointerStyle(style): this
Sets the axis pointer style
Parameters
Parameter | Type | Description |
---|---|---|
style | { indicatorLabelColor : string ; indicatorLabelTextColor : string ; indicatorLineColor : ChartBorderDashType ; indicatorLineType : string ; } | The style for the axis pointer. |
style.indicatorLabelColor ? | string | |
style.indicatorLabelTextColor ? | string | |
style.indicatorLineColor ? | ChartBorderDashType | |
style.indicatorLineType ? | string |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setAxisPointerStyle({
indicatorLabelColor: '#ff0000',
indicatorLineType: ChartBorderDashType.Solid,
indicatorLineColor: '#00ff00',
indicatorLabelTextColor: '#0000ff',
})
.build();
fSheet.insertChart(chartInfo);
// a AxisPointerStyle can be defined like following:
const chartInfo = chartBuilder.setOptions('axisPointer.indicatorLineColor', '#ff0000')
.setOptions('axisPointer.indicatorLineType', ChartBorderDashType.Solid)
.setOptions('axisPointer.indicatorLineColor', '#00ff00')
.setOptions('axisPointer.indicatorLabelTextColor', '#0000ff')
.build();
setChartType()
setChartType(chartType): this
The type of chart to create.
Parameters
Parameter | Type | Description |
---|---|---|
chartType | ChartTypeBits | The type of chart to create.Which can be found from package @univerjs-pro/sheets-chart. |
Returns
this
-this builder, for chaining.
Description
The type of chart to create. The following are the possible values: Line,Column,ColumnStacked,ColumnPercentStacked,Bar,BarStacked,BarPercentStacked,Pie,Doughnut,Area,AreaStacked,AreaPercentStacked,Radar,Scatter,Combination
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
.build();
fSheet.insertChart(chartInfo);
// update chart type to line
const updateBuilder = fSheet.newChart();
const updateChartInfo = updateBuilder.setChartType(univerAPI.Enum.ChartType.Line).build();
fSheet.updateChart(updateChartInfo);
setHeight()
setHeight(height): this
Sets the height of the chart in pixels.
Parameters
Parameter | Type | Description |
---|---|---|
height | number | The height of the chart in pixels. |
Returns
this
-this builder, for chaining.
setInvalidValueStrategy()
setInvalidValueStrategy(invalidValueType): this
Sets how to handle invalid data in the chart.The possible values are ‘zero’, ‘break’ & ‘link’.
Parameters
Parameter | Type | Description |
---|---|---|
invalidValueType | InvalidValueType | The type of invalid value to use. |
Returns
this
-this builder, for chaining.
Description
The default value is ‘zero’. It means that invalid data will be treated as zero. ‘break’ means that the chart will have a gap where the invalid data is. ‘link’ means that the chart will connect the data points on either side of the invalid data.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setInvalidValueAs(InvalidValueType.Zero)
.build();
fSheet.insertChart(chartInfo);
setOptions()
setOptions(optionPath, optionVal): this
The options for the chart. This function will overwrite existing options and merge new options property.
Parameters
Parameter | Type | Description |
---|---|---|
optionPath | string | The path of the option to set. A ” path means the root of the options object. |
optionVal | unknown | The value to set. Undefined value will be ignore , and null means delete the property.If a path is ”, the value must be the whole options object. |
Returns
this
The builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorkSheet = fWorkbook.getActiveSheet();
const chartBuilder = fWorkSheet.newChart().asPieChart();
const chartBuilderInfo1 = chartBuilder
.addRange('A1:D6')
.setOptions('title.content', 'Chart Title')
.setOptions('legend.position', 'right')
.setDoughnutHole(0.5)
.setHasPaddingAngle(true)
.setRosePie(true)
.setIsHalfPie(true)
.build();
// setOptions can be replaced by setOptions('', { ... })
const chartBuilderInfo2 = chartBuilder
.addRange('A1:D6')
.setOptions('', {
"title": {
"content": "Chart Title"
},
"legend": {
"position": "right"
},
"pie": {
"doughnutHole": 0.5,
"hasPaddingAngle": true,
"isHalfPie": true,
"rosePie": true
}
})
.build();
fWorkSheet.insertChart(chartBuilderInfo1);
// or they are same effect
// fWorkSheet.insertChart(chartBuilderInfo2);
setPosition()
setPosition(
anchorRowPos,
anchorColPos,
rowOffset,
columnOffset): this
Sets the position, changing where the chart appears on the sheet. anchorRowPos and anchorColPos are 0-indexed.This api can only work in the active sheet.
Parameters
Parameter | Type | Description |
---|---|---|
anchorRowPos | number | The chart’s top side is anchored in this row. |
anchorColPos | number | The chart’s left side is anchored in this column. |
rowOffset | number | The chart’s top left-hand corner is offset by this many pixels. |
columnOffset | number | The chart’s lower left-hand corner is offset by this many pixels. |
Returns
this
-this builder, for chaining.
Description
The chart’s start anchor position is the top left-hand corner of the chart. The rowOffset and columnOffset are the pixel offsets from the anchor position.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
// set the chart's top side is anchored in row 2, left side is anchored in column 5, and the chart's top left-hand corner is offset by 20 pixels.
.setPosition(2, 5, 20, 20)
.build();
fSheet.insertChart(chartInfo);
setRightYAxisTextStyle()
setRightYAxisTextStyle(textStyle): this
Sets the text style for the chart right y-axis. Only works in charts have right y-axis.
Parameters
Parameter | Type | Description |
---|---|---|
textStyle | IChartTextStyle | The text style for the chart right y-axis. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setRightYAxisTextStyle({
content: 'rightYAxis Title text',
fontSize: 12,
fontColor: '#ff0000'
})
.build();
fSheet.insertChart(chartInfo);
setRightYAxisTitle()
setRightYAxisTitle(title): this
Sets the title of the chart right y-axis.
Parameters
Parameter | Type | Description |
---|---|---|
title | string | The title of the chart right y-axis. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setRightYAxisTitle('rightYAxis Title text')
.build();
fSheet.insertChart(chartInfo);
setSeriesStyle()
setSeriesStyle(index, seriesStyle): this
Sets the series style by series index.
Parameters
Parameter | Type | Description |
---|---|---|
index | string | number | The index of the series to set the style for. |
seriesStyle | ISeriesStyle | The style for the series. |
Returns
this
-this builder, for chaining.
Description
Like setALLSeriesStyle, this difference is the style only set for the provide sty
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6').setChartType(2).setPosition(1, 1, 0, 0).build();
const fChart = await fSheet.insertChart(chartInfo);
// should wait the chart rendered
setTimeout(() => {
if (fChart) {
const chartBuilder = fSheet.newChart(fChart);
// get the series data
const first = fChart.getSeriesData()[0];
chartBuilder.setSeriesStyle(first.index, {
color: '#ff0000',
}).build();
fSheet.updateChart(chartBuilder);
}
},1000);
setTheme()
setTheme(theme): this
Sets the theme of the chart. If the theme name not registered, a default theme will be used.
Parameters
Parameter | Type | Description |
---|---|---|
theme | string | The theme name of the chart. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
.setTheme('univer1')
.build();
fSheet.insertChart(chartInfo);
setTransposeRowsAndColumns()
setTransposeRowsAndColumns(transposeRowsAndColumns): this
Sets whether to transpose the rows and columns of the chart.
Parameters
Parameter | Type | Description |
---|---|---|
transposeRowsAndColumns | boolean | Whether to transpose the rows and columns of the chart.The default value is false. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
// the chart will transpose the rows and columns
.setTransposeRowsAndColumns(true)
.build();
fSheet.insertChart(chartInfo);
setWidth()
setWidth(width): this
Sets the width of the chart in pixels.
Parameters
Parameter | Type | Description |
---|---|---|
width | number | The width of the chart in pixels. |
Returns
this
-this builder, for chaining.
setXAxisTextStyle()
setXAxisTextStyle(textStyle): this
Sets the text style for the chart x-axis.
Parameters
Parameter | Type | Description |
---|---|---|
textStyle | IChartTextStyle | The text style for the chart x-axis. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
.setXAxisTextStyle({ content: 'xAxis Title text', fontSize: 12, fontColor: '#ff0000' })
.build();
fSheet.insertChart(chartInfo);
setXAxisTitle()
setXAxisTitle(title): this
Sets the title of the chart x-axis.
Parameters
Parameter | Type | Description |
---|---|---|
title | string | The title of the chart x-axis. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Column)
.setPosition(1, 1, 0, 0)
.setXAxisTitle('xAxis Title text')
.build();
fSheet.insertChart(chartInfo);
setYAxisTextStyle()
setYAxisTextStyle(textStyle): this
Sets the text style for the chart y-axis.
Parameters
Parameter | Type | Description |
---|---|---|
textStyle | IChartTextStyle | The text style for the chart y-axis. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setYAxisTextStyle({ content: 'yAxis Title text', fontSize: 12, fontColor: '#ff0000' })
.build();
fSheet.insertChart(chartInfo);
setYAxisTitle()
setYAxisTitle(title): this
Sets the title of the chart y-axis.
Parameters
Parameter | Type | Description |
---|---|---|
title | string | The title of the chart y-axis. |
Returns
this
-this builder, for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fSheet = fWorkbook.getActiveSheet();
const chartBuilder = fSheet.newChart();
const chartInfo = chartBuilder.addRange('A1:D6')
.setChartType(univerAPI.Enum.ChartType.Line)
.setPosition(1, 1, 0, 0)
.setYAxisTitle('yAxis Title text')
.build();
fSheet.insertChart(chartInfo);