# FChart

> Language fallback: requested `ko-KR`; content is `en-US`.

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

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

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

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

---

Base facade for a live Chart that has already been inserted into a host.

Use host APIs such as `FWorksheet.newChart()` to build detached Chart information
and `insertChart()` to obtain a host-specific subclass of this facade.

For Docs, Slides, and Boards charts that use resource references, register [`UniverChartEmbedPlugin`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/chart-embed.md) before opening the host document and import `IResourceRefChartDataSourceInput` from `@univerjs-pro/chart-embed`. Inline values and native Sheets ranges do not require this plugin.

## Example

Sheet

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
fWorksheet.getRange('A1:B4').setValues([
  ['Month', 'Sales'],
  ['Jan', 120],
  ['Feb', 180],
  ['Mar', 160],
])
fWorksheet.getRange('D1:E4').setValues([
  ['Month', 'Sales'],
  ['Apr', 200],
  ['May', 240],
  ['Jun', 220],
])
const chartInfo = fWorksheet
  .newChart(univerAPI.Enum.ChartTypeString.Line)
  .setSource('A1:B4')
  .setPosition('G2')
  .setSize(640, 360)
  .setLineStyle({ width: 2 })
  .build()
const fChart = await fWorksheet.insertChart(chartInfo)

console.log(fChart.getId(), fChart.getInfo())
fChart
  .setTitle('Monthly sales')
  .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })
  .setPosition('H3')
  .setSize(720, 400)
await fChart.setDataSource('D1:E4')

const updatedInfo = fChart.toBuilder().setSubtitle('Second quarter').setPalette(['#1677ff']).build()
await fChart.update(updatedInfo)
```

Doc

```ts
const fDocument = univerAPI.getActiveDocument()
const chartInfo = fDocument
  .newChart(univerAPI.Enum.ChartTypeString.Line)
  .setSource([
    ['Month', 'Sales'],
    ['Jan', 120],
    ['Feb', 180],
    ['Mar', 160],
  ])
  .setFloating()
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .setLineStyle({ width: 2 })
  .build()
const fChart = await fDocument.insertChart(chartInfo)

console.log(fChart.getId(), fChart.getInfo())
fChart
  .setTitle('Monthly sales')
  .setAppearance({ background: { color: 'transparent' } })
  .setAbsolutePosition(160, 100)
  .setSize(720, 400)
await fChart.setDataSource([
  ['Month', 'Sales'],
  ['Apr', 200],
  ['May', 240],
  ['Jun', 220],
])

const updatedInfo = fChart.toBuilder().setSubtitle('Second quarter').setPalette(['#1677ff']).build()
await fChart.update(updatedInfo)
```

Slide

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const chartInfo = fSlide
  .newChart(univerAPI.Enum.ChartTypeString.Line)
  .setSource([
    ['Month', 'Sales'],
    ['Jan', 120],
    ['Feb', 180],
    ['Mar', 160],
  ])
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .setLineStyle({ width: 2 })
  .build()
const fChart = await fSlide.insertChart(chartInfo)

console.log(fChart.getId(), fChart.getInfo())
fChart
  .setTitle('Monthly sales')
  .setLegend({ position: univerAPI.Enum.ChartLegendPositionEnum.Bottom })
  .setAbsolutePosition(160, 100)
  .setSize(720, 400)
await fChart.setDataSource([
  ['Month', 'Sales'],
  ['Apr', 200],
  ['May', 240],
  ['Jun', 220],
])

const updatedInfo = fChart
  .toBuilder(univerAPI.Enum.ChartTypeString.Area)
  .setSubtitle('Second quarter')
  .setPalette(['#1677ff'])
  .build()
await fChart.update(updatedInfo)
```

Board

