Class FilterCriteria

FiltroCritérios

Use essa classe para receber informações sobre os critérios dos filtros ou copiá-los.

Usos comuns

Copiar critérios

O exemplo a seguir extrai o filtro aplicado ao intervalo A1:C20, extrai os critérios aplicados à coluna C e copia os critérios 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);

Conseguir valores ocultos pelo filtro

O exemplo a seguir recebe o filtro que se aplica ao intervalo fornecido 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étodoTipo de retornoBreve descrição
copy()FilterCriteriaBuilderCopia esses critérios de filtro e cria um builder de critérios que pode ser aplicado a outro filtro.
getCriteriaType()BooleanCriteriaRetorna 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()ColorRetorna a cor de plano de fundo usada como critério de filtro.
getVisibleForegroundColor()ColorRetorna a cor de primeiro plano usada como critério de filtro.
getVisibleValues()String[]Retorna os valores mostrados pelo filtro da tabela dinâmica.

Documentação detalhada

copy()

Copia esses critérios de filtro e cria um builder 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 planilha, 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 criador de critérios de filtro com base nestes 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 o tipo enumerado BooleanCriteria.

Esse método é usado com frequência para adicionar critérios de condição booleana a um filtro sem substituir os critérios atuais.

Você pode usar esse método para qualquer tipo de filtro. Se o critério do filtro não for uma condição booleana, ele 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: 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.

Esse método é usado com frequência para adicionar critérios de condição booleana a um filtro sem substituir os critérios atuais.

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

    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 apropriados para o tipo de critério booleano. 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 esse critério com filtros em planilhas Grid, o tipo padrão de planilha. 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 de plano de fundo usada como critério de filtro. As células com essa cor de plano de fundo permanecem visíveis.

Use esse critério com filtros em planilhas Grid, o tipo padrão de planilha. 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: a cor de plano de fundo usada como critério de filtro.

getVisibleForegroundColor()

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

Use esse critério com filtros em planilhas Grid, o tipo padrão de planilha. 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: a cor de primeiro plano usada como critério de filtro.

getVisibleValues()

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

Esse critério é válido 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 da tabela dinâmica mostra.