Sparkline
Sparkline is a compact, inline chart that provides a visual representation of data trends or key metrics, typically embedded within a table cell.
Plugin Mode
Installation
pnpm add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-uinpm install @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-uiyarn add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-uibun add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-uiUsage
import { UniverSheetSparklinePlugin } from '@univerjs-pro/sheets-sparkline'import { UniverSheetSparklineUIPlugin } from '@univerjs-pro/sheets-sparkline-ui'import SheetsSparklineUIEnUS from '@univerjs-pro/sheets-sparkline-ui/locale/en-US'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/sheets-sparkline/facade'import '@univerjs-pro/sheets-sparkline-ui/lib/index.css'const univer = new Univer({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( SheetsSparklineUIEnUS, ), },})univer.registerPlugin(UniverSheetSparklinePlugin)univer.registerPlugin(UniverSheetSparklineUIPlugin)If you have a commercial license for Univer, please refer to Using License in Client for configuration.
Mobile support
First configure the mobile editor. In this page’s plugin-mode setup, replace the desktop registrations below with their mobile exports from the same packages, before opening a document. Keep the model plugins, styles, locales and Facade imports; do not register both variants.
| Package | Desktop registration | Mobile registration |
|---|---|---|
@univerjs-pro/sheets-sparkline-ui | UniverSheetSparklineUIPlugin | UniverSheetSparklineMobileUIPlugin |
Preset Mode
The sparkline feature is included in the @univerjs/preset-sheets-advanced preset.
Installation
The UniverSheetsAdvancedPreset preset from @univerjs/preset-sheets-advanced depends on the UniverSheetsDrawingPreset preset at runtime. Please install @univerjs/preset-sheets-drawing first.
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancednpm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedyarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedbun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedUsage
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetSheetsCoreEnUS, UniverPresetSheetsDrawingEnUS, UniverPresetSheetsAdvancedEnUS, ), }, presets: [ UniverSheetsCorePreset(), UniverSheetsDrawingPreset(), UniverSheetsAdvancedPreset(), ],})If you have a commercial license for Univer, please refer to Using License in Client for configuration.
Facade API
Importing
Plugin mode note
Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.
import '@univerjs-pro/sheets-sparkline/facade'Add Sparkline
FWorksheet.addSparkline method is used to add a sparkline in the specified range, returning an FSparkline instance.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a sparkline with data source from A1:A7, placed in cell A10.const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]const targetRanges = [fWorksheet.getRange('A10').getRange()]const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges, univerAPI.Enum.SparklineTypeEnum.LINE_CHART)Compose and Uncomposing Sparkline
FWorksheet.composeSparkline and FWorksheet.unComposeSparkline methods are used to compose and uncompose sparklines.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a sparkline with data source from A1:A7, placed in cell A10.const firstSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('A1:A7').getRange()], [fWorksheet.getRange('A10').getRange()],)// Create a sparkline with data source from B1:B7, placed in cell B10.const secondSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('B1:B7').getRange()], [fWorksheet.getRange('B10').getRange()],)// Compose the two sparklines into a sparkline groupfWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])console.log(fWorksheet.getAllSubSparkline().size) // 1// After 3 seconds, uncompose the sparkline groupsetTimeout(() => { fWorksheet.unComposeSparkline([fWorksheet.getRange('A10:B10').getRange()]) console.log(fWorksheet.getAllSubSparkline().size) // 2}, 3000)Get Sparkline and Sparkline Group Instances
FWorksheet.getSparklineByCell is used to get the sparkline instance in a specified cell, returning an FSparkline instance.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a sparkline with data source from A1:A7, placed in cell A10.const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]const targetRanges = [fWorksheet.getRange('A10').getRange()]const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges)console.log('Cell A10: ', fWorksheet.getSparklineByCell(9, 0))console.log('Cell A11: ', fWorksheet.getSparklineByCell(10, 0))FWorksheet.getSparklineGroupByCell is used to get the sparkline group instance in a specified cell, returning an FSparklineGroup instance.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// Create a sparkline with data source from A1:A7, placed in cell A10.const firstSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('A1:A7').getRange()], [fWorksheet.getRange('A10').getRange()],)// Create a sparkline with data source from B1:B7, placed in cell B10.const secondSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('B1:B7').getRange()], [fWorksheet.getRange('B10').getRange()],)console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))// After 3 seconds, compose the two sparklines into a sparkline groupsetTimeout(() => { fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()]) console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))}, 3000)FSparkline instance has the following methods to manipulate the sparkline:
| Method | Description |
|---|---|
| changeDataSource | Modify the data source and placement of the sparkline in the current cell |
| removeSparkline | Remove the sparkline in the current cell |
FSparklineGroup instance has the following methods to manipulate the sparkline group:
| Method | Description |
|---|---|
| changeDataSource | Modify the data source and placement of the sparkline group in the current cell |
| removeSparklineGroup | Remove the sparkline group in the current cell |
| setConfig | Change the configuration of the sparkline group in the current cell |
Event Listeners
Complete event type definitions can be found in the Events.
univerAPI.Event.SheetSparklineChanged event is triggered when the sparkline changes.
const disposable = univerAPI.addEvent(univerAPI.Event.SheetSparklineChanged, (params) => { const { workbook, worksheet, sparklines } = params})// Remove the event listener, use `disposable.dispose()`Colors and display options
Use FSparklineGroup.setConfig() to configure colors and display options for the entire group. Set both seriesColor and themeType: SparklineThemeTypeEnum.CUSTOM for custom colors. See sparkline group configuration for the complete option table and example, including point markers, axes, extrema, empty values, hidden cells and line width.
How is this guide?