# 交叉分析篩選器與時間軸

- Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/features/slicer](https://docs.univer.ai/zh-TW/guides/sheets/features/slicer)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/features/slicer.md](https://docs.univer.ai/zh-TW/guides/sheets/features/slicer.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.4.0`

- Source: [sheets/features/slicer.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/slicer.zh-TW.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/zh-TW",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css",
      "headless": "unsupported"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/sheets-slicer",
      "facade": "@univerjs-pro/sheets-slicer/facade",
      "headless": "supported"
    },
    {
      "client": "@univerjs-pro/sheets-slicer-ui",
      "locale": "@univerjs-pro/sheets-slicer-ui/locale/zh-TW",
      "style": "@univerjs-pro/sheets-slicer-ui/lib/index.css",
      "headless": "unsupported"
    }
  ],
  "license": true,
  "server": false
}
```

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

## 外掛模式

### 安裝

```package-install
npm install @univerjs-pro/sheets-slicer @univerjs-pro/sheets-slicer-ui
```

### 使用

在現有的 [Sheets 設定](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md)中加入以下內容，並設定[繪圖支援](https://docs.univer.ai/zh-TW/guides/sheets/features/images.md)以及[表格](https://docs.univer.ai/zh-TW/guides/sheets/features/table.md)或[樞紐分析表](https://docs.univer.ai/zh-TW/guides/sheets/features/pivot-table.md)資料來源。在建立活頁簿前載入語言套件並註冊這些外掛。

```ts
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)
```

## 預設模式

### 安裝

```package-install
npm install @univerjs/presets @univerjs/preset-sheets-core @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 使用

進階預設已包含交叉分析篩選器與時間軸的模型、UI 和 Facade API。請搭配核心與繪圖預設，並合併語言套件。若已使用進階預設，將 `slicer` 合併到原有設定，不要重複註冊。用戶端授權設定請見[使用授權](https://docs.univer.ai/zh-TW/server/license.md)。

```ts
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](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/worker.md) 時，在進階預設設定 `useWorker: true`，並在 Worker 註冊 `UniverSheetsAdvancedWorkerPreset()`，其中也包含篩選器計算外掛。

## 建立交叉分析篩選器

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

```ts
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` 物件。

```ts
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 參考：

- [FSheetSlicer](https://docs.univer.ai/zh-TW/reference/facade/sheet-slicer.md)
- [FSheetSlicerBuilder](https://docs.univer.ai/zh-TW/reference/facade/sheet-slicer-builder.md)
- [FSheetTimeline](https://docs.univer.ai/zh-TW/reference/facade/sheet-timeline.md)
- [FSheetTimelineBuilder](https://docs.univer.ai/zh-TW/reference/facade/sheet-timeline-builder.md)
- [FEventName](https://docs.univer.ai/zh-TW/reference/facade/events.md#univerjs-prosheets-slicer)

## 成員查詢與共用篩選

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

```ts
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](https://docs.univer.ai/zh-TW/reference/facade/sheet-slicer.md)。

## 時間軸日期條件

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