Class FilterCriteriaBuilder

篩選器條件建構工具

篩選條件建構工具。如要為篩選器新增條件，請按照下列步驟操作：

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

常見的使用方式

隱藏工作表中的值

以下範例會取得工作表的現有篩選器，並新增條件，隱藏包含「hello」或「world」的 C 欄中儲存格。本範例中的條件只能用於 Grid 工作表 (工作表的預設類型) 的篩選器。
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
const criteria = SpreadsheetApp.newFilterCriteria()
                     .setHiddenValues(['hello', 'world'])
                     .build();
filter.setColumnFilterCriteria(3, criteria);

只顯示非空白儲存格

下列範例會在 DataSource 工作表 (已連結至資料庫) 中新增篩選器，篩選條件為只顯示「Category」欄中非空白的儲存格。
// Gets the sheet named "Connected sheet," which is connected to a database.
const sheet = SpreadsheetApp.getActiveSpreadsheet()
                  .getSheetByName('Connected sheet')
                  .asDataSourceSheet();
// Creates criteria that only shows non-empty cells.
const 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 個指定數字之間，或為其中任一數字的儲存格。
whenNumberEqualTo(number)FilterCriteriaBuilder設定篩選器條件，顯示數字等於指定數字的儲存格。
whenNumberEqualToAny(numbers)FilterCriteriaBuilder設定篩選條件，顯示數字等於任何指定數字的儲存格。
whenNumberGreaterThan(number)FilterCriteriaBuilder設定篩選條件，只顯示數字大於指定數字的儲存格
whenNumberGreaterThanOrEqualTo(number)FilterCriteriaBuilder設定篩選條件，顯示數字大於或等於指定數字的儲存格。
whenNumberLessThan(number)FilterCriteriaBuilder設定篩選器條件，顯示數字小於指定數字的儲存格。
whenNumberLessThanOrEqualTo(number)FilterCriteriaBuilder設定篩選條件，顯示數字小於或等於指定數字的儲存格。
whenNumberNotBetween(start, end)FilterCriteriaBuilder設定篩選條件，顯示儲存格內的數字不介於 2 個指定數字之間，且不等於這 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();
const filter = ss.getFilter();
const criteria = SpreadsheetApp
                     .newFilterCriteria()  // Creates a criteria builder.
                     .whenCellNotEmpty()   // Adds settings to the builder.
                     .build();             // Assembles the criteria.
filter.setColumnFilterCriteria(2, criteria);

回攻員

FilterCriteria：篩選條件的表示法。

copy()

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

您可以將這個方法用於任何類型的篩選器。如果您使用工作表篩選器，可以將條件複製到其他欄。

const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Makes a copy of the filter criteria applied to column C.
const 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。

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

回攻員

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

getCriteriaValues()

傳回布林條件的引數陣列。某些布林值條件類型沒有引數，且會傳回空陣列，例如 CELL_NOT_EMPTY。

使用者通常會使用這個方法，在篩選器中新增布林值條件，而不取代現有條件。

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

    您可以將此方法用於任何類型的篩選器。

    const ss = SpreadsheetApp.getActiveSheet();
const 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.
const criteriaValues = filter.getColumnFilterCriteria(2).getCriteriaValues();
console.log(criteriaValues);

    回攻員

    Object[]：適合布林值條件類型的引數陣列。引數的數量和類型，必須與 FilterCriteriaBuilder 類別的對應 when...() 方法相符。

getHiddenValues()

傳回篩除器隱藏的值。

在 Grid 試算表 (預設的試算表類型) 上使用篩選器搭配此條件。如果您針對其他類型的篩選器呼叫此方法，則會傳回 null。

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

回攻員

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

getVisibleBackgroundColor()

傳回用於篩選條件的背景顏色。背景顏色為此顏色的儲存格仍會顯示。

在 Grid 試算表 (預設的試算表類型) 上使用篩選器搭配此條件。如果您針對其他類型的篩選器呼叫此方法，則會傳回 null。

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

回攻員

Color：用於篩選條件的背景顏色。

getVisibleForegroundColor()

傳回用於篩選條件的前景顏色。使用此前景顏色的儲存格仍會顯示。

在 Grid 試算表 (預設的試算表類型) 上使用篩選器搭配此條件。如果您針對其他類型的篩選器呼叫此方法，則會傳回 null。

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

回攻員

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

getVisibleValues()

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

這個條件僅適用於未連結至資料庫的資料透視表篩選器。針對其他類型的篩選器，則傳回空白陣列。

const ss = SpreadsheetApp.getActiveSheet();
// Gets the first pivot table on the sheet, then gets the visible values of its
// first filter.
const pivotTable = ss.getPivotTables()[0];
const 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();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Sets the values to hide and applies the criteria to column C.
const 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();
const filter = ss.getFilter();
// Creates criteria that filters by background color and sets it to column B.
const color = SpreadsheetApp.newColor().setRgbColor('#185ABC').build();
const 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();
const filter = ss.getFilter();
// Creates criteria that filters by foreground color and sets it to column B.
const color = SpreadsheetApp.newColor().setRgbColor('#185ABC').build();
const 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."
const pivotTable = ss.getPivotTables()[0];
const 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();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Sets criteria to column B that only shows empty cells.
const criteria = SpreadsheetApp.newFilterCriteria().whenCellEmpty().build();
filter.setColumnFilterCriteria(2, criteria);

回攻員

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

whenCellNotEmpty()

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

您可以將這個條件套用至任何類型的篩選器。

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

回攻員

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

whenDateAfter(date)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選的資料欄資料類型必須是日期。如果資料未連結至資料庫，篩選的資料欄資料類型不必是日期，但如果不是，可能會產生意外結果。

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

