Class FilterCriteriaBuilder

FilterCriteriaBuilder

要向过滤器添加条件,您必须执行以下操作:

  1. 使用 SpreadsheetApp.newFilterCriteria() 创建条件构建器。
  2. 使用此类中的方法将设置添加到构建器中。
  3. 使用 build() 根据您指定的设置组合条件。

常见的使用情形

在工作表中隐藏值

以下示例会获取工作表的现有过滤条件,并添加条件来隐藏 C 列中包含“hello”或“world”的单元格。此示例中的条件只能与 Grid 工作表(工作表的默认类型)上的过滤条件一起使用。
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
let 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.
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 个指定数字之间、也不在 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_EMPTYNUMBER_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 - 此构建器,用于链接。


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 - 此构建器,用于链接。


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 个指定数字之间、也不在 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_EMPTYNUMBER_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 - 此构建器,用于链接。