Web SDK

圖表

圖表會將工作表資料視覺化，並使用圖表模型及 UI 套件。

外掛模式

Shell
pnpm add @univerjs-pro/chart-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui
TypeScript
import ChartUIZhTW from '@univerjs-pro/chart-ui/locale/zh-TW'import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart'import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui'import SheetsChartUIZhTW from '@univerjs-pro/sheets-chart-ui/locale/zh-TW'import SheetsChartZhTW from '@univerjs-pro/sheets-chart/locale/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(ChartUIZhTW, SheetsChartZhTW, SheetsChartUIZhTW),  },})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 UniverPresetSheetsAdvancedZhTW from '@univerjs/preset-sheets-advanced/locales/zh-TW'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhTW from '@univerjs/preset-sheets-drawing/locales/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsDrawingZhTW,      UniverPresetSheetsAdvancedZhTW,    ),  },  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.