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);

參數

名稱類型說明
columnPositionInteger資料欄的 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);

參數

名稱類型說明
columnPositionInteger資料欄的 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);

參數

名稱類型說明
columnPositionInteger資料欄的 1 索引位置。舉例來說，B 欄的索引為 2。
filterCriteriaFilterCriteria要設定的篩選條件。如果將條件設為 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);

參數

名稱類型說明
columnPositionInteger資料欄的 1 索引位置。舉例來說，B 欄的索引為 2。
ascendingBoolean如為 true，則會以遞增順序排序篩選範圍；如果值為 false，則會以遞減順序排序篩選範圍。

回攻員

Filter — 用於鏈結的篩選器。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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