Class FilterCriteria

FilterCriteria

Use essa classe para receber informações ou copiar os critérios de filtros existentes.

• Para criar um 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 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, recebe os critérios aplicados à coluna C e os copia para a coluna 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);

Receber valores ocultos pelo filtro

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

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

Métodos

Método	Tipo de retorno	Breve descrição
copy()	FilterCriteriaBuilder	Copia esses critérios de filtro e cria um builder de critérios que pode ser aplicado a outro filtro.
getCriteriaType()	BooleanCriteria|null	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|null	Retorna a cor do plano de fundo usada como critérios de filtro.
getVisibleForegroundColor()	Color|null	Retorna a cor do primeiro plano usada como critérios de filtro.
getVisibleValues()	String[]	Retorna os valores que o filtro de tabela dinâmica mostra.

Documentação detalhada

copy()

Copia esses critérios de filtro e cria um builder de critérios que pode ser aplicado a outro filtro.

É possível 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.

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

Retornar

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

---

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 booleana a um filtro sem substituir os critérios atuais.

• Para receber os argumentos dos 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).

É possível usar esse método para qualquer tipo de filtro. Se os critérios de filtro não forem uma condição booleana, o método vai retornar 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);

Retornar

BooleanCriteria|null — 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 de critérios para criar ou modificar critérios de filtro, consulte FilterCriteriaBuilder.withCriteria(criteria, args).

  É possível usar esse método para qualquer tipo de filtro.

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

  Retornar

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

---

getHiddenValues()

Retorna os valores que o filtro oculta.

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

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

Retornar

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

---

getVisibleBackgroundColor()

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

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

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

Retornar

Color|null: a cor do plano de fundo usada como critérios de filtro.

---

getVisibleForegroundColor()

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

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

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

Retornar

Color|null: a cor do primeiro plano usada como critérios de filtro.

---

getVisibleValues()

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

Esses critérios são 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.

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

Retornar

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