# FPieChartBuilder

- Human documentation: [https://docs.univer.ai/reference/facade/pie-chart-builder](https://docs.univer.ai/reference/facade/pie-chart-builder)

- Agent Markdown: [https://docs.univer.ai/reference/facade/pie-chart-builder.md](https://docs.univer.ai/reference/facade/pie-chart-builder.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/pie-chart-builder.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/pie-chart-builder.mdx)

---

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`](https://docs.univer.ai/reference/facade/chart-builder-base.md). Its inherited members are available on this object.

## Example

Sheet

```ts
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

```ts
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

```ts
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

```ts
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`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) 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](https://docs.univer.ai/guides/sheets/getting-started/facade.md).

## `@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.

```typescript
clearDoughnutHole(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearDoughnutHole()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.clearPieComposite`

Clears composite Pie layout options.

```typescript
clearPieComposite(): this
```

**Returns**

This Builder for chaining.

**Examples**

```ts
builder.clearPieComposite()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `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.

```typescript
clearPieLabel(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearPieLabel()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.clearSliceBorderColor`

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

This method executes synchronously.

```typescript
clearSliceBorderColor(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearSliceBorderColor()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.clearSliceStyle`

Clears the authored style for the materialized slice at `index`.

This method executes synchronously.

```typescript
clearSliceStyle(index: number): this
```

**Parameters**

* `index` — Required. The zero-based slice index.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearSliceStyle(0)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.resetExplosion`

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

This method executes synchronously.

```typescript
resetExplosion(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetExplosion()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.resetHalfPie`

Restores the default full-circle pie layout.

This method executes synchronously.

```typescript
resetHalfPie(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetHalfPie()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.resetLabelLineVisible`

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

This method executes synchronously.

```typescript
resetLabelLineVisible(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetLabelLineVisible()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.resetPaddingAngleEnabled`

Restores the default of rendering slices without padding angles.

This method executes synchronously.

```typescript
resetPaddingAngleEnabled(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetPaddingAngleEnabled()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.resetRosePie`

Restores the default non-rose pie layout.

This method executes synchronously.

```typescript
resetRosePie(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetRosePie()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.resetValueScale`

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

This method executes synchronously.

```typescript
resetValueScale(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetValueScale()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setDoughnutHole`

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

This method executes synchronously.

```typescript
setDoughnutHole(value: number): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setDoughnutHole(0.6)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `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.

```typescript
setExplosion(value: number): this
```

**Parameters**

* `value` — Required. Non-negative explosion ratio.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setExplosion(0.01)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setHalfPie`

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

This method executes synchronously.

```typescript
setHalfPie(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setHalfPie(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setLabelLineVisible`

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

This method executes synchronously.

```typescript
setLabelLineVisible(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setLabelLineVisible(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setPaddingAngleEnabled`

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

This method executes synchronously.

```typescript
setPaddingAngleEnabled(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setPaddingAngleEnabled(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setPieComposite`

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

```typescript
setPieComposite(value: DeepNullish<IChartPieCompositeSpec>): this
```

**Parameters**

* `value` — Required. The composite Pie specification.

**Returns**

This Builder for chaining.

**Examples**

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

**Types:** [`DeepNullish`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts) · [`IChartPieCompositeSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/chart-types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `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.

```typescript
setPieLabel(value: DeepNullish<IChartPieLabelSpec>): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

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

**Types:** [`DeepNullish`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/types.d.ts) · [`IChartPieLabelSpec`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/chart-types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setRosePie`

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

This method executes synchronously.

```typescript
setRosePie(value: boolean): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setRosePie(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setSliceBorderColor`

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

This method executes synchronously.

```typescript
setSliceBorderColor(value: string): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setSliceBorderColor('#ffffff')
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setSliceStyle`

Sets the style for the materialized slice at `index`.

This method executes synchronously.

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/chart-types.d.ts)

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)

### `FPieChartBuilder.setValueScale`

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

This method executes synchronously.

```typescript
setValueScale(value: number): this
```

**Parameters**

* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setValueScale(1)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/engine-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/facade/builders/f-pie-chart-builder.d.ts)