# 图表

- Human documentation: [https://docs.univer.ai/zh-CN/guides/sheets/features/charts](https://docs.univer.ai/zh-CN/guides/sheets/features/charts)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/sheets/features/charts.md](https://docs.univer.ai/zh-CN/guides/sheets/features/charts.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [sheets/features/charts.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/charts.zh-CN.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/zh-CN",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/chart-ui",
      "locale": "@univerjs-pro/chart-ui/locale/zh-CN",
      "style": "@univerjs-pro/chart-ui/lib/index.css"
    },
    {
      "client": "@univerjs-pro/sheets-chart",
      "locale": "@univerjs-pro/sheets-chart/locale/zh-CN",
      "facade": "@univerjs-pro/sheets-chart/facade"
    },
    {
      "client": "@univerjs-pro/sheets-chart-ui",
      "locale": "@univerjs-pro/sheets-chart-ui/locale/zh-CN",
      "style": "@univerjs-pro/sheets-chart-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

图表可视化工作表数据，依赖图表模型和 UI 包。

> Interactive example: [Open the playground](/playground/sheets/charts)

## 预设模式

图表功能包含在 `@univerjs/preset-sheets-advanced` 中，运行时需要绘图预设。

#### npm

```bash
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

## 插件模式

#### npm

```bash
npm install @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
```

#### yarn

```bash
yarn add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
```

#### bun

```bash
bun add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
```

```ts
import ChartUIZhCN from '@univerjs-pro/chart-ui/locale/zh-CN'
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'
import SheetsChartUIZhCN from '@univerjs-pro/sheets-chart-ui/locale/zh-CN'
import SheetsChartZhCN from '@univerjs-pro/sheets-chart/locale/zh-CN'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/chart-ui/facade'
import '@univerjs-pro/sheets-chart/facade'
import '@univerjs-pro/chart-ui/lib/index.css'
import '@univerjs-pro/sheets-chart-ui/lib/index.css'

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(ChartUIZhCN, SheetsChartZhCN, SheetsChartUIZhCN),
  },
})

univer.registerPlugin(UniverSheetsChartPlugin)
univer.registerPlugin(UniverSheetsChartUIPlugin)
```

## 创建和更新图表

`worksheet.newChart(type)` 创建的是独立构建器。只有将 `build()` 的结果传给 `worksheet.insertChart(info)` 后，图表才会插入工作表。

```ts
const workbook = univerAPI.getActiveWorkbook()
if (!workbook) throw new Error('No active workbook')

const worksheet = workbook.getActiveSheet()
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D6',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setPosition('F2')
  .setSize(640, 360)
  .setCategoryField(0)
  .setValueFields([1, 2, 3])
  .setTitle('Quarterly revenue')
  .build()

const chart = await worksheet.insertChart(info)
chart.setLegend({ visible: true }).bringToFront()

const updatedInfo = chart.toBuilder(univerAPI.Enum.ChartTypeString.Line).setSubtitle('FY 2026').build()
await chart.update(updatedInfo)

const svg = await chart.exportImage({ format: 'svg' })
```

对已插入 `chart` 调用 setter 会立即更新图表。需要完整的独立副本或切换类型时，请结合使用 `toBuilder(type)` 与 `update(info)`。如果当前没有可生成图片的 UI 渲染器，`exportImage()` 会返回 `undefined`。

使用 `worksheet.getCharts()` 和 `worksheet.getChart(id)` 获取实时图表。需要删除时调用 `await chart.remove()`，共享 ECharts 主题则通过 `univerAPI.registerTheme(name, theme)` 注册。

## 多级分类轴

当相邻数据列组成层级关系时，请按从根到叶的顺序将从零开始的列索引传给 `setCategoryFields()`，并启用多级分类轴。

```ts
const info = worksheet
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    range: 'A1:D7',
    orientation: univerAPI.Enum.ChartSourceOrientation.Columns,
  })
  .setCategoryFields([0, 1])
  .setMultiLevelCategoryAxis(true)
  .setValueFields([2, 3])
  .setPosition('F2')
  .build()

const chart = await worksheet.insertChart(info)
chart.setCategoryFields([0, 1]).setMultiLevelCategoryAxis(true)
```

调用 `clearCategoryFields()` 可移除有序分类映射。`setMultiLevelCategoryAxis(false)` 只关闭层级渲染，并保留已选择的字段。

## 支持的图表类型

通过 `univerAPI.Enum.ChartTypeString` 使用 `Line`、`Column`、`ColumnStacked`、`ColumnPercentStacked`、`Bar`、`BarStacked`、`BarPercentStacked`、`Pie`、`Donut`、`Area`、`AreaStacked`、`AreaPercentStacked`、`Radar`、`Scatter`、`Combination`、`WordCloud`、`Funnel`、`Bubble`、`Relation`、`Waterfall`、`Pareto`、`Sankey`、`Heatmap`、`Boxplot`、`Candlestick`、`Histogram`、`Treemap`、`Sunburst`、`Gauge` 和 `Chord`。

共享构建器配置请参阅[图表 Facade 参考](https://docs.univer.ai/zh-CN/reference/facade/chart.md)。