Chart
| Packages | @univerjs-pro/engine-chart, @univerjs-pro/sheets-chart, @univerjs-pro/slides-chart, @univerjs-pro/boards-chart, @univerjs-pro/docs-chart, @univerjs-pro/chart-ui |
|---|
Charts use direct host Facade methods. Create detached chart information with newChart(type), insert it with insertChart(info), and then edit the returned live FChart.
Import
@univerjs-pro/engine-chart/facadeand the matching host facade. Import@univerjs-pro/chart-ui/facadeto add image export.
Host lifecycle
| Host | Create and insert | Read |
|---|---|---|
| Sheets | FWorksheet.newChart(type), insertChart(info) | getChart(id), getCharts() |
| Slides | FSlide.newChart(type), insertChart(info) | getChart(id), getCharts() |
| Boards | FBoard.newChart(type), insertChart(info) | getChart(id), getCharts() |
| Docs | FDocument.newChart(type), insertChart(info) | getChart(id), getCharts() |
newChart() returns a type-specific builder. It does not mutate the host until build() is passed to insertChart().
Sheets example
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.setTitle('Quarterly revenue (updated)').bringToFront()Use getChart(id) or getCharts() to resolve live charts. Common setters update an inserted chart immediately; setDataSource(), update(), remove(), and image export are asynchronous.
const updatedInfo = chart.toBuilder(univerAPI.Enum.ChartTypeString.Line).setSubtitle('FY 2026').build()await chart.update(updatedInfo)const svg = await chart.exportImage({ format: 'svg' })exportImage() returns undefined when the current host has no UI renderer. Call await chart.remove() only when you want to delete the inserted chart.
Register shared themes on univerAPI:
registerTheme(name: string, theme: IEchartTheme): voidLive data sources
FChart.setDataSource() replaces the host source without changing chart configuration. Sheet charts accept a range string. Slide, Board, and Document charts accept inline tables or resource references to a Sheet range or a complete Base table.
await sheetChart.setDataSource('A1:C12')await slideChart.setDataSource([ ['Quarter', 'Revenue'], ['Q1', 120], ['Q2', 180],])await boardChart.setDataSource({ unit: { selector: 'base-unit-id', type: 'base' }, part: { kind: 'table', tableId: 'tasks-table-id', tableName: 'Tasks', },})Referenced Sheet sources use a range part with the sheet identity and A1 range. Referenced Base sources currently select a complete table.
Detached builders
| API | Methods |
|---|---|
| Builder lifecycle | setSource, setAbsolutePosition, setSize, build |
| Titles and legend | setTitle, clearTitle, setSubtitle, clearSubtitle, setLegend, clearLegend |
| Appearance and data | setTheme, setPalette, setAppearance, setAggregation, setCategoryField, setCategoryFields, setMultiLevelCategoryAxis, setValueFields, setInvalidValueStrategy, setAutoGradientFill |
| Type-specific builders | Axis, series, line, pie, bubble, candlestick, histogram, hierarchy, gauge, and relation-chart methods |
Builder methods only change a detached draft. build() returns an insertable information snapshot.
Multi-level category axes
When adjacent source fields form a hierarchy, pass their zero-based indexes to setCategoryFields() in root-to-leaf order, then enable the multi-level axis.
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() removes the ordered category mapping. setMultiLevelCategoryAxis(false) only switches the hierarchical rendering off and preserves the selected fields.
Live charts
| API | Methods |
|---|---|
| Live inspection | getId, getType, getInfo, toBuilder |
| Immediate updates | setType, setCategoryFields, clearCategoryFields, setMultiLevelCategoryAxis, the other shared configuration setters, setAbsolutePosition, setSize |
| Asynchronous updates | setDataSource, update, remove |
| Order | setZOrder, bringToFront, bringForward, sendBackward, sendToBack |
| Image export | exportImage(options?) for a PNG or SVG data URL; requires @univerjs-pro/chart-ui/facade |
Host-specific builders
| Host | Source and placement |
|---|---|
| Sheets | A1 ranges or range specs; setPosition(anchor) |
| Slides | Inline values or a Sheet resource reference; setPlaceholder, setStroke, setZOrder |
| Boards | Inline values or a Sheet resource reference; setContainer, setLane, setZOrder |
| Docs | Inline values or a Sheet resource reference; setPosition, setLayout, setInline, setFloating |
Slides, Boards, and Docs can reference a Sheet range instead of copying values:
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)Source: @univerjs-pro/engine-chart, @univerjs-pro/sheets-chart, @univerjs-pro/slides-chart,
@univerjs-pro/boards-chart, @univerjs-pro/docs-chart, @univerjs-pro/chart-ui
你觉得这篇文档如何？