# FCartesianChartBuilder

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

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

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

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Fluent Builder for Cartesian Charts with per-series styling and trendlines.

## Inheritance

Extends [`FAxisChartBuilder`](https://docs.univer.ai/zh-CN/reference/facade/axis-chart-builder.md). Its inherited members are available on this object.

## Example

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource('A1:D8')
  .setBar({ gapWidth: 0.2 })
  .build()
await fWorksheet.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`

### `FCartesianChartBuilder.clearAllSeriesOverrides`

Clears every per-series override while preserving all-series defaults.
Use `setSeries()` to write one selector and `describe().series` to read the effective state.

```typescript
clearAllSeriesOverrides(): this
```

**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/f-cartesian-chart-builder.d.ts)

### `FCartesianChartBuilder.clearAllSeriesStyle`

Clears persistent defaults inherited by every series.

This method executes synchronously.

```typescript
clearAllSeriesStyle(target?: ChartAllSeriesStyleTarget): this
```

**Parameters**

* `target` — Optional. The global series style field to clear, or omit it to clear all defaults.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearAllSeriesStyle(univerAPI.Enum.ChartAllSeriesStyleTarget.Color)
```

**Types:** [`ChartAllSeriesStyleTarget`](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/f-cartesian-chart-builder.d.ts)

### `FCartesianChartBuilder.clearAxisPointer`

Clears the axis pointer configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearAxisPointer(target?: ChartAxisPointerTarget): this
```

**Parameters**

* `target` — Optional. The configuration field to clear or reset.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearAxisPointer(univerAPI.Enum.ChartAxisPointerTarget.IndicatorLineColor)
```

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

### `FCartesianChartBuilder.clearBar`

Clears Chart-wide Bar and Column layout overrides.

```typescript
clearBar(): this
```

**Returns**

This Builder for chaining.

**Examples**

`builder.clearBar()`

**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/f-cartesian-chart-builder.d.ts)

### `FCartesianChartBuilder.clearSeries`

Clears the series configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearSeries(selector: ChartPublicSeriesSelector, target?: ChartSeriesClearTarget): this
```

**Parameters**

* `selector` — Required. The target series selector.
* `target` — Optional. The configuration field to clear or reset.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearSeries(0)
```

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

### `FCartesianChartBuilder.clearTrendlines`

Clears the trendlines configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
clearTrendlines(selector?: ChartSeriesTrendlineSelector): this
```

**Parameters**

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

**Returns**

This builder for chaining.

**Examples**

```ts
builder.clearTrendlines(0)
```

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

### `FCartesianChartBuilder.removeTrendline`

Remove trendline.

This method executes synchronously.

```typescript
removeTrendline(selector: ChartSeriesTrendlineSelector, trendline: ChartTrendlineSelector): this
```

**Parameters**

* `selector` — Required. The target series selector.
* `trendline` — Required. The trendline configuration to append.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.removeTrendline(0, 0)
```

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

### `FCartesianChartBuilder.setAllSeriesStyle`

Sets persistent defaults inherited by every current and future series.

This method executes synchronously.

```typescript
setAllSeriesStyle(style: DeepNullish<TSeriesStyle>): this
```

**Parameters**

* `style` — Required. The global series style defaults.

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setAllSeriesStyle({ color: '#1677ff', fillOpacity: 0.8 })
```

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

### `FCartesianChartBuilder.setAxisPointer`

Sets the axis pointer configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setAxisPointer(value: IChartAxisPointerSpec): this
```

**Parameters**

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

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setAxisPointer({ indicatorLineColor: '#1677ff' })
```

**Types:** [`IChartAxisPointerSpec`](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/f-cartesian-chart-builder.d.ts)

### `FCartesianChartBuilder.setBar`

Sets Chart-wide Bar and Column spacing and width options.

```typescript
setBar(value: IChartBarSpec): this
```

**Parameters**

* `value` — Required. The Bar or Column layout specification.

**Returns**

This Builder for chaining.

**Types:** [`IChartBarSpec`](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/f-cartesian-chart-builder.d.ts)

### `FCartesianChartBuilder.setSeries`

Sets the series configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setSeries(selector: ChartPublicSeriesSelector, patch: DeepNullish<TSeriesPatch>): this
```

**Parameters**

* `selector` — Required. The target series selector.
* `patch` — Required. The semantic configuration patch owned by this method.

**Returns**

This builder for chaining.

**Examples**

```ts
import { chartLinearGradient } from '@univerjs-pro/engine-chart'

const color = chartLinearGradient({
  start: { x: 0, y: 1 },
  end: { x: 0, y: 0 },
  stops: [
    { offset: 0, color: 'rgba(22, 119, 255, 0)' },
    { offset: 1, color: '#1677ff' },
  ],
})
builder.setSeries(0, { color })
```

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

### `FCartesianChartBuilder.setTrendline`

Sets the trendline configuration and returns this builder for chaining.

This method executes synchronously.

```typescript
setTrendline(selector: ChartSeriesTrendlineSelector, value: ChartTrendlineValue): this
```

**Parameters**

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

**Returns**

This builder for chaining.

**Examples**

```ts
builder.setTrendline(0, { type: univerAPI.Enum.ChartTrendlineType.linear })
```

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