# 图表

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

#### Package metadata

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

## 注册图表支持

幻灯片图表由模型包和 UI 包组成；`@univerjs-pro/chart-ui` 为图表 UI 提供共享控件、语言包和样式。

```ts
import ChartUIZhCN from '@univerjs-pro/chart-ui/locale/zh-CN'
import { UniverSlidesChartPlugin } from '@univerjs-pro/slides-chart'
import { UniverSlidesChartUIPlugin } from '@univerjs-pro/slides-chart-ui'
import SlidesChartUIZhCN from '@univerjs-pro/slides-chart-ui/locale/zh-CN'
import { LocaleType, mergeLocales } from '@univerjs/core'

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

univerAPI.loadLocales(LocaleType.ZH_CN, mergeLocales(ChartUIZhCN, SlidesChartUIZhCN))
univer.registerPlugin(UniverSlidesChartPlugin)
univer.registerPlugin(UniverSlidesChartUIPlugin)
```

在打开或导入可能包含图表元素的演示文稿前注册图表支持。

## 创建和更新图表

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

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

const slide = presentation.getActiveSlide()
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource([
    ['Month', 'Revenue', 'Cost'],
    ['Jan', 120, 80],
    ['Feb', 180, 96],
    ['Mar', 240, 132],
  ])
  .setTitle('Quarterly revenue')
  .setAbsolutePosition(80, 120)
  .setSize(520, 320)
  .setZOrder(1)
  .build()

const chart = await slide.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`。

使用 `slide.getCharts()` 和 `slide.getChart(id)` 获取实时图表。需要删除时调用 `await chart.remove()`。Slides 构建器额外提供 `setPlaceholder()`、`setStroke()` 和 `setZOrder()`。

## 多级分类轴

对于内联层级数据，请按从根到叶的顺序选择分类字段，并启用多级渲染：

```ts
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource([
    ['Region', 'Quarter', 'Revenue'],
    ['North', 'Q1', 120],
    ['North', 'Q2', 148],
    ['South', 'Q1', 98],
    ['South', 'Q2', 132],
  ])
  .setCategoryFields([0, 1])
  .setMultiLevelCategoryAxis(true)
  .setValueFields([2])
  .setAbsolutePosition(80, 120)
  .setSize(520, 320)
  .build()

await slide.insertChart(info)
```

## 绑定 Sheet 数据

如果图表需要跟随 Sheet 区域而不是保存值副本，请将资源引用传给 `setSource()`：

```ts
const info = slide
  .newChart(univerAPI.Enum.ChartTypeString.Column)
  .setSource({
    unit: { selector: 'sales-workbook', type: 'sheet' },
    part: {
      kind: 'range',
      sheetName: 'Data',
      range: 'A1:B20',
      ref: 'Data!A1:B20',
    },
  })
  .setAbsolutePosition(120, 80)
  .setSize(640, 360)
  .build()

const chart = await slide.insertChart(info)
```

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