FChartBuilderBase

Fluent base Builder for detached Chart information.

Builder methods only modify the detached draft. Call build to create an insertable IChartInfo; use a live FChart facade to update an inserted Chart.

Example

Sheet

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')fWorksheet.getRange('A1:C5').setValues([  ['Quarter', 'Revenue', 'Cost'],  ['Q1', 120, 80],  ['Q2', 180, 110],  ['Q3', 160, 100],  ['Q4', 220, 130],])const chartInfo = fWorksheet  .newChart(univerAPI.Enum.ChartTypeString.Column)  .setSource({    range: 'A1:C5',    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,  })  .setAbsolutePosition(120, 80)  .setSize(640, 360)  .setCategoryField(0)  .setValueFields([1, 2])  .setTitle('Quarterly performance')  .setSubtitle('FY 2026')  .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })  .setPalette(['#1677ff', '#52c41a'])  .setAppearance({    background: { color: 'transparent' },    border: { color: '#d9d9d9', width: 1 },  })  .setAutoGradientFill(true)  .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)  .setAggregation({ aggregate: true })  .build()await fWorksheet.insertChart(chartInfo)

Doc

const fDocument = univerAPI.getActiveDocument()const chartInfo = fDocument  .newChart(univerAPI.Enum.ChartTypeString.Column)  .setSource([    ['Quarter', 'Revenue', 'Cost'],    ['Q1', 120, 80],    ['Q2', 180, 110],    ['Q3', 160, 100],    ['Q4', 220, 130],  ])  .setFloating()  .setAbsolutePosition(120, 80)  .setSize(640, 360)  .setCategoryField(0)  .setValueFields([1, 2])  .setTitle('Quarterly performance')  .setSubtitle('FY 2026')  .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })  .setPalette(['#1677ff', '#52c41a'])  .setAppearance({    background: { color: 'transparent' },    border: { color: '#d9d9d9', width: 1 },  })  .setAutoGradientFill(true)  .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)  .setAggregation({ aggregate: true })  .build()await fDocument.insertChart(chartInfo)

Slide

const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const chartInfo = fSlide  .newChart(univerAPI.Enum.ChartTypeString.Column)  .setSource([    ['Quarter', 'Revenue', 'Cost'],    ['Q1', 120, 80],    ['Q2', 180, 110],    ['Q3', 160, 100],    ['Q4', 220, 130],  ])  .setAbsolutePosition(120, 80)  .setSize(640, 360)  .setCategoryField(0)  .setValueFields([1, 2])  .setTitle('Quarterly performance')  .setSubtitle('FY 2026')  .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })  .setPalette(['#1677ff', '#52c41a'])  .setAppearance({    background: { color: 'transparent' },    border: { color: '#d9d9d9', width: 1 },  })  .setAutoGradientFill(true)  .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)  .setAggregation({ aggregate: true })  .build()await fSlide.insertChart(chartInfo)

Board

const fBoard = univerAPI.getActiveBoard()const chartInfo = fBoard  .newChart(univerAPI.Enum.ChartTypeString.Column)  .setSource([    ['Quarter', 'Revenue', 'Cost'],    ['Q1', 120, 80],    ['Q2', 180, 110],    ['Q3', 160, 100],    ['Q4', 220, 130],  ])  .setAbsolutePosition(120, 80)  .setSize(640, 360)  .setCategoryField(0)  .setValueFields([1, 2])  .setTitle('Quarterly performance')  .setSubtitle('FY 2026')  .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })  .setPalette(['#1677ff', '#52c41a'])  .setAppearance({    background: { color: 'transparent' },    border: { color: '#d9d9d9', width: 1 },  })  .setAutoGradientFill(true)  .setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)  .setAggregation({ aggregate: true })  .build()await fBoard.insertChart(chartInfo)

Setup

Register @univerjs-pro/engine-chart or a preset that includes it. In plugin mode, import @univerjs-pro/engine-chart/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs-pro/engine-chart

FChartBuilderBase.build

Builds a detached Chart information snapshot without mutating a host.

build(): TInfo

Returns

A deep-cloned, insertable Chart information object.

Throws

If a new Chart Builder has no data source.

Examples

const chartInfo = builder.build()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearAggregation

Clears the aggregation configuration and returns this builder for chaining.

