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取得指定欄的篩選條件，如果該欄未套用篩選條件，則為 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);

參數

名稱類型說明
columnPositionInteger資料欄的位置 (從 1 開始)。舉例來說，B 欄的索引是 2。

回攻員

FilterCriteria|null：篩選條件。

授權

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

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

參數

名稱類型說明
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 參數。 

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

參數

名稱類型說明
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.
const ss = SpreadsheetApp.getActiveSheet();
const 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