Esta página foi traduzida pela API Cloud Translation.

Class FilterCriteria

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

Para criar um novo filtro, consulte as seguintes opções:
- Para páginas, use Range.createFilter().
- Para tabelas dinâmicas, use PivotTable.addFilter(sourceDataColumn, filterCriteria).
- Para planilhas 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 critérios para 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, acessa os critérios aplicados à 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);

Mostrar valores ocultos pelo filtro

A amostra a seguir recebe o filtro que se aplica ao intervalo especificado e registra os valores da coluna B que o filtro oculta.

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 esses critérios 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 de fundo usada como critérios de filtro.
`getVisibleForegroundColor()`	`Color`	Retorna a cor do primeiro plano usada como critério de filtro.
`getVisibleValues()`	`String[]`	Retorna os valores exibidos pelo filtro da tabela dinâmica.

Documentação detalhada

`copy()`

Copia esses critérios 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, pode 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);

Retorno

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 o tipo enumerado BooleanCriteria.

As pessoas costumam usar esse método para adicionar critérios de condição booleana a um filtro sem substituir os critérios atuais.

Para acessar os argumentos dos critérios, use getCriteriaValues().
Para usar o tipo e os valores de critérios ao criar ou modificar 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 uma condição booleana, será retornado 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);

Retorno

BooleanCriteria: o tipo de critérios booleanos, ou null se os critérios não forem uma condição booleana.

`getCriteriaValues()`

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

As pessoas costumam usar esse método para adicionar critérios de condição booleana a um filtro sem substituir os critérios atuais.

Para receber o tipo de critérios booleanos, use getCriteriaType().
Para usar o tipo e os valores dos critérios ao 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);
```
Retorno

Object[]: uma matriz de argumentos apropriados ao tipo de critérios booleanos. O número de argumentos e o tipo deles correspondem ao método when...() correspondente da classe FilterCriteriaBuilder.

`getHiddenValues()`

Retorna os valores que o filtro oculta.

Use estes critérios com filtros em Grid de páginas, o tipo padrão. Retornará 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);

Retorno

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

`getVisibleBackgroundColor()`

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

Use estes critérios com filtros em Grid de páginas, o tipo padrão. Retornará 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);

Retorno

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

`getVisibleForegroundColor()`

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

Use estes critérios com filtros em Grid de páginas, o tipo padrão. Retornará 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);

Retorno

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

`getVisibleValues()`

Retorna os valores exibidos pelo filtro da tabela dinâmica.

Este critério é 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);

Retorno

String[]: uma matriz de valores que o filtro da tabela dinâmica mostra.