Class Filter

篩選器

使用這個類別修改 Grid 工作表 (工作表的預設類型) 上的現有篩選器。格狀工作表是指未連結至資料庫的一般工作表。

如果工作表中尚未有篩選器，請使用 Range.createFilter() 建立一個。

如要使用這個類別，您必須先使用 Range.getFilter() 或 Sheet.getFilter() 存取格狀工作表篩選器。

常見的使用方式

移除篩選器

以下範例會取得目前工作表上的篩選器並移除。

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

取得篩選器適用的範圍

以下範例會取得有效工作表上的篩選器，然後使用這個類別的 getRange() 方法，記錄篩選器套用的範圍。

const ss = SpreadsheetApp.getActiveSheet();
// Gets the existing filter on the active sheet.
const 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 類別的方法連結。

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

參數

名稱	類型	說明
columnPosition	Integer	資料欄的 1-indexed 位置。例如，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.
const ss = SpreadsheetApp.getActiveSheet();
const 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.
const ss = SpreadsheetApp.getActiveSheet();
const 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.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.removeColumnFilterCriteria(2);

參數

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

回攻員

Filter：用於鏈結的篩選器。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

---

setColumnFilterCriteria(columnPosition, filterCriteria)

設定指定欄的篩選條件。首先，請使用 SpreadsheetApp.newFilterCriteria() 建立篩選條件建構工具。接著，使用 FilterCriteriaBuilder 類別將條件新增至建構工具。建立條件後，請將其設為此方法的 filterCriteria 參數。

const ss = SpreadsheetApp.getActiveSheet();
const 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-indexed 位置。例如，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.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
filter.sort(2, true);

參數

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

回攻員

Filter：用於鏈結的篩選器。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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