Web SDK

图表

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

预览

预设模式

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

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

插件模式

Shell
pnpm add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
TypeScript
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) 后，图表才会插入工作表。

TypeScript
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()，并启用多级分类轴。

TypeScript
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 参考。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.