```ts
const fBoard = univerAPI.getActiveBoard()
const chartInfo = fBoard
  .newChart(univerAPI.Enum.ChartTypeString.Line)
  .setSource([
    ['Month', 'Sales'],
    ['Jan', 120],
    ['Feb', 180],
    ['Mar', 160],
  ])
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .setLineStyle({ width: 2 })
  .build()
const fChart = await fBoard.insertChart(chartInfo)

console.log(fChart.getId(), fChart.getInfo())
fChart
  .setTitle('Monthly sales')
  .setAutoGradientFill(true)
  .setAbsolutePosition(160, 100)
  .setSize(720, 400)
await fChart.setDataSource([
  ['Month', 'Sales'],
  ['Apr', 200],
  ['May', 240],
  ['Jun', 220],
])

const updatedInfo = fChart.toBuilder().setSubtitle('Second quarter').setPalette(['#1677ff']).build()
await fChart.update(updatedInfo)
```

## Setup

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

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

### `FChart.exportImage`

Exports this Chart through its host UI renderer.

```typescript
exportImage(options?: IChartImageExportOptions): Promise<string | undefined>
```

**Parameters**

* `options` — Optional.

**Returns**

The rendered image data URL, or `undefined` when the host has no exportable UI image.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const chart = fWorksheet.getCharts()[0]
const defaultPng = await chart?.exportImage()
const svg = await chart?.exportImage({ format: 'svg' })
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IChartImageExportOptions`](https://unpkg.com/@univerjs-pro/chart-ui/lib/types/services/chart-image-export.service.d.ts)

**Package:** [`@univerjs-pro/chart-ui`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/chart-ui.md) · [Type definitions](https://unpkg.com/@univerjs-pro/chart-ui/lib/types/facade/f-chart.d.ts)

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

### `FChart.bringForward`

Moves this live Chart forward by one level in its host's persisted drawing order.

```typescript
bringForward(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].bringForward()
```

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

### `FChart.bringToFront`

Moves this live Chart to the front of its host's persisted drawing order.

```typescript
bringToFront(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].bringToFront()
```

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

### `FChart.clearAggregation`

Clears all data aggregation or one selected aggregation property.

```typescript
clearAggregation(target?: ChartAggregationTarget): this
```

**Parameters**

* `target` — Optional. The aggregation property to clear. Omit it to clear all aggregation.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearAggregation(univerAPI.Enum.ChartAggregationTarget.TopN)
```

**Types:** [`ChartAggregationTarget`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/configuration/aggregation.d.ts)

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

### `FChart.clearAppearance`

Clears all common appearance properties or one selected property.

```typescript
clearAppearance(target?: ChartAppearanceTarget): this
```

**Parameters**

