# FWaterfallChartBuilder

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

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Fluent, type-specific Builder for Waterfall Charts.

## 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.Waterfall)
  .setSource('A1:B8')
  .setPointRoles([
    { series: 0, dataPointIndex: 3, role: univerAPI.Enum.ChartWaterfallPointRole.Total },
  ])
  .setConnector(true)
  .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
  .setUseSubtotal(true)
  .setPositiveStyle(0, { color: '#16a34a' })
  .setNegativeStyle(0, { color: '#dc2626' })
  .setSubtotalStyle(0, { color: '#2563eb' })
  .build()
await fWorksheet.insertChart(chartInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
  .setSource([
    ['Stage', 'Change'],
    ['Revenue', 300],
    ['Costs', -180],
    ['Profit', 120],
  ])
  .setPointRoles([
    { series: 0, dataPointIndex: 2, role: univerAPI.Enum.ChartWaterfallPointRole.Total },
  ])
  .setConnector(true)
  .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
  .setUseSubtotal(true)
  .setPositiveStyle(0, { color: '#16a34a' })
  .setNegativeStyle(0, { color: '#dc2626' })
  .setSubtotalStyle(0, { color: '#2563eb' })
  .build()
await fDocument.insertChart(chartInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
  .setSource([
    ['Stage', 'Change'],
    ['Revenue', 300],
    ['Costs', -180],
    ['Profit', 120],
  ])
  .setPointRoles([
    { series: 0, dataPointIndex: 2, role: univerAPI.Enum.ChartWaterfallPointRole.Total },
  ])
  .setConnector(true)
  .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
  .setUseSubtotal(true)
  .setPositiveStyle(0, { color: '#16a34a' })
  .setNegativeStyle(0, { color: '#dc2626' })
  .setSubtotalStyle(0, { color: '#2563eb' })
  .build()
await fSlide.insertChart(chartInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Waterfall)
  .setSource([
    ['Stage', 'Change'],
    ['Revenue', 300],
    ['Costs', -180],
    ['Profit', 120],
  ])
  .setPointRoles([
    { series: 0, dataPointIndex: 2, role: univerAPI.Enum.ChartWaterfallPointRole.Total },
  ])
  .setConnector(true)
  .setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
  .setUseSubtotal(true)
  .setPositiveStyle(0, { color: '#16a34a' })
  .setNegativeStyle(0, { color: '#dc2626' })
  .setSubtotalStyle(0, { color: '#2563eb' })
  .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`

### `FWaterfallChartBuilder.clearConnector`

Clears connector configuration. With no persisted connector setting, the renderer does not
draw connectors; call `setConnector(true)` to restore the default dashed connector.

Read the cleared value from `builder.build().config.waterfall?.connector`.

```typescript
clearConnector(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearConnector()
const connector = builder.build().config.waterfall?.connector
```

**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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.clearNegativeStyle`

Clears the negative style configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearNegativeStyle(selector: ChartPublicSeriesSelector): this
```

**Parameters**

* `selector` — Required. The target series selector.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearNegativeStyle(0)
const negative = builder.build().config.series[0]?.waterfallStyles?.negative
```

**Types:** [`ChartPublicSeriesSelector`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/configuration/cartesian-series.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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.clearPositiveStyle`

Clears the positive style configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearPositiveStyle(selector: ChartPublicSeriesSelector): this
```

**Parameters**

* `selector` — Required. The target series selector.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearPositiveStyle(0)
const positive = builder.build().config.series[0]?.waterfallStyles?.positive
```

**Types:** [`ChartPublicSeriesSelector`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/configuration/cartesian-series.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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.clearSubtotalStyle`

Clears the subtotal style configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearSubtotalStyle(selector: ChartPublicSeriesSelector): this
```

**Parameters**

* `selector` — Required. The target series selector.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearSubtotalStyle(0)
const subtotal = builder.build().config.series[0]?.waterfallStyles?.subtotal
```

**Types:** [`ChartPublicSeriesSelector`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/configuration/cartesian-series.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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.resetStackType`

Restores the stack type to `Arrangement` and returns this builder for chaining.

This method executes synchronously.

```typescript
resetStackType(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetStackType()
```

**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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.resetUseSubtotal`

Restores automatic subtotal generation to its default of `true` and returns this builder for chaining.

This method executes synchronously.

```typescript
resetUseSubtotal(): this
```

**Returns**

This builder for chaining.

**Examples**

```ts
builder.resetUseSubtotal()
```

**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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.setConnector`

Enables, disables, or styles derived Waterfall connectors.

Passing `true` renders a 1 px dashed connector with full opacity, no endpoint symbols,
and a neutral `#8C8C8C` base color that is adapted by the active light or dark theme. An object
starts from those defaults and overrides only the supplied fields. Pass `false` to hide it.

Read the current value from `builder.build().config.waterfall?.connector`.

```typescript
setConnector(value: boolean | IChartWaterfallConnectorStyleSpec): this
```

**Parameters**

* `value` — Required. `false` disables, `true` enables the default dashed style, and an object enables style overrides.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setConnector(true)
const connector = builder.build().config.waterfall?.connector
```

**Types:** [`IChartWaterfallConnectorStyleSpec`](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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.setNegativeStyle`

Sets the negative style configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setNegativeStyle(selector: ChartPublicSeriesSelector, value: Omit<IChartSeriesPatch, 'selector'>): this
```

**Parameters**

* `selector` — Required. The target series selector.
* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setNegativeStyle(0, { color: '#f5222d' })
const negative = builder.build().config.series[0]?.waterfallStyles?.negative
```

**Types:** [`ChartPublicSeriesSelector`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/configuration/cartesian-series.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IChartSeriesPatch`](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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.setPointRoles`

Replaces all Waterfall point roles.

Duplicate series/point identities use the last input and read back in canonical order.

```typescript
setPointRoles(roles: readonly IChartWaterfallPointRoleSpec[]): this
```

**Parameters**

* `roles` — Required. The complete point-role collection.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setPointRoles([
  { series: 0, dataPointIndex: 0, role: univerAPI.Enum.ChartWaterfallPointRole.Total },
])
const roles = builder.build().config.waterfall?.pointRoles
```

**Types:** [`IChartWaterfallPointRoleSpec`](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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.setPositiveStyle`

Sets the positive style configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setPositiveStyle(selector: ChartPublicSeriesSelector, value: Omit<IChartSeriesPatch, 'selector'>): this
```

**Parameters**

* `selector` — Required. The target series selector.
* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setPositiveStyle(0, { color: '#52c41a' })
const positive = builder.build().config.series[0]?.waterfallStyles?.positive
```

**Types:** [`ChartPublicSeriesSelector`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/configuration/cartesian-series.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IChartSeriesPatch`](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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.setStackType`

Sets the stack type configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setStackType(value: WaterfallStackTypeEnum): this
```

**Parameters**

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

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setStackType(univerAPI.Enum.ChartWaterfallStackTypeEnum.Arrangement)
```

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

### `FWaterfallChartBuilder.setSubtotalStyle`

Sets the subtotal style configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setSubtotalStyle(selector: ChartPublicSeriesSelector, value: Omit<IChartSeriesPatch, 'selector'>): this
```

**Parameters**

* `selector` — Required. The target series selector.
* `value` — Required. The semantic value to record.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setSubtotalStyle(0, { color: '#1677ff' })
const subtotal = builder.build().config.series[0]?.waterfallStyles?.subtotal
```

**Types:** [`ChartPublicSeriesSelector`](https://unpkg.com/@univerjs-pro/engine-chart@1.0.0-rc.0/lib/types/chart-builder/configuration/cartesian-series.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IChartSeriesPatch`](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-waterfall-chart-builder.d.ts)

### `FWaterfallChartBuilder.setUseSubtotal`

Sets the use subtotal configuration and returns this builder for chaining.

This method executes synchronously.

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

**Parameters**

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

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setUseSubtotal(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-waterfall-chart-builder.d.ts)