This method executes synchronously.

clearAggregation(target?: ChartAggregationTarget): this

Parameters

• target — Optional. The configuration field to clear or reset.

Returns

This builder for chaining.

Examples

builder.clearAggregation(univerAPI.Enum.ChartAggregationTarget.TopN)

Types: ChartAggregationTarget

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearAppearance

Clears the appearance configuration and returns this builder for chaining.

This method executes synchronously.

clearAppearance(target?: ChartAppearanceTarget): this

Parameters

• target — Optional. The configuration field to clear or reset.

Returns

This builder for chaining.

Examples

builder.clearAppearance(univerAPI.Enum.ChartAppearanceTarget.Background)

Types: ChartAppearanceTarget

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearCategoryField

Clears the category field configuration and returns this builder for chaining.

This method executes synchronously.

clearCategoryField(): this

Returns

This builder for chaining.

Examples

builder.clearCategoryField()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearCategoryFields

Clears the ordered category field configuration.

This method executes synchronously.

clearCategoryFields(): this

Returns

This builder for chaining.

Examples

builder.clearCategoryFields()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearLegend

Clears the legend configuration and returns this builder for chaining.

This method executes synchronously.

clearLegend(): this

Returns

This builder for chaining.

Examples

builder.clearLegend()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearPalette

Clears the chart-owned palette and returns to the selected theme colors.

clearPalette(): this

Returns

This builder for chaining.

Examples

const chart = fWorksheet.getCharts()[0]const info = chart.toBuilder().clearPalette().build()await chart.update(info)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearSubtitle

Clears the subtitle configuration and returns this builder for chaining.

This method executes synchronously.

clearSubtitle(): this

Returns

This builder for chaining.

Examples

builder.clearSubtitle()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearTheme

Clears the theme configuration and returns this builder for chaining.

This method executes synchronously.

clearTheme(): this

Returns

This builder for chaining.

Examples

builder.clearTheme()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearTitle

Clears the title configuration and returns this builder for chaining.

This method executes synchronously.

clearTitle(): this

Returns

This builder for chaining.

Examples

builder.clearTitle()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.clearValueFields

Clears the value fields configuration and returns this builder for chaining.

This method executes synchronously.

clearValueFields(): this

Returns

This builder for chaining.

Examples

builder.clearValueFields()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.resetAutoGradientFill

Clears the automatic-gradient override and restores the chart type's default behavior.

This method executes synchronously.

resetAutoGradientFill(): this

Returns

This builder for chaining.

Examples

builder.setAutoGradientFill(true)builder.resetAutoGradientFill()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.resetInvalidValueStrategy

Restores the invalid value strategy to Break and returns this builder for chaining.

This method executes synchronously.

resetInvalidValueStrategy(): this

Returns

This builder for chaining.

Examples

builder.resetInvalidValueStrategy()

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setAbsolutePosition

Sets an absolute position in the target host.

setAbsolutePosition(x: number, y: number): this

Parameters

• x — Required. The horizontal host coordinate.
• y — Required. The vertical host coordinate.

Returns

This Builder for chaining.

Examples

builder.setAbsolutePosition(120, 80)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setAggregation

Sets the aggregation configuration and returns this builder for chaining.

This method executes synchronously.

setAggregation(value: IChartAggregationSpec): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setAggregation({  aggregate: true,  topN: { count: 10, sourceIndex: 2 },})

Types: IChartAggregationSpec

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setAppearance

Sets the appearance configuration and returns this builder for chaining.

Supported by Sheet, Document, Slide, and Board chart builders. An explicit 'transparent' background remains transparent, and border width 0 hides the persisted host border without removing selection or transformer chrome.

This method executes synchronously.

setAppearance(value: IChartAppearanceSpec): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setAppearance({  background: { color: 'transparent' },  border: { width: 0 },})

Types: IChartAppearanceSpec

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setAutoGradientFill

Enables or disables the automatic gradient preset for supported chart marks.

Explicit gradient colors configured on a series or slice take precedence over this preset. This method executes synchronously.

setAutoGradientFill(value: boolean): this

Parameters

• value — Required. Whether to apply the chart type's automatic gradient preset.

Returns

This builder for chaining.

Examples

builder.setAutoGradientFill(true)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setCategoryField

