Sparkline

Univer Pro

Sparkline is a compact, inline chart that provides a visual representation of data trends or key metrics, typically embedded within a table cell.

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.

npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

Usage

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.

Plugin Mode

Installation

npm install @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui

Usage

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.

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 group
fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])
console.log(fWorksheet.getAllSubSparkline().size) // 1

// After 3 seconds, uncompose the sparkline group
setTimeout(() => {
  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 group
setTimeout(() => {
  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()`

Table of Contents