參數

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

回攻員

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

whenDateAfter(date)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選的資料欄資料類型必須是日期。如果資料未連結至資料庫，篩選的資料欄資料類型不必是日期，但如果不是，可能會產生意外結果。

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

const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateAfter(SpreadsheetApp.RelativeDate.TODAY)
                     .build();
filter.setColumnFilterCriteria(1, criteria);

參數

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

回攻員

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

whenDateBefore(date)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選的資料欄資料類型必須是日期。如果資料未連結至資料庫，篩選的資料欄資料類型不必是日期，但如果不是，可能會產生意外結果。

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

參數

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

回攻員

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

whenDateBefore(date)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選的資料欄資料類型必須是日期。如果資料未連結至資料庫，篩選的資料欄資料類型不必是日期，但如果不是，可能會產生意外結果。

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

const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateBefore(SpreadsheetApp.RelativeDate.TODAY)
                     .build();
filter.setColumnFilterCriteria(1, criteria);

參數

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

回攻員

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

whenDateEqualTo(date)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選的資料欄資料類型必須是日期。如果資料未連結至資料庫，篩選的資料欄資料類型不必是日期，但如果不是，可能會產生意外結果。

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

參數

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

回攻員

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

whenDateEqualTo(date)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選的資料欄資料類型必須是日期。如果資料未連結至資料庫，篩選的資料欄資料類型不必是日期，但如果不是，可能會產生意外結果。

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates that fall within the past
// month and sets it to column A.

const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateEqualTo(SpreadsheetApp.RelativeDate.PAST_MONTH)
                     .build();
filter.setColumnFilterCriteria(1, criteria);

參數

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

回攻員

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

whenDateEqualToAny(dates)

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

您只能將這個條件套用至已連結至資料庫的資料。舉例來說，您可以將這項條件與 DataSource 工作表、連結至資料庫的工作表，或是 DataSourcePivotTable (從 DataSource 工作表建立的樞紐分析表) 上的篩選器搭配使用。

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "date" column that shows cells with any of the below
// dates.
const date1 = new Date('June 1, 2022');
const date2 = new Date('June 2, 2022');
const date3 = new Date('June 3, 2022');
const 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.
const ss =
    SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Pivot Table Sheet');
const dataPivotTable = ss.getDataSourcePivotTables()[0];
// Creates criteria that only shows cells that don't equal June 16, 2022
// and sets it to the "date" column.
const date = new Date('June 16, 2022');
const 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.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "date" column that hides cells with any of the below
// dates.
const date1 = new Date('June 1, 2022');
const date2 = new Date('June 2, 2022');
const date3 = new Date('June 3, 2022');
const 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();
const 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.
const formula = '=B:B<C:C';
const criteria =
    SpreadsheetApp.newFilterCriteria().whenFormulaSatisfied(formula).build();
filter.setColumnFilterCriteria(1, criteria);

參數

名稱類型說明
formulaString如果輸入內容有效，這個自訂公式會評估為 true。

回攻員

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

whenNumberBetween(start, end)

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

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選資料欄的資料類型必須是數字。如果資料未連結至資料庫，篩選的資料欄資料類型不必是數字，但如果不是，可能會產生意外結果。

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that only shows cells with numbers that fall between 1-25,
// inclusively, and sets it to column A.
const 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();
const filter = ss.getFilter();
// Creates criteria that only shows cells that are equal to 25 and sets it to
// column B.
const 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.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "amount" column that only shows cells with the number
// 10, 20, or 30.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells greater than 10 and sets it to column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells greater than or equal to 10 and sets it to
// column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells less than 10 and sets it to column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells less than or equal to 10 and sets it to
// column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberLessThanOrEqualTo(10).build();
filter.setColumnFilterCriteria(2, criteria);

參數

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

回攻員

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

whenNumberNotBetween(start, end)

設定篩選條件，顯示儲存格內的數字不介於 2 個指定數字之間，且不等於這 2 個數字。

您可以將這個條件套用至任何類型的篩選器。如果您將這個條件與連結至資料庫的資料一起使用，篩選資料欄的資料類型必須是數字。如果資料未連結至資料庫，篩選的資料欄資料類型不必是數字，但如果不是，可能會產生意外結果。

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that hides cells with numbers that fall between 1-25,
// inclusively, and sets it to column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that hides cells that are equal to 25 and sets it to column
// B.
const 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.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "amount" column that hides cells with the number 10, 20,
// or 30.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells that contain "Northwest" and sets it to
// column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that hides cells that contain "Northwest" and sets it to
// column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells with text that ends with "est" and sets it
// to column B.
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells with text that equals "hello" and sets it
// to column B.
const 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.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that shows cells with the text "tech"
// or "business."
const 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.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that hides cells with text equal to
// "tech."
const 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.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that hides cells with the text "tech"
// or "business."
const 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();
const filter = ss.getFilter();
// Creates criteria that shows cells with text that starts with "pre" and sets
// it to column B.
const 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();
const 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."
const filterCriteria = filter.getColumnFilterCriteria(2);
const criteria = SpreadsheetApp.newFilterCriteria()
                     .withCriteria(
                         filterCriteria.getCriteriaType(),
                         filterCriteria.getCriteriaValues(),
                         )
                     .setHiddenValues(['Northwest'])
                     .build();
filter.setColumnFilterCriteria(3, criteria);

參數

名稱類型說明
criteriaBooleanCriteria布林值條件的類型。
argsObject[]適合條件類型的引數陣列；引數數量和型別與上述對應的 when...() 方法相符。

回攻員

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