Web SDK

图表

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

插件模式

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)

移动端适配

先配置移动端编辑器。在本页插件模式的初始化代码中，将下列桌面端注册替换为同一个包导出的移动端插件，并在打开文档前完成。保留模型插件、样式、语言包和 Facade 导入，不要同时注册两个版本。

来源包桌面端注册移动端注册
@univerjs-pro/sheets-chart-uiUniverSheetsChartUIPluginUniverSheetsChartMobileUIPlugin

预设模式

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

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

创建和更新图表

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

隐藏数据与独立分类

setPlotVisibleOnly(false) 会包含隐藏行列中的值，getPlotVisibleOnly() 可读取该设置。数据源包含不同分类列时，setSeriesToCategory() 可将各值字段索引映射到其分类字段索引。索引指向原始数据向量，不随可见系列筛选而重新编号。未指定项继承共享分类，传入 {} 清除覆盖。

例如数据位于 A:D 时，D 列值系列可使用 C 列分类，B 列继续使用共享的 A 列分类。

TypeScript
const chart = worksheet.getCharts()[0]if (!chart) throw new Error('No chart')chart.setPlotVisibleOnly(false)chart.setSeriesToCategory({ 3: [2] })

需要聚合和交互式报表时，参见透视图。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.