# FParetoChartBuilder

> Language fallback: requested `zh-CN`; content is `en-US`.

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Fluent, type-specific Builder for Pareto Charts.

Select one category field with `setCategoryField()` and one numeric value field with
`setValueFields([index])`. Field indexes are zero-based in the normalized data source.
Explicit mapping is necessary when the source shape is ambiguous, such as a Sheet range
containing only numeric values; without both roles, the Chart has no renderable series.

Rows with the same category are aggregated. By default, zero and negative totals are
excluded, the remaining categories are sorted from largest to smallest, and the renderer
derives the cumulative-percentage line from the selected value field. Use
`setIncludeZeroValues(true)` to retain zero totals; negative totals remain excluded.

## Inheritance

Extends [`FCartesianChartBuilder`](https://docs.univer.ai/zh-CN/reference/facade/cartesian-chart-builder.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.Pareto)
  .setSource('A1:B8')
  .setCategoryField(0)
  .setValueFields([1])
  .setBarStyle({ color: '#2563eb', opacity: 0.8 })
  .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
  .setIncludeZeroValues(false)
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Pareto)
  .setSource([
    ['Cause', 'Count'],
    ['A', 42],
    ['B', 28],
    ['C', 15],
  ])
  .setCategoryField(0)
  .setValueFields([1])
  .setBarStyle({ color: '#2563eb', opacity: 0.8 })
  .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
  .setIncludeZeroValues(false)
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Pareto)
  .setSource([
    ['Cause', 'Count'],
    ['A', 42],
    ['B', 28],
    ['C', 15],
  ])
  .setCategoryField(0)
  .setValueFields([1])
  .setBarStyle({ color: '#2563eb', opacity: 0.8 })
  .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
  .setIncludeZeroValues(false)
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Pareto)
  .setSource([
    ['Cause', 'Count'],
    ['A', 42],
    ['B', 28],
    ['C', 15],
  ])
  .setCategoryField(0)
  .setValueFields([1])
  .setBarStyle({ color: '#2563eb', opacity: 0.8 })
  .setCumulativeLineStyle({ color: '#dc2626', width: 2 })
  .setIncludeZeroValues(false)
  .build()
await fBoard.insertChart(chartInfo)
```

## Setup

Register [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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/zh-CN/guides/sheets/getting-started/facade.md).

## `@univerjs-pro/engine-chart`

### `FParetoChartBuilder.clearBarStyle`

Clears the complete Pareto bar style.

After clearing, bars again use the active chart theme palette, full opacity, and
renderer-default borders and labels.

This method executes synchronously.

```typescript
clearBarStyle(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearBarStyle()
const barStyle = builder.build().config.pareto?.barStyle
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-pareto-chart-builder.d.ts)

### `FParetoChartBuilder.clearCumulativeLineStyle`

Clears the complete Pareto cumulative-line style.

The cumulative line remains visible and falls back to the fourth active theme color,
a 2 px solid stroke, full opacity, and 7 px points.

This method executes synchronously.

```typescript
clearCumulativeLineStyle(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearCumulativeLineStyle()
const lineStyle = builder.build().config.pareto?.cumulativeLineStyle
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-pareto-chart-builder.d.ts)

### `FParetoChartBuilder.resetIncludeZeroValues`

Restores the default of excluding zero-valued categories and returns this builder for chaining.

This method executes synchronously.

```typescript
resetIncludeZeroValues(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetIncludeZeroValues()
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-pareto-chart-builder.d.ts)

### `FParetoChartBuilder.setBarStyle`

Deep-merges supported Pareto bar appearance.

Omitted fields keep their current values. Without explicit overrides, bars use the active
chart theme palette, full opacity, and renderer-default borders and labels.

This method executes synchronously.

Read the current value from `builder.build().config.pareto?.barStyle`.

```typescript
setBarStyle(value: IChartParetoBarStyleSpec): this
```

**Parameters**

* `value` — Required. Supported bar appearance fields.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setBarStyle({ color: '#1677ff', opacity: 0.8 })
const barStyle = builder.build().config.pareto?.barStyle
```

**Types:** [`IChartParetoBarStyleSpec`](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/zh-CN/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-pareto-chart-builder.d.ts)

### `FParetoChartBuilder.setCumulativeLineStyle`

Deep-merges supported Pareto cumulative-line appearance.

Omitted fields keep their current values. Without explicit overrides, the line uses the
fourth active theme color, a 2 px solid stroke, full opacity, and 7 px points.

This method executes synchronously.

Non-positive widths are ignored because the cumulative line remains part of Pareto.
Read the current value from `builder.build().config.pareto?.cumulativeLineStyle`.

```typescript
setCumulativeLineStyle(value: IChartParetoLineStyleSpec): this
```

**Parameters**

* `value` — Required. Supported cumulative-line appearance fields.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setCumulativeLineStyle({ color: '#f5222d', width: 2 })
const lineStyle = builder.build().config.pareto?.cumulativeLineStyle
```

**Types:** [`IChartParetoLineStyleSpec`](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/zh-CN/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-pareto-chart-builder.d.ts)

### `FParetoChartBuilder.setIncludeZeroValues`

Sets the include zero values configuration and returns this builder for chaining.

This method executes synchronously.

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

**Parameters**

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

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setIncludeZeroValues(true)
```

**Package:** [`@univerjs-pro/engine-chart`](https://docs.univer.ai/zh-CN/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-pareto-chart-builder.d.ts)