Web SDK

迷你图

迷你图是一种简洁、直观的小型图表，通常嵌入在表格单元格中，用于快速展示数据趋势或关键指标。

预设模式

迷你图功能被包含在 @univerjs/preset-sheets-advanced 预设中。

安装

@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 预设在运行时依赖 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 UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'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.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsDrawingZhCN,       UniverPresetSheetsAdvancedZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),     UniverSheetsAdvancedPreset(),   ],})

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

插件模式

安装

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 SheetsSparklineUIZhCN from '@univerjs-pro/sheets-sparkline-ui/locale/zh-CN'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.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      SheetsSparklineUIZhCN,     ),  },})univer.registerPlugin(UniverSheetSparklinePlugin)univer.registerPlugin(UniverSheetSparklineUIPlugin)

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

Facade API

引入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

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

添加迷你图

FWorksheet.addSparkline 方法用于在指定区域添加迷你图，返回一个 FSparkline 实例。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()// 创建一个迷你图，数据源为 A1:A7，放置在 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()// 创建一个迷你图，数据源为 A1:A7，放置在 A10 单元格中。const firstSparkline = fWorksheet.addSparkline(  [fWorksheet.getRange('A1:A7').getRange()],  [fWorksheet.getRange('A10').getRange()],)// 创建一个迷你图，数据源为 B1:B7，放置在 B10 单元格中。const secondSparkline = fWorksheet.addSparkline(  [fWorksheet.getRange('B1:B7').getRange()],  [fWorksheet.getRange('B10').getRange()],)// 将两个迷你图组合成一个迷你图组fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])console.log(fWorksheet.getAllSubSparkline().size) // 1// 3 秒后取消组合迷你图组setTimeout(() => {  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()// 创建一个迷你图，数据源为 A1:A7，放置在 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()// 创建一个迷你图，数据源为 A1:A7，放置在 A10 单元格中。const firstSparkline = fWorksheet.addSparkline(  [fWorksheet.getRange('A1:A7').getRange()],  [fWorksheet.getRange('A10').getRange()],)// 创建一个迷你图，数据源为 B1:B7，放置在 B10 单元格中。const secondSparkline = fWorksheet.addSparkline(  [fWorksheet.getRange('B1:B7').getRange()],  [fWorksheet.getRange('B10').getRange()],)console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))// 3 秒后将两个迷你图组合成一个迷你图组setTimeout(() => {  fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()])  console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0))}, 3000)

FSparkline 实例有以下方法用来操作迷你图：

方法描述
changeDataSource修改当前单元格内迷你图的数据源和放置位置
removeSparkline删除当前单元格内的迷你图

FSparklineGroup 实例有以下方法用来操作迷你图组：

方法描述
changeDataSource修改当前单元格内迷你图组的数据源和放置位置
removeSparklineGroup删除当前单元格内的迷你图所在的迷你图组
setConfig更改当前单元格内的迷你图所在的迷你图组的配置

事件监听

完整事件类型定义，请查看 Events。

univerAPI.Event.SheetSparklineChanged 事件在迷你图发生变化时触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetSparklineChanged, (params) => {  const { workbook, worksheet, sparklines } = params})// 移除事件监听器，使用 `disposable.dispose()`

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.