Sets the category field configuration and returns this builder for chaining.

This method executes synchronously.

setCategoryField(index: number): this

Parameters

• index — Required. The zero-based field or series index.

Returns

This builder for chaining.

Examples

builder.setCategoryField(0)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setCategoryFields

Sets the ordered category fields used by a multi-level category axis.

This method executes synchronously.

setCategoryFields(indexes: readonly number[]): this

Parameters

• indexes — Required. The zero-based field indexes in root-to-leaf order.

Returns

This builder for chaining.

Examples

builder.setCategoryFields([0, 1, 2])

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setInvalidValueStrategy

Sets the invalid value strategy configuration and returns this builder for chaining.

This method executes synchronously.

setInvalidValueStrategy(value: InvalidValueType): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Break)

Types: InvalidValueType

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setLegend

Sets the legend configuration and returns this builder for chaining.

This method executes synchronously.

setLegend(value: ChartLegendSpec): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setLegend(true)

Types: ChartLegendSpec

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setMultiLevelCategoryAxis

Enables or disables the multi-level category axis for the selected category fields.

This method executes synchronously and does not replace the selected category fields.

setMultiLevelCategoryAxis(enabled: boolean): this

Parameters

• enabled — Required. Whether to render the selected category fields as one multi-level axis.

Returns

This builder for chaining.

Examples

builder.setMultiLevelCategoryAxis(true)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setPalette

Sets absolute series palette colors and returns this builder for chaining.

The values are copied, persisted with the chart, and used unchanged in light and dark mode. A non-empty palette takes precedence over the selected theme's series colors without clearing the selected theme. Call clearPalette() to return series-color control to the theme. An empty array has the same effect as clearPalette().

setPalette(colors: readonly string[]): this

Parameters

• colors — Required. Ordered CSS colors that override the selected theme's series colors.

Returns

This builder for chaining.

Examples

builder.setPalette(['#1677ff', '#52c41a'])

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setSize

Sets the Chart size in the target host.

setSize(width: number, height: number): this

Parameters

• width — Required. The width in host coordinates.
• height — Required. The height in host coordinates.

Returns

This Builder for chaining.

Examples

builder.setSize(640, 360)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setSource

Sets the host-specific descriptor stored in the detached Chart information. The Builder deep-clones this value; it does not retain or create a runtime DataSource.

setSource(source: TSource): this

Parameters

• source — Required. The host descriptor, such as a Sheet range or a two-dimensional value array.

Returns

This Builder for chaining.

Examples

builder.setSource('A1:D8')

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setSubtitle

Sets the subtitle configuration and returns this builder for chaining.

This method executes synchronously.

setSubtitle(value: ChartSubtitleSpec): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setSubtitle({ text: 'FY 2026' })

Types: ChartSubtitleSpec

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setTheme

Sets a built-in or custom registered theme and returns this builder for chaining.

A non-empty chart palette takes precedence over the theme's series colors. This method does not clear that palette; call clearPalette() explicitly to use the selected theme colors. Use univerAPI.Enum.ChartThemeName for built-in themes. Custom names must first be registered through univerAPI.registerTheme().

This method executes synchronously.

setTheme(name: string): this

Parameters

• name — Required. A built-in Chart theme name or the stable name of a custom registered theme.

Returns

This builder for chaining.

Examples

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')const chartInfo = fWorksheet  .newChart(univerAPI.Enum.ChartTypeString.Column)  .setSource('A1:B8')  .setTheme(univerAPI.Enum.ChartThemeName.UniverGradient1)  .build()await fWorksheet.insertChart(chartInfo)

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setTitle

Sets the title configuration and returns this builder for chaining.

This method executes synchronously.

setTitle(value: ChartTitleSpec): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setTitle({ text: 'Quarterly sales' })

Types: ChartTitleSpec

Package: @univerjs-pro/engine-chart · Type definitions

FChartBuilderBase.setValueFields

Sets the value fields configuration and returns this builder for chaining.

This method executes synchronously.

setValueFields(indexes: readonly number[]): this

Parameters

• indexes — Required. The zero-based field indexes.

Returns

This builder for chaining.

Examples

builder.setValueFields([1, 2])

Package: @univerjs-pro/engine-chart · Type definitions