Web SDK

Спарклайн

Спарклайн — это компактная встроенная диаграмма, которая наглядно показывает тенденции данных или ключевые показатели и обычно размещается прямо в ячейке таблицы.

Режим плагинов

Установка

Shell
pnpm add @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui

Использование

TypeScript
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)

Если у вас есть коммерческая лицензия Univer, инструкции по настройке см. в разделе Использование лицензии в клиенте.

Поддержка мобильных устройств

Сначала настройте мобильный редактор. В коде инициализации режима плагинов на этой странице замените указанные настольные регистрации мобильными экспортами тех же пакетов до открытия документа. Сохраните модели, стили, локализации и импорты Facade; не регистрируйте оба варианта.

ПакетНастольная регистрацияМобильная регистрация
@univerjs-pro/sheets-sparkline-uiUniverSheetSparklineUIPluginUniverSheetSparklineMobileUIPlugin

Режим предустановки

Функция спарклайнов входит в предустановку @univerjs/preset-sheets-advanced.

Установка

Во время выполнения предустановка UniverSheetsAdvancedPreset из @univerjs/preset-sheets-advanced зависит от UniverSheetsDrawingPreset. Сначала установите @univerjs/preset-sheets-drawing.

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

Использование

TypeScript
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(),   ],})

Если у вас есть коммерческая лицензия Univer, инструкции по настройке см. в разделе Использование лицензии в клиенте.

Facade API

Импорт

Примечание о режиме плагинов

Вручную импортировать пакет Facade нужно только в режиме плагинов. В режиме предустановки соответствующий пакет Facade уже подключён, поэтому дополнительный импорт не требуется.

TypeScript
import '@univerjs-pro/sheets-sparkline/facade'

Добавление спарклайна

Метод FWorksheet.addSparkline добавляет спарклайн в указанный диапазон и возвращает экземпляр FSparkline.

TypeScript
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)

Объединение и разделение спарклайнов

Методы FWorksheet.composeSparkline и FWorksheet.unComposeSparkline используются для объединения и разделения спарклайнов.

TypeScript
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)

Получение экземпляров спарклайна и группы спарклайнов

Метод FWorksheet.getSparklineByCell получает спарклайн в указанной ячейке и возвращает экземпляр FSparkline.

TypeScript
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 получает группу спарклайнов в указанной ячейке и возвращает экземпляр FSparklineGroup.

TypeScript
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 предоставляет следующие методы для работы со спарклайном:

МетодОписание
changeDataSourceИзменить источник данных и расположение спарклайна в текущей ячейке
removeSparklineУдалить спарклайн из текущей ячейки

Экземпляр FSparklineGroup предоставляет следующие методы для работы с группой спарклайнов:

МетодОписание
changeDataSourceИзменить источник данных и расположение группы спарклайнов в текущей ячейке
removeSparklineGroupУдалить группу спарклайнов из текущей ячейки
setConfigИзменить конфигурацию группы спарклайнов в текущей ячейке

Обработчики событий

Полные определения типов событий доступны в разделе События.

Событие univerAPI.Event.SheetSparklineChanged срабатывает при изменении спарклайна.

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetSparklineChanged, (params) => {  const { workbook, worksheet, sparklines } = params})// Remove the event listener, use `disposable.dispose()`

Цвета и параметры отображения

Для настройки цветов и отображения всей группы используйте FSparklineGroup.setConfig(). Отдельного метода FSparkline.setColor() нет. Для собственного цвета задайте seriesColor и themeType: SparklineThemeTypeEnum.CUSTOM. Полный список параметров и примеры настройки маркеров, осей, максимума и минимума, пустых и скрытых ячеек, а также толщины линии приведены в разделе настройки группы спарклайнов.

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.