本頁面由 Cloud Translation API 翻譯而成。

Class Filter

這個類別可用來修改 Grid 工作表 (預設類型為工作表。格狀工作表是一般工作表，內含未連結至資料庫的資料。

如果工作表中還沒有篩選器，請使用 Range.createFilter() 建立篩選器。

如要使用本課程，您必須先使用 Range.getFilter() 或 Sheet.getFilter() 存取格線工作表篩選器。

常見的使用方式

移除篩選器

下例會針對使用中的工作表取得篩選器並加以移除。

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Removes the filter from the active sheet.
filter.remove();

取得篩選器所套用的範圍

下例會針對使用中的工作表取得篩選器，然後使用 getRange() 方法這個類別記錄篩選器適用的範圍。

let ss = SpreadsheetApp.getActiveSheet();
// Gets the existing filter on the active sheet.
let filter = ss.getFilter();
// Logs the range that the filter applies to in A1 notation.
console.log(filter.getRange().getA1Notation());

方法

方法	傳回類型	簡短說明
`getColumnFilterCriteria(columnPosition)`	`FilterCriteria`	取得指定資料欄的篩選條件；如果資料欄沒有條件，則取得 `null` 套用的篩選器
`getRange()`	`Range`	取得這個篩選器所套用的範圍。
`remove()`	`void`	移除這個篩選器。
`removeColumnFilterCriteria(columnPosition)`	`Filter`	從指定資料欄中移除篩選條件。
`setColumnFilterCriteria(columnPosition, filterCriteria)`	`Filter`	在指定的資料欄上設定篩選條件。
`sort(columnPosition, ascending)`	`Filter`	以指定資料欄排序篩選範圍，並排除第一列 (標題列) 要套用這個篩選器的範圍

內容詳盡的說明文件

`getColumnFilterCriteria(columnPosition)`

取得指定資料欄的篩選條件；如果資料欄沒有條件，則取得 null 套用的篩選器

如要進一步瞭解篩選條件，請將此方法鏈結至 FilterCriteria 類別。

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
  // Gets the filter criteria applied to column B of the active sheet
  // and logs the hidden values.
let filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
console.log(filterCriteria);

參數

名稱	類型	說明
`columnPosition`	`Integer`	資料欄的 1 索引位置。例如，B 欄的索引是 2。

回攻員

FilterCriteria：篩選條件。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`getRange()`

取得這個篩選器所套用的範圍。

// Gets the existing filter on the active sheet.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Logs the range that the filter applies to in A1 notation.
console.log(filter.getRange().getA1Notation());

回攻員

Range：篩選器的範圍。如要使用 A1 標記法取得範圍，請使用 Range.getA1Notation() 鏈結此方法。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`remove()`

移除這個篩選器。

// Removes the filter from the active sheet.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
filter.remove();

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`removeColumnFilterCriteria(columnPosition)`

從指定資料欄中移除篩選條件。

// Removes the filter criteria from column B.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
filter.removeColumnFilterCriteria(2);

參數

名稱	類型	說明
`columnPosition`	`Integer`	資料欄的 1 索引位置。例如，B 欄的索引是 2。

回攻員

Filter：用於鏈結的篩選器。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`setColumnFilterCriteria(columnPosition, filterCriteria)`

在指定的資料欄上設定篩選條件。首先，建立篩選條件建構工具使用 SpreadsheetApp.newFilterCriteria()。然後新增條件至建構工具方法是使用 FilterCriteriaBuilder 類別。建立條件之後，請將其設為這個方法的 filterCriteria 參數。

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Builds the filter criteria to use as a parameter for setColumnFilterCriteria.
const criteria = SpreadsheetApp.newFilterCriteria()
                             .setHiddenValues(["Hello", "World"])
                             .build();
// Sets the filter criteria for column C.
filter.setColumnFilterCriteria(3, criteria);

參數

名稱	類型	說明
`columnPosition`	`Integer`	資料欄的 1 索引位置。例如，B 欄的索引是 2。
`filterCriteria`	`FilterCriteria`	要設定的篩選條件。如果您將條件設為 `null`，系統就會將它設為移除指定資料欄中的篩選條件。您也可以使用 `removeColumnFilterCriteria(columnPosition)`。

回攻員

Filter：用於鏈結的篩選器。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets

`sort(columnPosition, ascending)`

以指定資料欄排序篩選範圍，並排除第一列 (標題列) 要套用這個篩選器的範圍

// Gets the existing filter and sorts it by column B in ascending order.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
filter.sort(2, true);

參數

名稱	類型	說明
`columnPosition`	`Integer`	資料欄的 1 索引位置。例如，B 欄的索引是 2。
`ascending`	`Boolean`	如果設為 `true`，則會以遞增順序排序篩選範圍。如果是 `false`，則會以遞減順序排序篩選的範圍。

回攻員

Filter：用於鏈結的篩選器。

授權

使用這個方法的指令碼需要下列一或多個範圍的授權：

https://www.googleapis.com/auth/spreadsheets.currentonly
https://www.googleapis.com/auth/spreadsheets