FPieChartBuilder

Fluent, type-specific Builder for Pie and Donut Charts.

For a conventional category/value source, select the slice-label field with setCategoryField() and select its numeric value field with setValueFields([index]). Field indexes are zero-based in the normalized data source. A value field is required; without an explicit category field, slices fall back to generated ordinal labels. Explicit mapping is recommended for ambiguous sources, especially Sheet ranges containing only numeric values, because automatic inference cannot determine the intended label column.

A regular Pie uses the first selected value series. This example intentionally selects one value field so each source row becomes one labeled slice. Negative values render by absolute magnitude and retain a negative label and tooltip.

Inheritance

Extends FChartBuilderBase. Its inherited members are available on this object.

Example

Sheet

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')const chartInfo = fWorksheet  .newChart(univerAPI.Enum.ChartTypeString.Donut)  .setSource('A1:B8')  .setCategoryField(0)  .setValueFields([1])  .setDoughnutHole(0.4)  .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })  .setExplosion(0.01)  .setSliceBorderColor('#ffffff')  .setPaddingAngleEnabled(true)  .setLabelLineVisible(true)  .setValueScale(1)  .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })  .build()await fWorksheet.insertChart(chartInfo)

Doc

const fDocument = univerAPI.getActiveDocument()const chartInfo = fDocument  .newChart(univerAPI.Enum.ChartTypeString.Donut)  .setSource([    ['Channel', 'Sales'],    ['Online', 180],    ['Retail', 120],  ])  .setCategoryField(0)  .setValueFields([1])  .setDoughnutHole(0.4)  .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })  .setExplosion(0.01)  .setSliceBorderColor('#ffffff')  .setPaddingAngleEnabled(true)  .setLabelLineVisible(true)  .setValueScale(1)  .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })  .build()await fDocument.insertChart(chartInfo)

Slide

const fPresentation = univerAPI.getActivePresentation()const fSlide = fPresentation.getSlideByIndex(0)const chartInfo = fSlide  .newChart(univerAPI.Enum.ChartTypeString.Donut)  .setSource([    ['Channel', 'Sales'],    ['Online', 180],    ['Retail', 120],  ])  .setCategoryField(0)  .setValueFields([1])  .setDoughnutHole(0.4)  .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })  .setExplosion(0.01)  .setSliceBorderColor('#ffffff')  .setPaddingAngleEnabled(true)  .setLabelLineVisible(true)  .setValueScale(1)  .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })  .build()await fSlide.insertChart(chartInfo)

Board

const fBoard = univerAPI.getActiveBoard()const chartInfo = fBoard  .newChart(univerAPI.Enum.ChartTypeString.Donut)  .setSource([    ['Channel', 'Sales'],    ['Online', 180],    ['Retail', 120],  ])  .setCategoryField(0)  .setValueFields([1])  .setDoughnutHole(0.4)  .setSliceStyle(0, { color: '#2563eb', fillOpacity: 0.8 })  .setExplosion(0.01)  .setSliceBorderColor('#ffffff')  .setPaddingAngleEnabled(true)  .setLabelLineVisible(true)  .setValueScale(1)  .setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })  .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

FPieChartBuilder.clearDoughnutHole

Clears the doughnut hole override. Doughnut charts fall back to a 50% inner radius; pie charts remain solid.

This method executes synchronously.

clearDoughnutHole(): this

Returns

This builder for chaining.

Examples

builder.clearDoughnutHole()

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

FPieChartBuilder.clearPieComposite

Clears composite Pie layout options.

clearPieComposite(): this

Returns

This Builder for chaining.

Examples

builder.clearPieComposite()

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

FPieChartBuilder.clearPieLabel

Clears the pie label override. Labels fall back to visible outside labels containing category, value, and percentage with the active chart font and theme colors.

This method executes synchronously.

clearPieLabel(): this

Returns

This builder for chaining.

Examples

builder.clearPieLabel()

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

FPieChartBuilder.clearSliceBorderColor

Clears the slice border override so the renderer uses its theme-aware white base color.

This method executes synchronously.

clearSliceBorderColor(): this

Returns

This builder for chaining.

Examples

builder.clearSliceBorderColor()

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

FPieChartBuilder.clearSliceStyle

Clears the authored style for the materialized slice at index.

This method executes synchronously.

clearSliceStyle(index: number): this

Parameters

• index — Required. The zero-based slice index.

Returns

This builder for chaining.

Examples

builder.clearSliceStyle(0)

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

FPieChartBuilder.resetExplosion

Restores the default of no slice explosion and returns this builder for chaining.

This method executes synchronously.

resetExplosion(): this

Returns

This builder for chaining.

Examples

builder.resetExplosion()

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

FPieChartBuilder.resetHalfPie

Restores the default full-circle pie layout.

