Web SDK

篩選

篩選功能允許使用者對電子表格中的資料進行篩選，以便快速查詢和分析特定資訊。它支援多種篩選條件和操作，幫助使用者更高效地處理資料。

篩選與排序學習計畫

先篩選關注的記錄，再按學習進度排序。透過記錄 ID 觀察同一筆資料的位置。

記錄 ID課程學習進度
1Sheets
86%
2Docs
100%
3Slides
64%
4Bases
92%
5Boards
48%
6PDFs
78%

可見記錄: 6 / 6

篩選隱藏不符合條件的記錄，排序改變記錄順序。取消篩選後仍可看到全部記錄。

外掛模式

安裝

Shell
pnpm add @univerjs/sheets-filter @univerjs/sheets-filter-ui

使用

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter'import { UniverSheetsFilterUIPlugin } from '@univerjs/sheets-filter-ui'import SheetsFilterUIZhTW from '@univerjs/sheets-filter-ui/locale/zh-TW'import '@univerjs/sheets-filter-ui/lib/index.css'import '@univerjs/sheets-filter/facade'const univer = new Univer({  locale: LocaleType.ZH_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      SheetsFilterUIZhTW,     ),  },})univer.registerPlugin(UniverSheetsFilterPlugin)univer.registerPlugin(UniverSheetsFilterUIPlugin)

外掛與配置

TypeScript
interface IUniverSheetsFilterConfig {  /**   * 是否在篩選面板中顯示篩選器同步開關。   * 這個配置可以在協作場景中使用，允許使用者選擇是否啟用篩選器同步。   * 如果設定為 defaultValue 物件，則會顯示篩選器同步開關，其初始狀態將由 defaultValue 屬性決定。   * @default false   */  enableSyncSwitch?: boolean | { defaultValue: boolean }}

行動裝置支援

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

套件桌面版註冊行動版註冊
@univerjs/sheets-filter-uiUniverSheetsFilterUIPluginUniverSheetsFilterMobileUIPlugin

預設模式

安裝

Shell
pnpm 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'import UniverPresetSheetsFilterZhTW from '@univerjs/preset-sheets-filter/locales/zh-TW'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-filter/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsFilterZhTW,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsFilterPreset(),   ],})

預設與配置

TypeScript
interface IUniverSheetsFilterPresetConfig {  /**   * 是否在篩選面板中顯示篩選器同步開關。   * 這個配置可以在協作場景中使用，允許使用者選擇是否啟用篩選器同步。   * 如果設定為 defaultValue 物件，則會顯示篩選器同步開關，其初始狀態將由 defaultValue 屬性決定。   * @default false   */  enableSyncSwitch?: boolean | { defaultValue: boolean }}

Facade API

完整 Facade API 型別定義，請檢視 FacadeAPI。

引入

外掛模式提示

僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件，無需額外引入。

TypeScript
import '@univerjs/sheets-filter/facade'

獲取篩選器

返回一個 FFilter 物件，若 sheet 沒有篩選器，則返回 null。

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 物件，若 sheet 已經有篩選器，則返回 null。

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() 方法移除篩選器。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()fWorksheet.getFilter()?.remove()

獲取列過濾條件

FFilter.getColumnFilterCriteria(column) 方法返回指定列的篩選條件。

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) 方法設定指定列的篩選條件。

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'],  },})

移除列篩選條件

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() 方法返回一個陣列，包含被篩選掉的行的索引。

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。

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

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.