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
TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-advanced/lib/index.css'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsDrawingZhCN,      UniverPresetSheetsAdvancedZhCN,    ),  },  presets: [UniverSheetsCorePreset(), UniverSheetsDrawingPreset(), UniverSheetsAdvancedPreset()],})

创建和更新图表

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] })

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

三维图表

三维图表沿用同一套图表插件注册配置。选择三维类型后，通过独立构建器设置视角。

支持的类型包括 Line3D、Column3D、ColumnStacked3D、ColumnPercentStacked3D、Bar3D、BarStacked3D、BarPercentStacked3D、Pie3D、Area3D、AreaStacked3D 和 AreaPercentStacked3D。

TypeScript
const info = worksheet  .newChart(univerAPI.Enum.ChartTypeString.Column3D)  .setSource('A1:C5')  .setCategoryField(0)  .setValueFields([1, 2])  .setPosition('F18')  .setSize(640, 360)  .setThreeD({    view: { rotX: 20, rotY: 30, rightAngleAxes: false, perspective: 30 },    gapDepth: 120,  })  .build()await worksheet.insertChart(info)

对于带坐标轴的图表，rightAngleAxes: false 时才会应用 perspective。clearThreeD() 清除自定义三维视图设置，但保留三维类型和深度轴；清除深度轴使用 clearDepthAxis()。三维坐标轴图表不提供次坐标轴或趋势线，Pie3D 使用实心饼图。

对数数值轴

二维折线图、面积图、柱状图、条形图及组合图的数值轴支持 scaleType: 'log'。纵向数值轴使用 setYAxis()；条形图的横向数值轴使用 setXAxis()。setRightYAxis() 用于配置已有的次级数值轴。

默认底数为 10。自定义 logBase 必须是 2 到 1000 之间的有限数，也支持 2.5 这样的非整数；数值轴上下界必须为正。零和负数数据点不参与对数绘制，原始数据保持不变。百分比堆叠图和三维图表不支持对数轴。

TypeScript
const info = worksheet  .newChart(univerAPI.Enum.ChartTypeString.Line)  .setSource('A1:B5')  .setYAxis({ scaleType: 'log', logBase: 10 })  .setPosition('F36')  .setSize(640, 360)  .build()const chart = await worksheet.insertChart(info)await chart.update(  chart.toBuilder(univerAPI.Enum.ChartTypeString.Line)    .setYAxis({ scaleType: 'linear' })    .build(),)

新图表需构建后插入；修改已有图表时，通过 await chart.update(builder.build()) 应用构建器结果。设置 scaleType: 'linear' 会移除对数底数；修改其他轴属性会保留原有刻度。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.