Esta página foi traduzida pela API Cloud Translation.

Class FilterCriteria

Use esta classe para consultar informações ou copiar os critérios dos filtros existentes.

Para criar um novo filtro, consulte:
- Para planilhas, use Range.createFilter().
- Para tabelas dinâmicas, use PivotTable.addFilter(sourceDataColumn, filterCriteria).
- Para páginas conectadas a um banco de dados, use DataSourceSheet.addFilter(columnName, filterCriteria).
- Para tabelas dinâmicas conectadas a um banco de dados, use DataSourcePivotTable.addFilter(columnName, filterCriteria).
Para criar os critérios de qualquer tipo de filtro, consulte SpreadsheetApp.newFilterCriteria() e FilterCriteriaBuilder.

Usos comuns

Copiar critérios

O exemplo a seguir recebe o filtro que se aplica ao intervalo A1:C20 e recebe os critérios aplicado à coluna C e copia os critérios para a coluna B.

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

Exibir valores ocultos pelo filtro

O exemplo a seguir recebe o filtro que se aplica ao intervalo especificado e registra os valores do coluna B oculta pelo filtro.

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

Métodos

Método	Tipo de retorno	Breve descrição
`copy()`	`FilterCriteriaBuilder`	Copia esse critério de filtro e cria um criador de critérios que você pode aplicar a outro filtro.
`getCriteriaType()`	`BooleanCriteria`	Retorna o tipo booleano dos critérios, por exemplo, `CELL_EMPTY`.
`getCriteriaValues()`	`Object[]`	Retorna uma matriz de argumentos para critérios booleanos.
`getHiddenValues()`	`String[]`	Retorna os valores que o filtro oculta.
`getVisibleBackgroundColor()`	`Color`	Retorna a cor do plano de fundo usada como critério de filtro.
`getVisibleForegroundColor()`	`Color`	Retorna a cor do primeiro plano usada como um critério de filtro.
`getVisibleValues()`	`String[]`	Retorna os valores que o filtro da tabela dinâmica mostra.

Documentação detalhada

`copy()`

Copia esse critério de filtro e cria um criador de critérios que você pode aplicar a outro filtro.

Você pode usar esse método com qualquer tipo de filtro. Se você estiver usando um filtro de página, poderá copiar os critérios para outra coluna.

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

Retornar

FilterCriteriaBuilder: um criador de critérios de filtro com base nesses critérios de filtro.

`getCriteriaType()`

Retorna o tipo booleano dos critérios, por exemplo, CELL_EMPTY. Para saber mais sobre os tipos de critérios booleanos, consulte a enumeração BooleanCriteria.

As pessoas costumam usar esse método para adicionar critérios de condição booleanos a um filtro sem substituí-los critérios existentes.

Para receber os argumentos dos critérios, use getCriteriaValues().
Para usar o tipo e os valores dos critérios para criar ou modificar os critérios de filtro, consulte FilterCriteriaBuilder.withCriteria(criteria, args):

Você pode usar esse método para qualquer tipo de filtro. Se os critérios de filtro não forem booleanos condição, retorna 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);

Retornar

BooleanCriteria: o tipo de critério booleano ou null se o critério não for booleano condição.

`getCriteriaValues()`

Retorna uma matriz de argumentos para critérios booleanos. Alguns tipos de critérios booleanos não têm e retornam uma matriz vazia, por exemplo, CELL_NOT_EMPTY.

As pessoas costumam usar esse método para adicionar critérios de condição booleanos a um filtro sem substituí-los critérios existentes.

Para receber o tipo de critério booleano, use getCriteriaType().
Para usar o tipo e os valores de critérios para criar ou modificar um critério de filtro, consulte FilterCriteriaBuilder.withCriteria(criteria, args):
Você pode usar esse método para qualquer tipo de filtro.
```
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);
```
Retornar

Object[]: uma matriz de argumentos apropriados para o tipo de critério booleano. O número de argumentos e o tipo deles corresponde ao método when...() da classe FilterCriteriaBuilder.

`getHiddenValues()`

Retorna os valores que o filtro oculta.

Usar estes critérios com filtros em Grid páginas, o tipo padrão de página. Retorna null se você chamar esse método para outros tipos de filtros.

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

Retornar

String[]: uma matriz de valores que o filtro oculta.

`getVisibleBackgroundColor()`

Retorna a cor do plano de fundo usada como critério de filtro. As células com essa cor de plano de fundo permanecem visíveis.

Usar estes critérios com filtros em Grid páginas, o tipo padrão de página. Retorna null se você chamar esse método para outros tipos de filtros.

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

Retornar

Color: a cor do plano de fundo usada como critério de filtro.

`getVisibleForegroundColor()`

Retorna a cor do primeiro plano usada como um critério de filtro. As células com essa cor de primeiro plano permanecem visíveis.

Usar estes critérios com filtros em Grid páginas, o tipo padrão de página. Retorna null se você chamar esse método para outros tipos de filtros.

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

Retornar

Color: a cor do primeiro plano usada como critério de filtro.

`getVisibleValues()`

Retorna os valores que o filtro da tabela dinâmica mostra.

Esse critério serve apenas para filtros em tabelas dinâmicas que não estão conectadas a um banco de dados. Retorna uma matriz vazia para outros tipos de filtros.

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

Retornar

String[]: uma matriz de valores exibidos pelo filtro da tabela dinâmica.