交叉分析篩選器與時間軸

支援 Headless

交叉分析篩選器可依來源資料成員篩選表格、樞紐分析表和樞紐分析圖。時間軸用於篩選受支援的樞紐分析表原始日期欄位，不支援表格欄、文字欄位、計算欄位和衍生分組欄位。

外掛模式

安裝

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

使用

在現有的 Sheets 設定中加入以下內容，並設定繪圖支援以及表格或樞紐分析表資料來源。在建立活頁簿前載入語言套件並註冊這些外掛。

TypeScript
import { UniverSheetsSlicerPlugin } from '@univerjs-pro/sheets-slicer'import { UniverSheetsSlicerUIPlugin } from '@univerjs-pro/sheets-slicer-ui'import SheetsSlicerUILocale from '@univerjs-pro/sheets-slicer-ui/locale/zh-TW'import { LocaleType } from '@univerjs/core'import '@univerjs-pro/sheets-slicer/facade'import '@univerjs-pro/sheets-slicer-ui/lib/index.css'univerAPI.loadLocales(LocaleType.ZH_TW, SheetsSlicerUILocale)univer.registerPlugin(UniverSheetsSlicerPlugin)univer.registerPlugin(UniverSheetsSlicerUIPlugin)

預設模式

安裝

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

使用

進階預設已包含交叉分析篩選器與時間軸的模型、UI 和 Facade API。請搭配核心與繪圖預設，並合併語言套件。若已使用進階預設，將 slicer 合併到原有設定，不要重複註冊。用戶端授權設定請見使用授權。

TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import AdvancedLocale from '@univerjs/preset-sheets-advanced/locales/zh-TW'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import CoreLocale from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import DrawingLocale 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(CoreLocale, DrawingLocale, AdvancedLocale),  },  presets: [    UniverSheetsCorePreset({ container: 'app' }),    UniverSheetsDrawingPreset(),    UniverSheetsAdvancedPreset({ slicer: { maxMemberWindowSize: 200 } }),  ],})

使用 Worker 時，在進階預設設定 useWorker: true，並在 Worker 註冊 UniverSheetsAdvancedWorkerPreset()，其中也包含篩選器計算外掛。

建立交叉分析篩選器

以下範例使用作用中工作表 I1 處的樞紐分析表，其來源資料包含名為 Region 的欄位。透過 getSourceFieldsInfo() 取得原始欄位的穩定 ID；不能將顯示名稱或報表欄位 ID 傳給 newSlicer()。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook?.getActiveSheet()if (!fWorkbook || !fWorksheet) throw new Error('No active worksheet')const pivotTable = fWorkbook.getPivotTableByCell(  fWorkbook.getId(),  fWorksheet.getSheetId(),  0,  8,)const regionField = pivotTable?.getSourceFieldsInfo().find((field) => field.name === 'Region')if (!pivotTable || !regionField) throw new Error('Region source field not found')const slicer = await fWorksheet.insertSlicer(  pivotTable.newSlicer(regionField.id)    .setCaption(regionField.name)    .setPosition('N2')    .build(),)

pivotTable.newSlicer() 會將建構器綁定至資料來源。build() 只產生設定，insertSlicer() 才會建立控制項。控制項所在工作表可以與資料來源工作表不同，但兩者必須屬於同一活頁簿。若使用表格資料來源，呼叫 fWorksheet.newSlicer(columnId).setTableReference({ subUnitId, tableId })，其中 columnId 為表格欄的穩定 ID。

建立時間軸

繼續使用同一樞紐分析表，以下範例要求存在名為 Date 的原始日期欄位。newTimeline() 會驗證資料來源並拒絕不支援的欄位。時間軸範圍 API 使用活頁簿日期系統中的 Excel 序列值，不接受 JavaScript Date 物件。

TypeScript
const dateField = pivotTable.getSourceFieldsInfo().find((field) => field.name === 'Date')if (!dateField) throw new Error('Date source field not found')const timeline = await fWorksheet.insertTimeline(  pivotTable.newTimeline(dateField.id)    .setCaption(dateField.name)    .setLevel(univerAPI.Enum.TimelineLevel.Month)    .setPosition('N18')    .build(),)

尋找控制項與監聽變更

在控制項所在工作表上呼叫 getSlicer(viewId) / getSlicers() 和 getTimeline(viewId) / getTimelines()。viewId 是控制項 getId() 傳回的業務 ID，不是繪圖 ID。

透過 univerAPI.addEvent() 監聽 SlicerAdded、SlicerChanged、SlicerRemoved、TimelineAdded、TimelineChanged 和 TimelineRemoved。事件表示已提交的本機變更，不表示遠端儲存或繪製已完成。不再需要監聽時，呼叫傳回訂閱的 dispose()。

API 參考：

成員查詢與共用篩選

setSelection() 使用具型別的來源值：數字 1、字串 '1' 與空白是不同成員，不可傳入顯示標籤或清單索引。篩選會套用至相同快取的所有檢視與連接報表。表格來源會取代該欄的篩選並保留其他欄。呼叫 clearFilter() 可清除篩選。

TypeScript
import { FilterSelectionMode, RecordValueType } from '@univerjs/core'const accepted = await slicer.setSelection({  mode: FilterSelectionMode.Include,  values: [{ type: RecordValueType.String, value: 'EMEA' }],})

getItems({ start, count }) 僅查詢一個視窗，不會讀取全部來源或改變選取狀態。預設查詢 100 項，上限由 maxMemberWindowSize 控制，預設為正整數 200。分頁時請保留視窗外的選取值。setConnections() 取代樞紐報表連接，可用 getConnectionCandidates() 查詢相容報表。編輯需要相應工作表權限，詳見 FSheetSlicer。

時間軸日期條件

setSelection({ startDate, endDate, useWholeDay: true }) 將含小數的邊界擴展為整日，整數結束值仍不包含在區間內。未設定 useWholeDay 時，區間精確為 [startDate, endDate)。樞紐分析表共享的固定日期條件可能不是連續區間，應使用 getDateCondition() 讀取。此時 getSelection() 回傳 undefined，不能僅據此判斷時間軸未篩選。

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.