Class FilterCriteriaBuilder

FilterCriteriaBuilder

如需向过滤器添加条件，您必须执行以下操作：

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

常见用途

隐藏工作表中的值

以下示例会获取工作表的现有过滤器，并添加用于隐藏以下单元格的条件： C 列包含“hello”或“世界”此示例中的条件只能用于 过滤 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 之间或其中之一的单元格 。
whenNumberEqualTo(number)	FilterCriteriaBuilder	设置过滤条件，以显示数字等于指定数字的单元格。
whenNumberEqualToAny(numbers)	FilterCriteriaBuilder	设置过滤条件，以显示数字等于任意指定值的单元格 数字。
whenNumberGreaterThan(number)	FilterCriteriaBuilder	设置过滤条件，以显示数值大于指定数值的单元格
whenNumberGreaterThanOrEqualTo(number)	FilterCriteriaBuilder	设置过滤条件，以显示数字大于或等于指定值的单元格 数字。
whenNumberLessThan(number)	FilterCriteriaBuilder	设置过滤条件，以显示数字小于指定数字的单元格。
whenNumberLessThanOrEqualTo(number)	FilterCriteriaBuilder	设置过滤条件，以显示数字小于或等于指定值的单元格 数字。
whenNumberNotBetween(start, end)	FilterCriteriaBuilder	设置过滤条件，以显示数字单元格不介于 2 和 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();
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 枚举。

人们通常使用此方法将布尔条件条件添加到过滤器中，而不将 现有条件

• 如需获取条件的参数，请使用 getCriteriaValues()。
• 要使用条件类型和条件值创建或修改过滤条件，请参阅 withCriteria(criteria, args)。

您可以对任何类型的过滤器使用此方法。如果过滤条件不是布尔值 条件，则返回 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);

参数

名称	类型	说明
values	String[]	要隐藏的值的列表。

返回

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

参数

名称	类型	说明
visibleBackgroundColor	Color	要设置的背景颜色。颜色必须采用 RGB 样式 color 决定。此方法不支持主题颜色。

返回

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

参数

名称	类型	说明
visibleForegroundColor	Color	要设置的前景色。颜色必须采用 RGB 样式 color 决定。此方法不支持主题颜色。

返回

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

参数

名称	类型	说明
values	String[]	要显示的值的列表。

返回

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

参数

名称	类型	说明
date	Date	要隐藏的最新日期。

返回

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

参数

名称	类型	说明
date	RelativeDate	最新的相对日期。

返回

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

参数

名称	类型	说明
date	Date	要隐藏的最早日期。

返回

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

参数

名称	类型	说明
date	RelativeDate	要隐藏的最早的相对日期。

返回

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

参数

名称	类型	说明
date	Date	单元格值必须匹配的日期。

返回

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

参数

名称	类型	说明
date	RelativeDate	单元格值必须匹配的相对日期。

返回

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

参数

名称	类型	说明
dates	Date[]	要显示的日期。

返回

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

参数

名称	类型	说明
date	Date	要隐藏的日期。

返回

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

参数

名称	类型	说明
dates	Date[]	要隐藏的日期。

返回

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

参数

名称	类型	说明
formula	String	计算结果为 true（如果输入有效）的自定义公式。

返回

FilterCriteriaBuilder - 此构建器，用于链接。

---

whenNumberBetween(start, end)

设置过滤条件，以显示数字介于 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);

参数

名称	类型	说明
start	Number	要显示的最小数字。
end	Number	要显示的最大值。

返回

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

参数

名称	类型	说明
number	Number	要显示的数值。

返回

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

参数

名称	类型	说明
numbers	Number[]	要显示的数字。

返回

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

参数

名称	类型	说明
number	Number	要隐藏的最大值。

返回

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

参数

名称	类型	说明
number	Number	要显示的最小数字。

返回

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

参数

名称	类型	说明
number	Number	要隐藏的最小数字。

返回

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

参数

名称	类型	说明
number	Number	要显示的最大值。

返回

FilterCriteriaBuilder - 此构建器，用于链接。

---

whenNumberNotBetween(start, end)

设置过滤条件，以显示数字单元格不介于 2 和 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);

参数

名称	类型	说明
start	Number	隐藏最小值。
end	Number	要隐藏的最大值。

返回

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

参数

名称	类型	说明
number	Number	要隐藏的数值。

返回

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

参数

名称	类型	说明
numbers	Number[]	要隐藏的数字。

返回

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

参数

名称	类型	说明
text	String	单元格必须包含的文本。

返回

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

参数

名称	类型	说明
text	String	单元格中不得包含的文本。

返回

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

参数

名称	类型	说明
text	String	单元格的文本末尾必须包含的文本。

返回

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

参数

名称	类型	说明
text	String	单元格中的文本必须等于的文本。

返回

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

参数

名称	类型	说明
texts	String[]	单元格必须等于的文本值。

返回

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

参数

名称	类型	说明
text	String	单元格中的文本不能相同的文本。

返回

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

参数

名称	类型	说明
texts	String[]	单元格不能相等的文本值。

返回

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

参数

名称	类型	说明
text	String	单元格文本的开头必须包含的文本。

返回

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

参数

名称	类型	说明
criteria	BooleanCriteria	布尔值条件的类型。
args	Object[]	适合条件类型的参数数组；参数数量 其类型与上述相应的 when...() 方法匹配。

返回

FilterCriteriaBuilder - 此构建器，用于链接。