此页面由 Cloud Translation API 翻译。

Class FilterCriteria

您可以使用此类获取现有过滤条件的相关信息或复制其条件。

如需创建新的过滤条件，请参阅以下内容：
- 对于工作表，请使用 Range.createFilter()。
- 对于数据透视表，请使用 PivotTable.addFilter(sourceDataColumn, filterCriteria)。
- 对于与数据库关联的工作表，请使用 DataSourceSheet.addFilter(columnName, filterCriteria)。
- 对于与数据库关联的数据透视表，请使用 DataSourcePivotTable.addFilter(columnName, filterCriteria)。
如需为任何类型的过滤条件创建条件，请参阅 SpreadsheetApp.newFilterCriteria() 和 FilterCriteriaBuilder。

常见用途

复制条件

以下示例会获取应用于范围 A1:C20 的过滤条件，获取应用于列 C 的条件，并将条件复制到列 B。

const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Copies the filter criteria applied to column C.
const filter = range.getFilter();
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);

获取被过滤器隐藏的值

以下示例会获取应用于给定范围的过滤条件，并记录过滤条件隐藏的 B 列中的值。

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

方法

方法	返回类型	简介
`copy()`	`FilterCriteriaBuilder`	复制此过滤条件，并创建一个可应用于其他过滤条件的条件构建器。
`getCriteriaType()`	`BooleanCriteria`	返回条件的布尔值类型，例如 `CELL_EMPTY`。
`getCriteriaValues()`	`Object[]`	返回布尔条件的参数数组。
`getHiddenValues()`	`String[]`	返回过滤器隐藏的值。
`getVisibleBackgroundColor()`	`Color`	返回用作过滤条件的背景颜色。
`getVisibleForegroundColor()`	`Color`	返回用作过滤条件的前景颜色。
`getVisibleValues()`	`String[]`	返回数据透视表过滤条件显示的值。

详细文档

`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 枚举。

用户通常使用此方法向过滤条件添加布尔值条件，而不会替换现有条件。

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

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

如需使用条件类型和条件值创建或修改过滤条件，请参阅 FilterCriteriaBuilder.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[] - 数据透视表过滤条件显示的值数组。