Class FilterCriteriaBuilder

FilterCriteriaBuilder

如要在篩選器中新增條件，您必須執行下列操作：

  1. 使用 SpreadsheetApp.newFilterCriteria() 建立條件建構工具。
  2. 使用此類別的方法將設定新增至建構工具。
  3. 使用 build() 根據指定的設定組合條件。

常見的使用方式

隱藏工作表中的值

下例會取得工作表現有的篩選器，並新增用來隱藏儲存格的條件 內含「hello」的 C 欄或「全世界」。這個範例中的條件 Grid 份工作表的篩選器，這是預設的工作表類型。 
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
let criteria = SpreadsheetApp.newFilterCriteria()
                             .setHiddenValues(["hello", "world"])
                             .build();
filter.setColumnFilterCriteria(3, criteria);

只顯示非空白儲存格

下例會在 DataSource 工作表 (也就是 已連結至資料庫，且只有隻顯示「類別」儲存格的條件欄 非空白 
// Gets the sheet named "Connected sheet," which is connected to a database.
let sheet = SpreadsheetApp.getActiveSpreadsheet()
                          .getSheetByName("Connected sheet")
                          .asDataSourceSheet();
// Creates criteria that only shows non-empty cells.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenCellNotEmpty()
                             .build();
// Applies the criteria to the column named "Category."
sheet.addFilter("Category", criteria);

方法

方法傳回類型簡短說明
build()FilterCriteria根據您新增到條件建立工具的設定，組合篩選條件。
copy()FilterCriteriaBuilder複製這個篩選條件，並建立可套用到其他篩選條件的條件建立工具 篩選。
getCriteriaType()BooleanCriteria傳回條件的布林值類型，例如 CELL_EMPTY。
getCriteriaValues()Object[]傳回布林條件的引數陣列。
getHiddenValues()String[]傳回篩選器隱藏的值。
getVisibleBackgroundColor()Color傳回做為篩選條件使用的背景顏色。
getVisibleForegroundColor()Color傳回做為篩選條件使用的前景顏色。
getVisibleValues()String[]傳回資料透視表篩選器顯示的值。
setHiddenValues(values)FilterCriteriaBuilder設定要隱藏的值。
setVisibleBackgroundColor(visibleBackgroundColor)FilterCriteriaBuilder設定做為篩選條件使用的背景顏色。
setVisibleForegroundColor(visibleForegroundColor)FilterCriteriaBuilder設定做為篩選條件使用的前景顏色。
setVisibleValues(values)FilterCriteriaBuilder設定資料透視表顯示的值。
whenCellEmpty()FilterCriteriaBuilder設定篩選條件，顯示空白儲存格。
whenCellNotEmpty()FilterCriteriaBuilder設定篩選條件，讓系統顯示非空白的儲存格。
whenDateAfter(date)FilterCriteriaBuilder設定篩選條件，讓系統顯示日期落在指定日期之後的儲存格。
whenDateAfter(date)FilterCriteriaBuilder設定篩選條件，讓系統顯示日期落在指定相對日期之後的儲存格。
whenDateBefore(date)FilterCriteriaBuilder設定篩選條件，讓系統顯示日期早於指定日期的儲存格。
whenDateBefore(date)FilterCriteriaBuilder設定篩選條件，讓系統顯示日期早於指定相對日期的儲存格。
whenDateEqualTo(date)FilterCriteriaBuilder設定篩選條件，讓系統顯示日期等於指定日期的儲存格。
whenDateEqualTo(date)FilterCriteriaBuilder設定篩選條件，顯示日期等於指定相對日期的儲存格。
whenDateEqualToAny(dates)FilterCriteriaBuilder設定篩選條件，顯示日期等於任一指定日期的儲存格。
whenDateNotEqualTo(date)FilterCriteriaBuilder設定篩選條件，顯示不等於指定日期的儲存格。
whenDateNotEqualToAny(dates)FilterCriteriaBuilder設定篩選條件，顯示日期不等於任何指定日期的儲存格 日期。
whenFormulaSatisfied(formula)FilterCriteriaBuilder設定篩選條件，顯示含有指定公式 (例如 =B:B<C:C) 的儲存格， 的值為 true。
whenNumberBetween(start, end)FilterCriteriaBuilder設定篩選條件，顯示數字介於一個介於 2 或 2 之間的儲存格 指定數字。
whenNumberEqualTo(number)FilterCriteriaBuilder設定篩選條件，顯示數字等於指定數字的儲存格。
whenNumberEqualToAny(numbers)FilterCriteriaBuilder設定篩選條件，顯示數字等於任一指定值的儲存格 數字。
whenNumberGreaterThan(number)FilterCriteriaBuilder設定篩選條件，顯示數值大於指定數字的儲存格
whenNumberGreaterThanOrEqualTo(number)FilterCriteriaBuilder設定篩選條件，顯示數值大於或等於指定值的儲存格 號碼。
whenNumberLessThan(number)FilterCriteriaBuilder設定篩選條件，顯示數值小於指定數字的儲存格。
whenNumberLessThanOrEqualTo(number)FilterCriteriaBuilder設定篩選條件，顯示數值小於或等於指定值的儲存格 號碼。
whenNumberNotBetween(start, end)FilterCriteriaBuilder設定篩選條件，讓系統顯示數值介於指定數字之間的儲存格範圍，以及介於兩者之間的值。2 指定數字。
whenNumberNotEqualTo(number)FilterCriteriaBuilder設定篩選條件，顯示數值不等於指定數字的儲存格。
whenNumberNotEqualToAny(numbers)FilterCriteriaBuilder設定篩選條件，顯示數值與任一指定數量不等的儲存格 數字。
whenTextContains(text)FilterCriteriaBuilder設定篩選條件，顯示含有指定文字的儲存格。
whenTextDoesNotContain(text)FilterCriteriaBuilder設定篩選條件，顯示文字不含指定文字的儲存格。
whenTextEndsWith(text)FilterCriteriaBuilder設定篩選條件，顯示文字結尾為指定文字的儲存格。
whenTextEqualTo(text)FilterCriteriaBuilder設定篩選條件，顯示文字等於指定文字的儲存格。
whenTextEqualToAny(texts)FilterCriteriaBuilder設定篩選條件，顯示文字等於任何指定文字的儲存格 輕鬆分配獎金
whenTextNotEqualTo(text)FilterCriteriaBuilder設定篩選條件，讓系統顯示文字不等於指定文字的儲存格。
whenTextNotEqualToAny(texts)FilterCriteriaBuilder設定篩選條件，顯示文字不等於任何指定值的儲存格 輕鬆分配獎金
whenTextStartsWith(text)FilterCriteriaBuilder設定篩選條件，顯示開頭為指定文字的儲存格。
withCriteria(criteria, args)FilterCriteriaBuilder將篩選條件設為由 BooleanCriteria 值定義的布林值條件，例如： 格式為 CELL_EMPTY 或 NUMBER_GREATER_THAN。

內容詳盡的說明文件

build()

根據您新增到條件建立工具的設定，組合篩選條件。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
let criteria = SpreadsheetApp.newFilterCriteria() // Creates a criteria builder.
                             .whenCellNotEmpty() // Adds settings to the builder.
                             .build();          // Assembles the criteria.
filter.setColumnFilterCriteria(2, criteria);

回攻員

FilterCriteria：篩選條件的表示法。

copy()

複製這個篩選條件，並建立可套用到其他篩選條件的條件建立工具 篩選。

這個方法適用於任何類型的篩選器。使用工作表篩選器時，您可以 將條件複製到另一個資料欄 

let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Makes a copy of the filter criteria applied to column C.
let criteria = filter.getColumnFilterCriteria(3).copy().build();
// Applies the copied criteria to column B. The copied criteria overwrites any existing
// criteria on column B.
filter.setColumnFilterCriteria(2, criteria);

回攻員

FilterCriteriaBuilder：根據這個篩選條件建立的篩選條件建構工具。

getCriteriaType()

傳回條件的布林值類型，例如 CELL_EMPTY。如要瞭解 布林值條件，請參閱 BooleanCriteria 列舉。

使用者通常會使用這個方法在篩選器中加入布林條件條件，而不會將任何取代 現有的條件

這個方法適用於任何類型的篩選器。如果篩選條件不是布林值 條件，會傳回 null。 

let ss = SpreadsheetApp.getActiveSheet();
// Gets the filter on the active sheet.
let filter = ss.getFilter();
// Gets the criteria type and returns a string representing the criteria type object.
let criteriaType = filter.getColumnFilterCriteria(2)
                         .getCriteriaType()
                         .toString();
// Logs the criteria type.
console.log(criteriaType);

回攻員

BooleanCriteria：布林條件的類型；如果條件不是布林值，則傳回 null 值。

getCriteriaValues()

傳回布林條件的引數陣列。部分佈林條件類型沒有 並傳回空陣列，例如 CELL_NOT_EMPTY。

使用者通常會使用這個方法在篩選器中加入布林條件條件，而不會將任何取代 現有的條件

  • 如要取得布林條件類型，請使用 getCriteriaType()。
  • 如要使用條件類型和條件值建立或修改篩選條件，請參閱 withCriteria(criteria, args)。

    這個方法適用於任何類型的篩選器。 

    let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Gets the values of the boolean criteria and logs them. For example, if the boolean
// condition is whenNumberGreaterThan(10), then the logged value is 10.
let criteriaValues = filter.getColumnFilterCriteria(2).getCriteriaValues();
console.log(criteriaValues);

    回攻員

    Object[]：適合佈林值條件類型的引數陣列。引數的數量 而且類型符合 FilterCriteriaBuilder 類別的對應 when...() 方法。

getHiddenValues()

傳回篩選器隱藏的值。

您可以在 Grid 工作表 (預設類型的工作表) 中搭配使用這項條件和篩選器。 如果您呼叫這個方法為其他類型的篩選器，會傳回 null。 

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Gets the filter criteria applied to column B, then gets the hidden values.
let filterCriteria = filter.getColumnFilterCriteria(2).getHiddenValues();
// Logs the hidden values.
console.log(filterCriteria);

回攻員

String[]：篩選器隱藏的值陣列。

getVisibleBackgroundColor()

傳回做為篩選條件使用的背景顏色。保持套用這個背景顏色的儲存格 顯示。

您可以在 Grid 工作表 (預設類型的工作表) 中搭配使用這項條件和篩選器。 如果您呼叫這個方法為其他類型的篩選器，會傳回 null。 

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Logs the background color that column B is filtered by as a hexadecimal string.
let filter = range.getFilter();
let color = filter.getColumnFilterCriteria(2)
                  .getVisibleBackgroundColor()
                  .asRgbColor()
                  .asHexString();
console.log(color);

回攻員

Color：當做篩選條件的背景顏色。

getVisibleForegroundColor()

傳回做為篩選條件使用的前景顏色。保留這個前景顏色的儲存格 顯示。

您可以在 Grid 工作表 (預設類型的工作表) 中搭配使用這項條件和篩選器。 如果您呼叫這個方法為其他類型的篩選器，會傳回 null。 

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Logs the foreground color that column B is filtered by as a hexadecimal string.
let filter = range.getFilter();
let color = filter.getColumnFilterCriteria(2)
                  .getVisibleForegroundColor()
                  .asRgbColor()
                  .asHexString();
console.log(color);

回攻員

Color：當做篩選條件的前景顏色。

getVisibleValues()

傳回資料透視表篩選器顯示的值。

這項條件僅適用於未連結到資料庫的資料透視表篩選器。 為其他類型的篩選器傳回空白陣列。 

let ss = SpreadsheetApp.getActiveSheet();
// Gets the first pivot table on the sheet, then gets the visible values of its first filter.
pivotTable = ss.getPivotTables()[0];
pivotFilterValues = pivotTable.getFilters()[0].getFilterCriteria().getVisibleValues();
// Logs the visible values.
console.log(pivotFilterValues);

回攻員

String[]：資料透視表篩選器顯示的值陣列。

setHiddenValues(values)

設定要隱藏的值。清除任何現有的可見或隱藏值。

你只能針對 Grid 份工作表 (預設) 篩選這個條件 工作表類型 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Sets the values to hide and applies the criteria to column C.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .setHiddenValues(["Hello", "World"])
                             .build();
filter.setColumnFilterCriteria(3, criteria);

參數

名稱類型說明
valuesString[]要隱藏的值清單。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

擲回

Error - 如果任一值為 null。

setVisibleBackgroundColor(visibleBackgroundColor)

設定做為篩選條件使用的背景顏色。保持套用這個背景顏色的儲存格 顯示。設定背景顏色篩選條件後，系統會移除所有目前的色彩篩選條件 使用這個建構工具進行切換

你只能針對 Grid 份工作表 (預設) 篩選這個條件 工作表類型 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that filters by background color and sets it to column B.
let color = SpreadsheetApp.newColor().setRgbColor("#185ABC").build();
let criteria = SpreadsheetApp.newFilterCriteria()
                             .setVisibleBackgroundColor(color)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
visibleBackgroundColorColor要設定的背景顏色。顏色必須是 RGB 樣式 顏色。這個方法不支援主題顏色。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

setVisibleForegroundColor(visibleForegroundColor)

設定做為篩選條件使用的前景顏色。保留這個前景顏色的儲存格 顯示。設定前景顏色篩選條件時，系統會移除所有目前的色彩篩選條件 使用這個建構工具進行切換

你只能針對 Grid 份工作表 (預設) 篩選這個條件 工作表類型 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that filters by foreground color and sets it to column B.
let color = SpreadsheetApp.newColor().setRgbColor("#185ABC").build();
let criteria = SpreadsheetApp.newFilterCriteria()
                             .setVisibleForegroundColor(color)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
visibleForegroundColorColor要設定的前景顏色。顏色必須是 RGB 樣式 顏色。這個方法不支援主題顏色。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

setVisibleValues(values)

設定資料透視表顯示的值。清除任何現有的可見或隱藏值。

您只能在未連結資料透視表的資料透視表中使用這個條件 資料庫 

// Gets the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
// Gets the first pivot table on the sheet and adds a filter to it that
// sets the visible values to "Northeast" and "Southwest."
let pivotTable = ss.getPivotTables()[0];
let criteria = SpreadsheetApp.newFilterCriteria()
                             .setVisibleValues(["Northeast", "Southwest"])
                             .build();
pivotTable.addFilter(2, criteria);

參數

名稱類型說明
valuesString[]要顯示的值清單。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

擲回

Error - 如果任一值為 null。

whenCellEmpty()

設定篩選條件，顯示空白儲存格。

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Sets criteria to column B that only shows empty cells.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenCellEmpty()
                             .build();
filter.setColumnFilterCriteria(2, criteria);

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenCellNotEmpty()

設定篩選條件，讓系統顯示非空白的儲存格。

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Sets criteria to column B that only shows cells that aren't empty.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenCellNotEmpty()
                             .build();
filter.setColumnFilterCriteria(2, criteria);

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateAfter(date)

設定篩選條件，讓系統顯示日期落在指定日期之後的儲存格。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 資料欄類型，必須是日期做為篩選依據的資料欄資料類型。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是日期，否則可能會發生非預期的結果。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates after June 1, 2022
// and sets it to column A.
let date = new Date("June 1, 2022");
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateAfter(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
dateDate要隱藏的最晚日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateAfter(date)

設定篩選條件，讓系統顯示日期落在指定相對日期之後的儲存格。目的地： 查看相對日期選項，請參閱列舉 RelativeDate。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 資料欄類型，必須是日期做為篩選依據的資料欄資料類型。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是日期，否則可能會發生非預期的結果。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates after today's date
// and sets it to column A.
let date = SpreadsheetApp.RelativeDate.TODAY;
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateAfter(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
dateRelativeDate最新的相對日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateBefore(date)

設定篩選條件，讓系統顯示日期早於指定日期的儲存格。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 資料欄類型，必須是日期做為篩選依據的資料欄資料類型。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是日期，否則可能會發生非預期的結果。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates before June 1, 2022
// and sets it to column A.
let date = new Date("June 1, 2022");
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateBefore(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
dateDate要隱藏的最早日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateBefore(date)

設定篩選條件，讓系統顯示日期早於指定相對日期的儲存格。 如要查看相對日期選項，請參閱列舉 RelativeDate。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 資料欄類型，必須是日期做為篩選依據的資料欄資料類型。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是日期，否則可能會發生非預期的結果。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates before today's date
// and sets it to column A.
let date = SpreadsheetApp.RelativeDate.TODAY;
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateBefore(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
dateRelativeDate要隱藏的最早相對日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateEqualTo(date)

設定篩選條件，讓系統顯示日期等於指定日期的儲存格。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 資料欄類型，必須是日期做為篩選依據的資料欄資料類型。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是日期，否則可能會發生非預期的結果。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates equal to June 1, 2022
// and sets it to column A.
let date = new Date("June 1, 2022");
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateEqualTo(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
dateDate儲存格值必須符合的日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateEqualTo(date)

設定篩選條件，顯示日期等於指定相對日期的儲存格。 如要查看相對日期選項，請參閱列舉 RelativeDate。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 資料欄類型，必須是日期做為篩選依據的資料欄資料類型。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是日期，否則可能會發生非預期的結果。 

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates that fall within the past month
// and sets it to column A.
let date = SpreadsheetApp.RelativeDate.PAST_MONTH;
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateEqualTo(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
dateRelativeDate儲存格值必須符合的相對日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateEqualToAny(dates)

設定篩選條件，顯示日期等於任一指定日期的儲存格。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "date" column that shows cells with any of the below dates.
let date1 = new Date("June 1, 2022");
let date2 = new Date("June 2, 2022");
let date3 = new Date("June 3, 2022");
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateEqualToAny([date1, date2, date3])
                             .build();
dataSheet.addFilter("date", criteria);

參數

名稱類型說明
datesDate[]要顯示的日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateNotEqualTo(date)

設定篩選條件，顯示不等於指定日期的儲存格。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。

您要篩選的資料欄資料類型必須是日期。 

// Gets a pivot table that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Pivot Table Sheet");
let dataPivotTable = ss.getDataSourcePivotTables()[0];
// Creates criteria that only shows cells that don't equal June 16, 2022
// and sets it to the "date" column.
let date = new Date("June 16, 2022");
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateNotEqualTo(date)
                             .build();
dataPivotTable.addFilter("date", criteria);

參數

名稱類型說明
dateDate要隱藏的日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenDateNotEqualToAny(dates)

設定篩選條件，顯示日期不等於任何指定日期的儲存格 日期。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "date" column that hides cells with any of the below dates.
let date1 = new Date("June 1, 2022");
let date2 = new Date("June 2, 2022");
let date3 = new Date("June 3, 2022");
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateNotEqualToAny([date1, date2, date3])
                             .build();
dataSheet.addFilter("date", criteria);

參數

名稱類型說明
datesDate[]要隱藏的日期。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenFormulaSatisfied(formula)

設定篩選條件，顯示含有指定公式 (例如 =B:B<C:C) 的儲存格， 的值為 true。

您只能使用這項條件來篩選未連線至資料庫的資料。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows the rows where the value in column B is less than the value in
// column C and sets it to column A.
let formula = "=B:B<C:C";
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenFormulaSatisfied(formula)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
formulaString如果輸入有效，系統評估為 true 的自訂公式。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberBetween(start, end)

設定篩選條件，顯示數字介於一個介於 2 或 2 之間的儲存格 指定數字。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that only shows cells with numbers that fall between 1-25, inclusively,
// and sets it to column A.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberBetween(1, 25)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
startNumber要顯示的最小值。
endNumber要顯示的最大值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberEqualTo(number)

設定篩選條件，顯示數字等於指定數字的儲存格。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that only shows cells that are equal to 25 and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberEqualTo(25)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
numberNumber要顯示的數字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberEqualToAny(numbers)

設定篩選條件，顯示數字等於任一指定值的儲存格 數字。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "amount" column that only shows cells with the number 10, 20, or 30.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberEqualToAny([10,20,30])
                             .build();
dataSheet.addFilter("amount", criteria);

參數

名稱類型說明
numbersNumber[]要顯示的數字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberGreaterThan(number)

設定篩選條件，顯示數值大於指定數字的儲存格

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells greater than 10 and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberGreaterThan(10)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
numberNumber要隱藏的最大數值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberGreaterThanOrEqualTo(number)

設定篩選條件，顯示數值大於或等於指定值的儲存格 號碼。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells greater than or equal to 10 and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberGreaterThanOrEqualTo(10)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
numberNumber要顯示的最小值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberLessThan(number)

設定篩選條件，顯示數值小於指定數字的儲存格。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells less than 10 and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberLessThan(10)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
numberNumber要隱藏的最低數字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberLessThanOrEqualTo(number)

設定篩選條件，顯示數值小於或等於指定值的儲存格 號碼。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells less than or equal to 10 and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberLessThanOrEqualTo(10)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
numberNumber要顯示的最大值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberNotBetween(start, end)

設定篩選條件，讓系統顯示數值介於指定數字之間的儲存格範圍，以及介於兩者之間的值。2 指定數字。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that hides cells with numbers that fall between 1-25, inclusively,
// and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberNotBetween(1, 25)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
startNumber隱藏的最小數字。
endNumber要隱藏的最大數值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberNotEqualTo(number)

設定篩選條件，顯示數值不等於指定數字的儲存格。

您可以使用這個條件搭配任何類型的篩選器。您使用這項條件時的資料 您要做為篩選依據的資料欄資料類型必須是數字。如果 資料未連結至資料庫，用於篩選的資料欄資料類型無法 必須是數字，否則可能會導致非預期的結果。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that hides cells that are equal to 25 and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberNotEqualTo(25)
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
numberNumber要隱藏的數字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenNumberNotEqualToAny(numbers)

設定篩選條件，顯示數字不等於任一指定數量的儲存格 數字。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "amount" column that hides cells with the number 10, 20, or 30.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenNumberNotEqualToAny([10,20,30])
                             .build();
dataSheet.addFilter("amount", criteria);

參數

名稱類型說明
numbersNumber[]要隱藏的數字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextContains(text)

設定篩選條件，顯示含有指定文字的儲存格。文字 沒有大小寫之分

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells that contain "Northwest" and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextContains("Northwest")
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
textString儲存格必須包含的文字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextDoesNotContain(text)

設定篩選條件，顯示文字不含指定文字的儲存格。 文字不區分大小寫

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that hides cells that contain "Northwest" and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextDoesNotContain("Northwest")
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
textString儲存格不得包含的文字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextEndsWith(text)

設定篩選條件，顯示文字結尾為指定文字的儲存格。文字 沒有大小寫之分

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells with text that ends with "est" and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextEndsWith("est")
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
textString儲存格文字結尾必須包含的文字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextEqualTo(text)

設定篩選條件，顯示文字等於指定文字的儲存格。文字 沒有大小寫之分

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells with text that equals "hello" and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextEqualTo("hello")
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
textString儲存格中的文字必須相等。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextEqualToAny(texts)

設定篩選條件，顯示文字等於任何指定文字的儲存格 輕鬆分配獎金文字不區分大小寫。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that shows cells with the text "tech" or "business."
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextEqualToAny(["tech","business"])
                             .build();
dataSheet.addFilter("category", criteria);

參數

名稱類型說明
textsString[]儲存格必須相等的文字值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextNotEqualTo(text)

設定篩選條件，讓系統顯示文字不等於指定文字的儲存格。 不區分大小寫

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that hides cells with text equal to "tech."
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextNotEqualTo("tech")
                             .build();
dataSheet.addFilter("category", criteria);

參數

名稱類型說明
textString儲存格中的文字不得相等。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextNotEqualToAny(texts)

設定篩選條件，顯示文字不等於任何指定值的儲存格 輕鬆分配獎金文字不區分大小寫。

這個條件只能用於連線至資料庫的資料。舉例來說，您可以使用這個 條件核對 DataSource 工作表，也就是連結至某個試算表的 資料庫或 DataSourcePivotTable，也就是透過 DataSource 工作表建立的資料透視表。 

// Gets the sheet that's connected to a database.
let ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data Sheet");
let dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that hides cells with the text "tech" or "business."
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextNotEqualToAny(["tech","business"])
                             .build();
dataSheet.addFilter("category", criteria);

參數

名稱類型說明
textsString[]儲存格不等於文字值。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

whenTextStartsWith(text)

設定篩選條件，顯示開頭為指定文字的儲存格。文字 沒有大小寫之分

您可以使用這個條件搭配任何類型的篩選器。 

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Creates criteria that shows cells with text that starts with "pre" and sets it to column B.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenTextStartsWith("pre")
                             .build();
filter.setColumnFilterCriteria(2, criteria);

參數

名稱類型說明
textString儲存格文字開頭必須包含的文字。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。

withCriteria(criteria, args)

將篩選條件設為由 BooleanCriteria 值定義的布林值條件，例如： 格式為 CELL_EMPTY 或 NUMBER_GREATER_THAN。如何複製布林值條件 請使用 getCriteriaType() 和 getCriteriaValues()，定義這個方法的參數 現有的條件

您可以搭配任何類型的篩選器使用這項條件，但部分BooleanCriteria 適用於所有篩選器 

// Builds a filter criteria that is based on existing boolean conditions from another criteria.
// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
// Gets the existing boolean conditions applied to Column B and adds criteria to column C that
// has the same boolean conditions and additional criteria that hides the value, "Northwest."
let filter = ss.getFilter();
let filterCriteria = filter.getColumnFilterCriteria(2);
let criteria = SpreadsheetApp.newFilterCriteria()
    .withCriteria(filterCriteria.getCriteriaType(), filterCriteria.getCriteriaValues())
    .setHiddenValues(["Northwest"])
    .build();
filter.setColumnFilterCriteria(3, criteria);

參數

名稱類型說明
criteriaBooleanCriteria布林條件的類型。
argsObject[]適合該條件類型的引數陣列；可能會引發 其類型符合上述對應的 when...() 方法。

回攻員

FilterCriteriaBuilder：這個建構工具用於鏈結。