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

如果你擁有 Univer 的商業許可證，請參考在客戶端使用許可證進行配置。

行動裝置支援

先設定行動版編輯器。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在開啟文件前完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

套件桌面版註冊行動版註冊
@univerjs-pro/sheets-sparkline-uiUniverSheetSparklineUIPluginUniverSheetSparklineMobileUIPlugin

預設模式

迷你圖功能被包含在 @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 UniverPresetSheetsAdvancedZhTW from '@univerjs/preset-sheets-advanced/locales/zh-TW'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhTW from '@univerjs/preset-sheets-drawing/locales/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsDrawingZhTW,       UniverPresetSheetsAdvancedZhTW,     ),  },  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()// 建立一個迷你圖，資料來源為 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()`

顏色與顯示選項

迷你圖的顏色等視覺選項透過 FSparklineGroup.setConfig() 設定，並非獨立的 FSparkline.setColor() 方法。設定會套用至整個迷你圖群組。自訂顏色時，需同時設定 seriesColor 與 themeType: SparklineThemeTypeEnum.CUSTOM。顏色、標記點、座標軸、最大／最小值、空值、隱藏儲存格、線寬等完整選項及範例，請參閱迷你圖群組設定。

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.