Esta página foi traduzida pela API Cloud Translation.

Class FilterCriteria

Use essa classe para ver informações ou copiar os critérios nos filtros atuais.

Para criar um novo filtro, consulte o seguinte:
- Para páginas, 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 que estão conectadas a um banco de dados, use DataSourcePivotTable.addFilter(columnName, filterCriteria).
Para criar um critério para qualquer tipo de filtro, consulte SpreadsheetApp.newFilterCriteria() e FilterCriteriaBuilder.

Usos comuns

Critérios de cópia

A amostra a seguir busca o filtro que se aplica ao intervalo A1:C20, extrai 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);

Exibir valores ocultos pelo filtro

A amostra a seguir acessa 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 esse critério de filtro e cria um criador de critérios que pode ser aplicado a outro filtro.
`getCriteriaType()`	`BooleanCriteria`	Retorna o tipo booleano dos critérios, como `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ério de filtro.
`getVisibleForegroundColor()`	`Color`	Retorna a cor do primeiro plano usada como um critério do filtro.
`getVisibleValues()`	`String[]`	Retorna os valores exibidos pelo filtro da tabela dinâmica.

Documentação detalhada

`copy()`

Copia esse critério de filtro e cria um criador de critérios que pode ser aplicado 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.

`getCriteriaType()`

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

Geralmente, as pessoas usam esse método para adicionar critérios de condição booleanas a um filtro sem substituir os critérios atuais.

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

Você pode usar esse método com qualquer tipo de filtro. Se o critério do filtro não for uma condição booleana, null será retornado.

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é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.

Geralmente, as pessoas usam esse método para adicionar critérios de condição booleanas a um filtro sem substituir os critérios atuais.

Para ver 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 com 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é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 páginas, o tipo padrão de página. Retornará null se você chamar esse método para outros tipos de 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);

Retornar

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

`getVisibleBackgroundColor()`

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

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

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 de fundo usada como critério de filtro.

`getVisibleForegroundColor()`

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

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

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 de primeiro plano usada como um critério de filtro.

`getVisibleValues()`

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

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

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 mostrada pelo filtro da tabela dinâmica.