# 篩選 - Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/features/filter](https://docs.univer.ai/zh-TW/guides/sheets/features/filter) - Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/features/filter.md](https://docs.univer.ai/zh-TW/guides/sheets/features/filter.md) - Requested language: `zh-TW` - Content language: `zh-TW` - Documentation version: `1.2.0` - Source: [sheets/features/filter.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/filter.zh-TW.mdx) --- #### Package metadata ```json { "preset": [ { "client": "@univerjs/preset-sheets-filter", "locale": "@univerjs/preset-sheets-filter/locales/zh-TW", "style": "@univerjs/preset-sheets-filter/lib/index.css" } ], "plugins": [ { "client": "@univerjs/sheets-filter", "facade": "@univerjs/sheets-filter/facade", "locale": "@univerjs/sheets-filter/locale/zh-TW" }, { "client": "@univerjs/sheets-filter-ui", "locale": "@univerjs/sheets-filter-ui/locale/zh-TW", "style": "@univerjs/sheets-filter-ui/lib/index.css" } ], "mobile": true, "headless": true, "license": false, "server": false } ``` 篩選功能允許使用者對電子表格中的資料進行篩選，以便快速查詢和分析特定資訊。它支援多種篩選條件和操作，幫助使用者更高效地處理資料。 ## 外掛模式 ### 安裝 #### npm ```bash npm install @univerjs/sheets-filter @univerjs/sheets-filter-ui ``` #### pnpm ```bash pnpm add @univerjs/sheets-filter @univerjs/sheets-filter-ui ``` #### yarn ```bash yarn add @univerjs/sheets-filter @univerjs/sheets-filter-ui ``` #### bun ```bash bun add @univerjs/sheets-filter @univerjs/sheets-filter-ui ``` ### 使用 ```typescript import { LocaleType, mergeLocales, Univer } from '@univerjs/core' import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter' // [!code ++] import { UniverSheetsFilterUIPlugin } from '@univerjs/sheets-filter-ui' // [!code ++] import SheetsFilterUIZhTW from '@univerjs/sheets-filter-ui/locale/zh-TW' // [!code ++] import '@univerjs/sheets-filter-ui/lib/index.css' // [!code ++] import '@univerjs/sheets-filter/facade' // [!code ++] const univer = new Univer({ locale: LocaleType.ZH_TW, locales: { [LocaleType.ZH_TW]: mergeLocales( SheetsFilterUIZhTW, // [!code ++] ), }, }) univer.registerPlugin(UniverSheetsFilterPlugin) // [!code ++] univer.registerPlugin(UniverSheetsFilterUIPlugin) // [!code ++] ``` ### 外掛與配置 ```typescript interface IUniverSheetsFilterConfig { /** * 是否在篩選面板中顯示篩選器同步開關。 * 這個配置可以在協作場景中使用，允許使用者選擇是否啟用篩選器同步。 * 如果設定為 defaultValue 物件，則會顯示篩選器同步開關，其初始狀態將由 defaultValue 屬性決定。 * @default false */ enableSyncSwitch?: boolean | { defaultValue: boolean } } ``` ## 行動裝置支援 先設定[行動版編輯器](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md#mobile-support)。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在**開啟文件前**完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。 | 套件 | 桌面版註冊 | 行動版註冊 | | ---------------------------- | ---------------------------- | ---------------------------------- | | `@univerjs/sheets-filter-ui` | `UniverSheetsFilterUIPlugin` | `UniverSheetsFilterMobileUIPlugin` | ## 預設模式 ### 安裝 #### npm ```bash npm install @univerjs/preset-sheets-filter ``` #### pnpm ```bash pnpm add @univerjs/preset-sheets-filter ``` #### yarn ```bash yarn add @univerjs/preset-sheets-filter ``` #### bun ```bash bun add @univerjs/preset-sheets-filter ``` ### 使用 ```typescript import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core' import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW' import { UniverSheetsFilterPreset } from '@univerjs/preset-sheets-filter' // [!code ++] import UniverPresetSheetsFilterZhTW from '@univerjs/preset-sheets-filter/locales/zh-TW' // [!code ++] import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets' import '@univerjs/preset-sheets-core/lib/index.css' import '@univerjs/preset-sheets-filter/lib/index.css' // [!code ++] const { univerAPI } = createUniver({ locale: LocaleType.ZH_TW, locales: { [LocaleType.ZH_TW]: mergeLocales( UniverPresetSheetsCoreZhTW, UniverPresetSheetsFilterZhTW, // [!code ++] ), }, presets: [ UniverSheetsCorePreset(), UniverSheetsFilterPreset(), // [!code ++] ], }) ``` ### 預設與配置 ```typescript interface IUniverSheetsFilterPresetConfig { /** * 是否在篩選面板中顯示篩選器同步開關。 * 這個配置可以在協作場景中使用，允許使用者選擇是否啟用篩選器同步。 * 如果設定為 defaultValue 物件，則會顯示篩選器同步開關，其初始狀態將由 defaultValue 屬性決定。 * @default false */ enableSyncSwitch?: boolean | { defaultValue: boolean } } ``` ## Facade API 完整 Facade API 型別定義，請檢視 [FacadeAPI](https://docs.univer.ai/zh-TW/reference/facade/univer.md)。 ### 引入 > [!INFO: 外掛模式提示] > 僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件，無需額外引入。 ```typescript import '@univerjs/sheets-filter/facade' ``` ### 獲取篩選器 返回一個 [`FFilter`](https://docs.univer.ai/zh-TW/reference/facade/filter.md) 物件，若 sheet 沒有篩選器，則返回 `null`。 * `FWorksheet` 物件上的 [`getFilter()`](https://docs.univer.ai/zh-TW/reference/facade/worksheet.md#getfilter) * `FRange` 物件上的 [`getFilter()`](https://docs.univer.ai/zh-TW/reference/facade/range.md#getfilter) ```typescript const fWorkbook = univerAPI.getActiveWorkbook() // 從 FWorksheet 獲取篩選器 const fWorksheet = fWorkbook.getActiveSheet() const fFilter = fWorksheet.getFilter() fFilter?.getRange().getA1Notation() // 從 FRange 獲取篩選器 const fRange = fWorksheet.getRange('A1:D14') const fFilter2 = fRange.getFilter() fFilter2?.getRange().getA1Notation() ``` ### 建立篩選器 建立一個 [`FFilter`](https://docs.univer.ai/zh-TW/reference/facade/filter.md) 物件，若 sheet 已經有篩選器，則返回 `null`。 * `FRange` 物件上的 [`createFilter()`](https://docs.univer.ai/zh-TW/reference/facade/range.md#createfilter) ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() const fRange = fWorksheet.getRange('A1:D14') let fFilter = fRange.createFilter() // 如果工作表已經有篩選器，則移除它並建立一個新的篩選器。 if (!fFilter) { fWorksheet.getFilter().remove() fFilter = fRange.createFilter() } fFilter.getRange().getA1Notation() ``` ### 移除篩選器 [`FFilter.remove()`](https://docs.univer.ai/zh-TW/reference/facade/filter.md#remove) 方法移除篩選器。 ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() fWorksheet.getFilter()?.remove() ``` ### 獲取列過濾條件 [`FFilter.getColumnFilterCriteria(column)`](https://docs.univer.ai/zh-TW/reference/facade/filter.md#getcolumnfiltercriteria) 方法返回指定列的篩選條件。 ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() // 設定 C1:F10 範圍的值 const fRange = fWorksheet.getRange('C1:F10') fRange.setValues([ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8], [6, 7, 8, 9], [7, 8, 9, 10], [8, 9, 10, 11], [9, 10, 11, 12], [10, 11, 12, 13], ]) // 建立 C1:F10 範圍的篩選器 let fFilter = fRange.createFilter() // 如果篩選器已經存在，則移除它並建立一個新的篩選器 if (!fFilter) { fRange.getFilter().remove() fFilter = fRange.createFilter() } // 設定 C 列的篩選條件，篩選出值不是 1、5、9 的行 const column = fWorksheet.getRange('C:C').getColumn() fFilter.setColumnFilterCriteria(column, { colId: 0, filters: { filters: ['1', '5', '9'], }, }) // 獲取 C 和 D 列的篩選條件 fFilter.getColumnFilterCriteria(column) // { colId: 0, filters: { filters: ['1', '5', '9'] } } fFilter.getColumnFilterCriteria(column + 1) // undefined ``` ### 設定列篩選條件 [`FFilter.setColumnFilterCriteria(column, criteria)`](https://docs.univer.ai/zh-TW/reference/facade/filter.md#setcolumnfiltercriteria) 方法設定指定列的篩選條件。 ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() // 設定 C1:F10 範圍的值 const fRange = fWorksheet.getRange('C1:F10') fRange.setValues([ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8], [6, 7, 8, 9], [7, 8, 9, 10], [8, 9, 10, 11], [9, 10, 11, 12], [10, 11, 12, 13], ]) // 建立 C1:F10 範圍的篩選器 let fFilter = fRange.createFilter() // 如果篩選器已經存在，則移除它並建立一個新的篩選器 if (!fFilter) { fRange.getFilter().remove() fFilter = fRange.createFilter() } // 設定 C 列的篩選條件，篩選出值不是 1、5、9 的行 const column = fWorksheet.getRange('C:C').getColumn() fFilter.setColumnFilterCriteria(column, { colId: 0, filters: { filters: ['1', '5', '9'], }, }) ``` ### 移除列篩選條件 * [`FFilter.removeColumnFilterCriteria(column)`](https://docs.univer.ai/zh-TW/reference/facade/filter.md#removecolumnfiltercriteria) 方法移除指定列的篩選條件。 * [`FFilter.removeFilterCriteria()`](https://docs.univer.ai/zh-TW/reference/facade/filter.md#removefiltercriteria) 方法移除所有列的篩選條件。 ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() // 設定 C1:F10 範圍的值 const fRange = fWorksheet.getRange('C1:F10') fRange.setValues([ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8], [6, 7, 8, 9], [7, 8, 9, 10], [8, 9, 10, 11], [9, 10, 11, 12], [10, 11, 12, 13], ]) // 建立 C1:F10 範圍的篩選器 let fFilter = fRange.createFilter() // 如果篩選器已經存在，則移除它並建立一個新的篩選器 if (!fFilter) { fRange.getFilter().remove() fFilter = fRange.createFilter() } // 設定 C 列的篩選條件，篩選出值不是 1、5、9 的行 const column = fWorksheet.getRange('C:C').getColumn() fFilter.setColumnFilterCriteria(column, { colId: 0, filters: { filters: ['1', '5', '9'], }, }) // 3 秒後清除 C 列的篩選條件 setTimeout(() => { fFilter.removeColumnFilterCriteria(column) // 或者使用 fFilter.removeFilterCriteria() 移除所有列的篩選條件 }, 3000) ``` ### 獲取過濾掉的行 [`FFilter.getFilteredOutRows()`](https://docs.univer.ai/zh-TW/reference/facade/filter.md#getfilteredoutrows) 方法返回一個陣列，包含被篩選掉的行的索引。 ```typescript const fWorkbook = univerAPI.getActiveWorkbook() const fWorksheet = fWorkbook.getActiveSheet() // 設定一些 C1:F10 範圍的值 const fRange = fWorksheet.getRange('C1:F10') fRange.setValues([ [1, 2, 3, 4], [2, 3, 4, 5], [3, 4, 5, 6], [4, 5, 6, 7], [5, 6, 7, 8], [6, 7, 8, 9], [7, 8, 9, 10], [8, 9, 10, 11], [9, 10, 11, 12], [10, 11, 12, 13], ]) // 建立 C1:F10 範圍的篩選器 let fFilter = fRange.createFilter() // 如果篩選器已經存在，則移除它並建立一個新的篩選器 if (!fFilter) { fRange.getFilter().remove() fFilter = fRange.createFilter() } // 設定 C 列的篩選條件，篩選出值不是 1、5、9 的行 const column = fWorksheet.getRange('C:C').getColumn() fFilter.setColumnFilterCriteria(column, { colId: 0, filters: { filters: ['1', '5', '9'], }, }) // 列印被篩選掉的行 fFilter.getFilteredOutRows() // [1, 2, 3, 5, 6, 7, 9] ``` ### 事件監聽 完整事件型別定義，請檢視 [Events](https://docs.univer.ai/zh-TW/reference/facade/events.md)。 `SheetRangeFiltered` 事件在列過濾條件發生改變時觸發。 ```typescript const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeFiltered, (params) => { const { workbook, worksheet, col, criteria } = params }) // 移除事件監聽器，使用 `disposable.dispose()` ``` `SheetBeforeRangeFilter` 事件在列過濾條件發生改變前觸發。 ```typescript const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeFilter, (params) => { const { workbook, worksheet, col, criteria } = params // 取消篩選條件更改操作 params.cancel = true }) // 移除事件監聽器，使用 `disposable.dispose()` ``` `SheetRangeFilterCleared` 事件在清除篩選條件時觸發。 ```typescript const disposable = univerAPI.addEvent(univerAPI.Event.SheetRangeFilterCleared, (params) => { const { workbook, worksheet } = params }) // 移除事件監聽器，使用 `disposable.dispose()` ``` `SheetBeforeRangeFilterClear` 事件在清除篩選條件前觸發。 ```typescript const disposable = univerAPI.addEvent(univerAPI.Event.SheetBeforeRangeFilterClear, (params) => { const { workbook, worksheet } = params // 取消清除篩選條件操作 params.cancel = true }) // 移除事件監聽器，使用 `disposable.dispose()` ```