* `target` — Optional. The appearance property to clear. Omit it to clear all common appearance.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearAppearance(univerAPI.Enum.ChartAppearanceTarget.Background)
```

**Types:** [`ChartAppearanceTarget`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/configuration/appearance.d.ts)

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

### `FChart.clearCategoryField`

Clears the category field mapping of this live Chart.

```typescript
clearCategoryField(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearCategoryField()
```

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

### `FChart.clearCategoryFields`

Clears the ordered category fields used by this live Chart.

```typescript
clearCategoryFields(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fChart = fWorksheet.getCharts()[0]
fChart.clearCategoryFields()
```

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

### `FChart.clearLegend`

Clears the legend configuration of this live Chart.

```typescript
clearLegend(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearLegend()
```

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

### `FChart.clearPalette`

Clears the palette override and returns series-color control to the selected theme.

```typescript
clearPalette(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearPalette()
```

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

### `FChart.clearSubtitle`

Clears the subtitle of this live Chart.

```typescript
clearSubtitle(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearSubtitle()
```

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

### `FChart.clearTheme`

Clears the registered theme override of this live Chart.

```typescript
clearTheme(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearTheme()
```

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

### `FChart.clearTitle`

Clears the title of this live Chart.

```typescript
clearTitle(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearTitle()
```

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

### `FChart.clearValueFields`

Clears the value field mappings of this live Chart.

```typescript
clearValueFields(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.clearValueFields()
```

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

### `FChart.getId`

Returns the stable identifier of this Chart.

```typescript
getId(): string
```

**Returns**

The Chart identifier.

**Examples**

```ts
const fChart = fWorksheet.getCharts()[0]
console.log(fChart.getId())
```

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

### `FChart.getInfo`

Returns a detached, read-only snapshot of this Chart's configuration, data source, and placement.
Mutating the returned object does not update the live Chart.

```typescript
getInfo(): DeepReadonly<TInfo>
```

**Returns**

The complete Chart information snapshot.

**Examples**

```ts
const info = fWorksheet.getCharts()[0].getInfo()
console.log(info.config.type, info.dataSource)
```

**Types:** [`DeepReadonly`](https://unpkg.com/@univerjs/core/lib/types/shared/types.d.ts)

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

### `FChart.getType`

Returns the current type of this Chart.

```typescript
getType(): ChartTypeString
```

**Returns**

The current Chart type.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
console.log(fChart.getType())
```

**Types:** [`ChartTypeString`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.remove`

Removes this Chart from its host.

```typescript
remove(): Promise<boolean>
```

**Returns**

Whether the Chart was removed successfully.

**Examples**

```ts
const removed = await fWorksheet.getCharts()[0].remove()
console.log(removed)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

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

### `FChart.resetAutoGradientFill`

Clears the automatic-gradient override and restores the Chart type's default.

```typescript
resetAutoGradientFill(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.resetAutoGradientFill()
```

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

### `FChart.resetInvalidValueStrategy`

Restores the default invalid-value strategy of this live Chart.

```typescript
resetInvalidValueStrategy(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.resetInvalidValueStrategy()
```

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

### `FChart.sendBackward`

Moves this live Chart backward by one level in its host's persisted drawing order.

```typescript
sendBackward(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].sendBackward()
```

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

### `FChart.sendToBack`

Moves this live Chart to the back of its host's persisted drawing order.

```typescript
sendToBack(): this
```

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].sendToBack()
```

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

### `FChart.setAbsolutePosition`

Sets this live Chart's absolute host position.

```typescript
setAbsolutePosition(x: number, y: number): this
```

**Parameters**

* `x` — Required. The horizontal host coordinate.
* `y` — Required. The vertical host coordinate.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].setAbsolutePosition(120, 80)
```

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

### `FChart.setAggregation`

Sets the data aggregation configuration of this live Chart.

```typescript
setAggregation(value: IChartAggregationSpec): this
```

**Parameters**

* `value` — Required. The aggregation configuration to apply.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setAggregation({ topN: { count: 10, sourceIndex: 1 } })
```

**Types:** [`IChartAggregationSpec`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.setAppearance`

Sets common appearance properties of this live Chart.

```typescript
setAppearance(value: IChartAppearanceSpec): this
```

**Parameters**

* `value` — Required. The background and border configuration to apply.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setAppearance({ background: { color: '#ffffff' } })
```

**Types:** [`IChartAppearanceSpec`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.setAutoGradientFill`

Enables or disables the automatic gradient preset for supported Chart marks.

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

**Parameters**

* `value` — Required. Whether to apply the Chart type's automatic gradient preset.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setAutoGradientFill(true)
```

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

### `FChart.setCategoryField`

Sets the zero-based category field index used by this live Chart.

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

**Parameters**

* `index` — Required. The zero-based source field index.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setCategoryField(0)
```

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

### `FChart.setCategoryFields`

Sets the ordered category fields used by this live Chart's multi-level category axis.

```typescript
setCategoryFields(indexes: readonly number[]): this
```

**Parameters**

* `indexes` — Required. The zero-based source field indexes in root-to-leaf order.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fChart = fWorksheet.getCharts()[0]
fChart.setCategoryFields([0, 1, 2])
```

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

### `FChart.setDataSource`

Replaces this live Chart's host data source without changing its configuration.
Sheet Charts accept Sheet range sources.
Slide, Board, and Document Charts accept inline tables or resource references.
Resource references targeting a Sheet use a `range` part.
Base references currently select a complete table with a `table` part.

```typescript
setDataSource(source: TSource): Promise<this>
```

**Parameters**

* `source` — Required. The host-specific Chart data source.

**Returns**

This live Chart facade after the data source update completes.

**Examples**

Sheet Chart - Sheet range

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
await fChart.setDataSource('A1:C12')
```

Slide / Board / Document Chart - Inline table

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const fChart = fSlide.getCharts()[0]

await fChart.setDataSource([
  ['Quarter', 'Revenue'],
  ['Q1', 120],
  ['Q2', 180],
])
```

Slide / Board / Document Chart - Referenced Sheet range

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const fChart = fSlide.getCharts()[0]

await fChart.setDataSource({
  unit: { selector: 'workbook-unit-id', type: 'sheet' },
  part: {
    kind: 'range',
    ref: 'Data!A1:B10',
    sheetId: 'data-sheet-id',
    sheetName: 'Data',
    range: 'A1:B10',
  },
})
```

Slide / Board / Document Chart - Referenced Base table

```ts
const fPresentation = univerAPI.getActivePresentation()
const fSlide = fPresentation.getSlideByIndex(0)
const fChart = fSlide.getCharts()[0]

await fChart.setDataSource({
  unit: { selector: 'base-unit-id', type: 'base' },
  part: {
    kind: 'table',
    tableId: 'tasks-table-id',
    tableName: 'Tasks',
  },
})
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

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

### `FChart.setInvalidValueStrategy`

Sets how this live Chart handles invalid source values.

```typescript
setInvalidValueStrategy(value: InvalidValueType): this
```

**Parameters**

* `value` — Required. The invalid-value strategy to apply.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setInvalidValueStrategy(univerAPI.Enum.ChartInvalidValueType.Zero)
```

**Types:** [`InvalidValueType`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/enum.d.ts)

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

### `FChart.setLegend`

Sets the legend of this live Chart.

```typescript
setLegend(value: ChartLegendSpec): this
```

**Parameters**

* `value` — Required. Whether to show the legend or its configuration.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setLegend(true)
```

**Types:** [`ChartLegendSpec`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.setMultiLevelCategoryAxis`

Enables or disables the multi-level category axis for this live Chart's selected category fields.

```typescript
setMultiLevelCategoryAxis(enabled: boolean): this
```

**Parameters**

* `enabled` — Required. Whether to render the selected category fields as one multi-level axis.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setMultiLevelCategoryAxis(true)
```

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

### `FChart.setPalette`

Sets the ordered series palette colors of this live Chart.

```typescript
setPalette(colors: readonly string[]): this
```

**Parameters**

* `colors` — Required. CSS colors that override the selected theme's series colors.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setPalette(['#1677ff', '#52c41a'])
```

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

### `FChart.setSeriesToCategory`

Replaces all per-series category/X bindings. An empty object restores shared categories.
Keys are dataset value-field indexes, not series positions or visual axis IDs.
Values are ordered dataset category-field indexes. Scatter requires one X field;
Combination supports root-to-leaf fields when multi-level categories are enabled.
Omitted series retain the shared category selection; this does not create extra axes.
Input arrays are copied. Repeated calls replace this map without changing other selections.

```typescript
setSeriesToCategory(mapping: Record<number, number[]>): this
```

**Parameters**

* `mapping` — Required. Complete independent category mapping.

**Returns**

This chart API for chaining.

**Examples**

```ts
// Columns A/B/C/D become dataset fields 0/1/2/3.
// A = shared X, B = first Y, C = independent X, D = second Y.
fChart.setCategoryField(0).setValueFields([1, 3])
fChart.setSeriesToCategory({ 3: [2] }) // B uses A; D uses C.
fChart.setSeriesToCategory({ 1: [0], 3: [0] }) // Both explicitly use A.
fChart.setSeriesToCategory({}) // Both inherit the shared category again.
// Combination with multi-level categories enabled:
fChart.setSeriesToCategory({ 2: [0, 1] }) // Series 2 uses root field 0, leaf field 1.
```

**Types:** [`Record`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

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

### `FChart.setSize`

Sets this live Chart's host size.

```typescript
setSize(width: number, height: number): this
```

**Parameters**

* `width` — Required. The width in host coordinates.
* `height` — Required. The height in host coordinates.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].setSize(640, 360)
```

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

### `FChart.setSubtitle`

Sets the subtitle of this live Chart.

```typescript
setSubtitle(value: ChartSubtitleSpec): this
```

**Parameters**

* `value` — Required. The subtitle text or subtitle configuration.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setSubtitle('FY 2026')
```

**Types:** [`ChartSubtitleSpec`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.setTheme`

Sets a built-in or custom registered theme on this live Chart.

Use `univerAPI.Enum.ChartThemeName` for built-in themes. Custom names must first be
registered through `univerAPI.registerTheme()`. A non-empty palette continues to override
the selected theme's series colors until `clearPalette` is called.

```typescript
setTheme(name: string): this
```

**Parameters**

* `name` — Required. A built-in Chart theme name or the stable name of a custom registered theme.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setTheme(univerAPI.Enum.ChartThemeName.UniverGradient1)
```

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

### `FChart.setTitle`

Sets the title of this live Chart.

```typescript
setTitle(value: ChartTitleSpec): this
```

**Parameters**

* `value` — Required. The title text or title configuration.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setTitle('Quarterly sales')
```

**Types:** [`ChartTitleSpec`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.setType`

Sets the type of this live Chart without changing its data source or placement.

```typescript
setType(type: ChartTypeString): this
```

**Parameters**

* `type` — Required. The target Chart type.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setType(univerAPI.Enum.ChartTypeString.Pie)
```

**Types:** [`ChartTypeString`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts)

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

### `FChart.setValueFields`

Sets the ordered, zero-based value field indexes used by this live Chart.

```typescript
setValueFields(indexes: readonly number[]): this
```

**Parameters**

* `indexes` — Required. The zero-based source field indexes.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getSheetByName('Sheet1')
const fChart = fWorksheet.getCharts()[0]
fChart.setValueFields([1, 2])
```

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

### `FChart.setZOrder`

Moves this live Chart to a zero-based index in its host's persisted drawing order.
The host clamps an out-of-range index to its nearest valid position.

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

**Parameters**

* `index` — Required. The zero-based target order index.

**Returns**

This live Chart facade for chaining.

**Examples**

```ts
fWorksheet.getCharts()[0].setZOrder(2)
```

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

### `FChart.toBuilder`

Creates a detached Builder prefilled from this Chart.

The Builder does not update the live Chart. Call `build()` to obtain a new
information snapshot, then pass it to `update` or insert the
complete snapshot as another Chart. Pass a Chart type to build a converted copy.

```typescript
toBuilder(): FChartInfoBuilder<ChartTypeString, TSource, TDataSource, TInfo, TExtension>
toBuilder<T extends ChartTypeString>(type: T): FChartInfoBuilder<T, TSource, TDataSource, TInfo, TExtension>
```

**Parameters**

* `type` — Optional. The target Chart type for the detached copy.

**Returns**

A detached Builder using the current Chart type.

A detached type-specific Builder.

**Examples**

```ts
const fChart = fWorksheet.getCharts()[0]
const updatedInfo = fChart.toBuilder().setTitle('Updated sales').build()
await fChart.update(updatedInfo)
```

```ts
const fChart = fWorksheet.getCharts()[0]
const pieInfo = fChart.toBuilder(univerAPI.Enum.ChartTypeString.Pie).setDoughnutHole(0.4).build()
await fChart.update(pieInfo)
```

**Types:** [`ChartTypeString`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/chart-builder/chart-types.d.ts) · [`FChartInfoBuilder`](https://unpkg.com/@univerjs-pro/engine-chart/lib/types/facade/create-chart-builder.d.ts)

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

### `FChart.update`

Replaces this live Chart from complete host Chart information.

The host applies configuration, data source, placement, and host-specific fields as one
update so the change is represented by one undo/redo history item. Use the shortcut methods
below when only one common configuration property needs to change.

```typescript
update(info: TInfo): Promise<this>
```

**Parameters**

* `info` — Required. The complete Chart information returned by `toBuilder().build()`.

**Returns**

This live Chart facade after the update completes.

**Examples**

```ts
const fChart = fWorksheet.getCharts()[0]
const info = fChart.toBuilder().setTitle('Updated sales').build()
await fChart.update(info)
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

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