Skip to Content
ClassesFChartBuilderBase

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

PropertyType

chartId

string

chartType

ChartTypeBits

height

number

options

IChartBuildOptions

range

IRange

sourceSheetName

string

subUnitId

string

transposeRowsAndColumns

boolean

unitId

string

width

number

x

number

y

number

Methods

addRange()

addRange(range): this

Adds a range to the chart this builder modifies

Parameters

ParameterTypeDescription
rangestring | IRangeThe 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

LineChartBuilder


asPieChart()

asPieChart(): PieChartBuilder

Returns

PieChartBuilder


asRadarChart()

asRadarChart(): RadarChartBuilder

Returns

RadarChartBuilder


build()

build(): IChartBuilderInfo

Builds the chart to reflect all changes made to it.

Returns

IChartBuilderInfo

-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

ParameterTypeDescription
xnumberThe x-coordinate of the chart’s top left-hand corner.
ynumberThe 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

ParameterTypeDescription
allSeriesStyleIAllSeriesStyleThe 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

ParameterTypeDescription
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

ParameterTypeDescription
chartTypeChartTypeBitsThe 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

ParameterTypeDescription
heightnumberThe 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

ParameterTypeDescription
invalidValueTypeInvalidValueTypeThe 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

ParameterTypeDescription
optionPathstringThe path of the option to set. A ” path means the root of the options object.
optionValunknownThe 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

ParameterTypeDescription
anchorRowPosnumberThe chart’s top side is anchored in this row.
anchorColPosnumberThe chart’s left side is anchored in this column.
rowOffsetnumberThe chart’s top left-hand corner is offset by this many pixels.
columnOffsetnumberThe 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

ParameterTypeDescription
textStyleIChartTextStyleThe 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

ParameterTypeDescription
titlestringThe 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

ParameterTypeDescription
indexstring | numberThe index of the series to set the style for.
seriesStyleISeriesStyleThe 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

ParameterTypeDescription
themestringThe 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

ParameterTypeDescription
transposeRowsAndColumnsbooleanWhether 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

ParameterTypeDescription
widthnumberThe 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

ParameterTypeDescription
textStyleIChartTextStyleThe 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

ParameterTypeDescription
titlestringThe 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

ParameterTypeDescription
textStyleIChartTextStyleThe 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

ParameterTypeDescription
titlestringThe 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);