This method executes synchronously.

resetHalfPie(): this

Returns

This builder for chaining.

Examples

builder.resetHalfPie()

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

FPieChartBuilder.resetLabelLineVisible

Removes the label-line visibility override so the renderer determines visibility from the label layout.

This method executes synchronously.

resetLabelLineVisible(): this

Returns

This builder for chaining.

Examples

builder.resetLabelLineVisible()

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

FPieChartBuilder.resetPaddingAngleEnabled

Restores the default of rendering slices without padding angles.

This method executes synchronously.

resetPaddingAngleEnabled(): this

Returns

This builder for chaining.

Examples

builder.resetPaddingAngleEnabled()

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

FPieChartBuilder.resetRosePie

Restores the default non-rose pie layout.

This method executes synchronously.

resetRosePie(): this

Returns

This builder for chaining.

Examples

builder.resetRosePie()

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

FPieChartBuilder.resetValueScale

Restores the value scale to 1 and returns this builder for chaining.

This method executes synchronously.

resetValueScale(): this

Returns

This builder for chaining.

Examples

builder.resetValueScale()

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

FPieChartBuilder.setDoughnutHole

Sets the doughnut hole configuration and returns this builder for chaining.

This method executes synchronously.

setDoughnutHole(value: number): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setDoughnutHole(0.6)

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

FPieChartBuilder.setExplosion

Sets the distance that every slice is offset from the Pie center.

The value is a ratio of the Chart's shorter side, not a pixel distance. For example, 0.01 produces an offset of about 2.2 px in a 480 px square Chart. Large values can move every slice outside the visible plot area.

setExplosion(value: number): this

Parameters

• value — Required. Non-negative explosion ratio.

Returns

This builder for chaining.

Examples

builder.setExplosion(0.01)

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

FPieChartBuilder.setHalfPie

Sets the half pie configuration and returns this builder for chaining.

This method executes synchronously.

setHalfPie(value: boolean): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setHalfPie(true)

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

FPieChartBuilder.setLabelLineVisible

Sets the label line visible configuration and returns this builder for chaining.

This method executes synchronously.

setLabelLineVisible(value: boolean): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setLabelLineVisible(true)

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

FPieChartBuilder.setPaddingAngleEnabled

Sets the padding angle enabled configuration and returns this builder for chaining.

This method executes synchronously.

setPaddingAngleEnabled(value: boolean): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setPaddingAngleEnabled(true)

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

FPieChartBuilder.setPieComposite

Sets secondary-plot and composite layout options for a Pie Chart.

setPieComposite(value: DeepNullish<IChartPieCompositeSpec>): this

Parameters

• value — Required. The composite Pie specification.

Returns

This Builder for chaining.

Examples

builder.setPieComposite({  enabled: true,  secondaryPlot: { type: univerAPI.Enum.ChartPieSecondaryPlotType.Pie },})

Types: DeepNullish · IChartPieCompositeSpec

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

FPieChartBuilder.setPieLabel

Sets the pie label configuration and returns this builder for chaining.

Omitted fields keep their current values. With no explicit label overrides, labels are visible outside the pie and contain category, value, and percentage using 12 px active-theme text.

This method executes synchronously.

setPieLabel(value: DeepNullish<IChartPieLabelSpec>): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setPieLabel({ visible: true, position: univerAPI.Enum.ChartPieLabelPosition.Outside })

Types: DeepNullish · IChartPieLabelSpec

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

FPieChartBuilder.setRosePie

Sets the rose pie configuration and returns this builder for chaining.

This method executes synchronously.

setRosePie(value: boolean): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setRosePie(true)

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

FPieChartBuilder.setSliceBorderColor

Sets the slice border color configuration and returns this builder for chaining.

This method executes synchronously.

setSliceBorderColor(value: string): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setSliceBorderColor('#ffffff')

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

FPieChartBuilder.setSliceStyle

Sets the style for the materialized slice at index.

This method executes synchronously.

setSliceStyle(index: number, value: IChartSliceStyleSpec): this

Parameters

• index — Required. The zero-based slice index.
• value — Required. The slice style patch.

Returns

This builder for chaining.

Examples

import { chartLinearGradient } from '@univerjs-pro/engine-chart'const color = chartLinearGradient({  start: { x: 0, y: 0 },  end: { x: 1, y: 1 },  stops: [    { offset: 0, color: '#fff1b8' },    { offset: 1, color: '#faad14' },  ],})builder.setSliceStyle(0, { color })

Types: IChartSliceStyleSpec

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

FPieChartBuilder.setValueScale

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

This method executes synchronously.

setValueScale(value: number): this

Parameters

• value — Required. The semantic value to record.

Returns

This builder for chaining.

Examples

builder.setValueScale(1)

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