Class FilterCriteriaBuilder

FiltroCritériosBuilder

Criador de critérios de filtro. Para adicionar critérios a um filtro, faça o seguinte:

1. Crie o builder de critérios usando SpreadsheetApp.newFilterCriteria().
2. Adicione configurações ao builder usando os métodos desta classe.
3. Use build() para montar os critérios com as configurações especificadas.

Usos comuns

Ocultar valores em uma página

O exemplo a seguir recebe o filtro atual de uma planilha e adiciona critérios que ocultam as células na coluna C que contêm "hello" ou "world". Os critérios neste exemplo só podem ser usados com filtros em planilhas Grid, o tipo padrão de planilha.

const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
const criteria = SpreadsheetApp.newFilterCriteria()
                     .setHiddenValues(['hello', 'world'])
                     .build();
filter.setColumnFilterCriteria(3, criteria);

Mostrar apenas células não vazias

O exemplo a seguir adiciona um filtro a uma planilha DataSource, que está conectada a um banco de dados, com critérios que mostram apenas células na coluna "Categoria" que não estão vazias.

// Gets the sheet named "Connected sheet," which is connected to a database.
const sheet = SpreadsheetApp.getActiveSpreadsheet()
                  .getSheetByName('Connected sheet')
                  .asDataSourceSheet();
// Creates criteria that only shows non-empty cells.
const criteria = SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build();
// Applies the criteria to the column named "Category."
sheet.addFilter('Category', criteria);

Métodos

Método	Tipo de retorno	Breve descrição
build()	FilterCriteria	Monta os critérios de filtro usando as configurações adicionadas ao criador de critérios.
copy()	FilterCriteriaBuilder	Copia esses critérios de filtro e cria um builder de critérios que pode ser aplicado 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 plano de fundo usada como critério de filtro.
getVisibleForegroundColor()	Color	Retorna a cor de primeiro plano usada como critério de filtro.
getVisibleValues()	String[]	Retorna os valores mostrados pelo filtro da tabela dinâmica.
setHiddenValues(values)	FilterCriteriaBuilder	Define os valores a serem ocultados.
setVisibleBackgroundColor(visibleBackgroundColor)	FilterCriteriaBuilder	Define a cor de plano de fundo usada como critério de filtro.
setVisibleForegroundColor(visibleForegroundColor)	FilterCriteriaBuilder	Define a cor do primeiro plano usada como critério de filtro.
setVisibleValues(values)	FilterCriteriaBuilder	Define os valores a serem mostrados em uma tabela dinâmica.
whenCellEmpty()	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células vazias.
whenCellNotEmpty()	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células que não estão vazias.
whenDateAfter(date)	FilterCriteriaBuilder	Define um critério de filtro que mostra células com datas posteriores à data especificada.
whenDateAfter(date)	FilterCriteriaBuilder	Define critérios de filtro que mostram células com datas posteriores à data relativa especificada.
whenDateBefore(date)	FilterCriteriaBuilder	Define critérios de filtro que mostram células com datas anteriores à especificada.
whenDateBefore(date)	FilterCriteriaBuilder	Define critérios de filtro que mostram células com datas anteriores à data relativa especificada.
whenDateEqualTo(date)	FilterCriteriaBuilder	Define critérios de filtro que mostram células com datas iguais à especificada.
whenDateEqualTo(date)	FilterCriteriaBuilder	Define critérios de filtro que mostram células com datas iguais à data relativa especificada.
whenDateEqualToAny(dates)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com datas iguais a qualquer uma das datas especificadas.
whenDateNotEqualTo(date)	FilterCriteriaBuilder	Define os critérios do filtro para mostrar as células que não são iguais à data especificada.
whenDateNotEqualToAny(dates)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com datas que não são iguais a nenhuma das datas especificadas.
whenFormulaSatisfied(formula)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com uma fórmula especificada (como =B:B<C:C) que é avaliada como true.
whenNumberBetween(start, end)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número que fica entre dois números especificados ou é um deles.
whenNumberEqualTo(number)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número igual ao especificado.
whenNumberEqualToAny(numbers)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número igual a qualquer um dos números especificados.
whenNumberGreaterThan(number)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número maior que o especificado
whenNumberGreaterThanOrEqualTo(number)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número maior ou igual ao especificado.
whenNumberLessThan(number)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número menor do que o especificado.
whenNumberLessThanOrEqualTo(number)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número menor ou igual ao especificado.
whenNumberNotBetween(start, end)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número que não está entre dois números especificados e não é nenhum deles.
whenNumberNotEqualTo(number)	FilterCriteriaBuilder	Define os critérios do filtro para mostrar células com um número que não é igual ao especificado.
whenNumberNotEqualToAny(numbers)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com um número que não é igual a nenhum dos números especificados.
whenTextContains(text)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto que contenha o texto especificado.
whenTextDoesNotContain(text)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto que não contenha o texto especificado.
whenTextEndsWith(text)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto que termina com o texto especificado.
whenTextEqualTo(text)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto igual ao especificado.
whenTextEqualToAny(texts)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto igual a qualquer um dos valores de texto especificados.
whenTextNotEqualTo(text)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto que não é igual ao especificado.
whenTextNotEqualToAny(texts)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto que não é igual a nenhum dos valores especificados.
whenTextStartsWith(text)	FilterCriteriaBuilder	Define os critérios de filtro para mostrar células com texto que começa com o texto especificado.
withCriteria(criteria, args)	FilterCriteriaBuilder	Define os critérios de filtro para uma condição booleana definida por valores BooleanCriteria, como CELL_EMPTY ou NUMBER_GREATER_THAN.

Documentação detalhada

build()

Monta os critérios de filtro usando as configurações adicionadas ao criador de critérios.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
const criteria = SpreadsheetApp
                     .newFilterCriteria()  // Creates a criteria builder.
                     .whenCellNotEmpty()   // Adds settings to the builder.
                     .build();             // Assembles the criteria.
filter.setColumnFilterCriteria(2, criteria);

Retornar

FilterCriteria: uma representação dos critérios de filtro.

---

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.

• 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 withCriteria(criteria, args).

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

---

setHiddenValues(values)

Define os valores a serem ocultados. Limpa todos os valores visíveis ou ocultos.

Esse critério só pode ser usado para filtros em planilhas Grid, o tipo padrão de planilha.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Sets the values to hide and applies the criteria to column C.
const criteria = SpreadsheetApp.newFilterCriteria()
                     .setHiddenValues(['Hello', 'World'])
                     .build();
filter.setColumnFilterCriteria(3, criteria);

Parâmetros

Nome	Tipo	Descrição
values	String[]	A lista de valores a serem ocultados.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

Gera

Error: se algum dos valores for null.

---

setVisibleBackgroundColor(visibleBackgroundColor)

Define 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. Definir um critério de filtro de cor de plano de fundo remove todos os critérios de filtro de cor atual deste builder.

Esse critério só pode ser usado para filtros em planilhas Grid, o tipo padrão de planilha.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that filters by background color and sets it to column B.
const color = SpreadsheetApp.newColor().setRgbColor('#185ABC').build();
const criteria =
    SpreadsheetApp.newFilterCriteria().setVisibleBackgroundColor(color).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
visibleBackgroundColor	Color	A cor do plano de fundo a ser definida. A cor precisa ser do estilo RGB. Esse método não oferece suporte a cores de tema.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

setVisibleForegroundColor(visibleForegroundColor)

Define a cor do primeiro plano usada como critério de filtro. As células com essa cor do primeiro plano permanecem visíveis. Definir critérios de filtro de cor de primeiro plano remove todos os critérios de filtro de cor atuais deste builder.

Esse critério só pode ser usado para filtros em planilhas Grid, o tipo padrão de planilha.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that filters by foreground color and sets it to column B.
const color = SpreadsheetApp.newColor().setRgbColor('#185ABC').build();
const criteria =
    SpreadsheetApp.newFilterCriteria().setVisibleForegroundColor(color).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
visibleForegroundColor	Color	A cor de primeiro plano a ser definida. A cor precisa ser do estilo RGB. Esse método não oferece suporte a cores de tema.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

setVisibleValues(values)

Define os valores a serem mostrados em uma tabela dinâmica. Limpa todos os valores visíveis ou ocultos.

Só é possível usar esse critério para filtros em tabelas dinâmicas que não estão conectadas a um banco de dados.

// Gets the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
// Gets the first pivot table on the sheet and adds a filter to it that
// sets the visible values to "Northeast" and "Southwest."
const pivotTable = ss.getPivotTables()[0];
const criteria = SpreadsheetApp.newFilterCriteria()
                     .setVisibleValues(['Northeast', 'Southwest'])
                     .build();
pivotTable.addFilter(2, criteria);

Parâmetros

Nome	Tipo	Descrição
values	String[]	A lista de valores a serem mostrados.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

Gera

Error: se algum dos valores for null.

---

whenCellEmpty()

Define os critérios de filtro para mostrar células vazias.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Sets criteria to column B that only shows empty cells.
const criteria = SpreadsheetApp.newFilterCriteria().whenCellEmpty().build();
filter.setColumnFilterCriteria(2, criteria);

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenCellNotEmpty()

Define os critérios de filtro para mostrar células que não estão vazias.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Sets criteria to column B that only shows cells that aren't empty.
const criteria = SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build();
filter.setColumnFilterCriteria(2, criteria);

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateAfter(date)

Define um critério de filtro que mostra células com datas posteriores à data especificada.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser uma data, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates after June 1, 2022
// and sets it to column A.
const date = new Date('June 1, 2022');
const criteria = SpreadsheetApp.newFilterCriteria().whenDateAfter(date).build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
date	Date	A data mais recente a ser oculta.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateAfter(date)

Define critérios de filtro que mostram células com datas posteriores à data relativa especificada. Para ver as opções de data relativa, consulte Tipo enumerado RelativeDate.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser uma data, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates after today's date
// and sets it to column A.

const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateAfter(SpreadsheetApp.RelativeDate.TODAY)
                     .build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
date	RelativeDate	A data relativa mais recente.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateBefore(date)

Define critérios de filtro que mostram células com datas anteriores à especificada.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser uma data, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates before June 1, 2022
// and sets it to column A.
const date = new Date('June 1, 2022');
const criteria =
    SpreadsheetApp.newFilterCriteria().whenDateBefore(date).build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
date	Date	A data mais antiga a ser oculta.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateBefore(date)

Define critérios de filtro que mostram células com datas anteriores à data relativa especificada. Para conferir as opções de data relativa, consulte Tipo enumerado RelativeDate.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser uma data, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates before today's date
// and sets it to column A.

const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateBefore(SpreadsheetApp.RelativeDate.TODAY)
                     .build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
date	RelativeDate	A data relativa mais antiga a ser oculta.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateEqualTo(date)

Define critérios de filtro que mostram células com datas iguais à especificada.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser uma data, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates equal to June 1, 2022
// and sets it to column A.
const date = new Date('June 1, 2022');
const criteria =
    SpreadsheetApp.newFilterCriteria().whenDateEqualTo(date).build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
date	Date	A data que os valores da célula precisam corresponder.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateEqualTo(date)

Define critérios de filtro que mostram células com datas iguais à data relativa especificada. Para conferir as opções de data relativa, consulte Tipo enumerado RelativeDate.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser uma data, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
const filter = range.getFilter();
// Creates criteria that only shows cells with dates that fall within the past
// month and sets it to column A.

const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateEqualTo(SpreadsheetApp.RelativeDate.PAST_MONTH)
                     .build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
date	RelativeDate	A data relativa que os valores da célula precisam corresponder.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateEqualToAny(dates)

Define os critérios de filtro para mostrar células com datas iguais a qualquer uma das datas especificadas.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "date" column that shows cells with any of the below
// dates.
const date1 = new Date('June 1, 2022');
const date2 = new Date('June 2, 2022');
const date3 = new Date('June 3, 2022');
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateEqualToAny([date1, date2, date3])
                     .build();
dataSheet.addFilter('date', criteria);

Parâmetros

Nome	Tipo	Descrição
dates	Date[]	As datas a serem mostradas.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateNotEqualTo(date)

Define os critérios do filtro para mostrar as células que não são iguais à data especificada.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

O tipo de dados da coluna que você está usando para filtrar precisa ser uma data.

// Gets a pivot table that's connected to a database.
const ss =
    SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Pivot Table Sheet');
const dataPivotTable = ss.getDataSourcePivotTables()[0];
// Creates criteria that only shows cells that don't equal June 16, 2022
// and sets it to the "date" column.
const date = new Date('June 16, 2022');
const criteria =
    SpreadsheetApp.newFilterCriteria().whenDateNotEqualTo(date).build();
dataPivotTable.addFilter('date', criteria);

Parâmetros

Nome	Tipo	Descrição
date	Date	A data a ser oculta.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenDateNotEqualToAny(dates)

Define os critérios de filtro para mostrar células com datas que não são iguais a nenhuma das datas especificadas.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "date" column that hides cells with any of the below
// dates.
const date1 = new Date('June 1, 2022');
const date2 = new Date('June 2, 2022');
const date3 = new Date('June 3, 2022');
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenDateNotEqualToAny([date1, date2, date3])
                     .build();
dataSheet.addFilter('date', criteria);

Parâmetros

Nome	Tipo	Descrição
dates	Date[]	As datas a serem ocultadas.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenFormulaSatisfied(formula)

Define os critérios de filtro para mostrar células com uma fórmula especificada (como =B:B<C:C) que é avaliada como true.

Só é possível usar esse critério para filtrar dados que não estão conectados a um banco de dados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows the rows where the value in column B is less than
// the value in column C and sets it to column A.
const formula = '=B:B<C:C';
const criteria =
    SpreadsheetApp.newFilterCriteria().whenFormulaSatisfied(formula).build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
formula	String	Uma fórmula personalizada que é avaliada como true se a entrada for válida.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberBetween(start, end)

Define os critérios de filtro para mostrar células com um número que fica entre dois números especificados ou é um deles.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that only shows cells with numbers that fall between 1-25,
// inclusively, and sets it to column A.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberBetween(1, 25).build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

Nome	Tipo	Descrição
start	Number	O número mais baixo a ser mostrado.
end	Number	O número mais alto a ser mostrado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberEqualTo(number)

Define os critérios de filtro para mostrar células com um número igual ao especificado.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está usando para filtrar não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that only shows cells that are equal to 25 and sets it to
// column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberEqualTo(25).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
number	Number	O número a ser mostrado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberEqualToAny(numbers)

Define os critérios de filtro para mostrar células com um número igual a qualquer um dos números especificados.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "amount" column that only shows cells with the number
// 10, 20, or 30.
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenNumberEqualToAny([10, 20, 30])
                     .build();
dataSheet.addFilter('amount', criteria);

Parâmetros

Nome	Tipo	Descrição
numbers	Number[]	Os números a serem mostrados.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberGreaterThan(number)

Define os critérios de filtro para mostrar células com um número maior que o especificado

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells greater than 10 and sets it to column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberGreaterThan(10).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
number	Number	O número mais alto a ser ocultado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberGreaterThanOrEqualTo(number)

Define os critérios de filtro para mostrar células com um número maior ou igual ao especificado.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells greater than or equal to 10 and sets it to
// column B.
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenNumberGreaterThanOrEqualTo(10)
                     .build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
number	Number	O número mais baixo a ser mostrado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberLessThan(number)

Define os critérios de filtro para mostrar células com um número menor do que o especificado.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells less than 10 and sets it to column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberLessThan(10).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
number	Number	O número mais baixo a ser ocultado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberLessThanOrEqualTo(number)

Define os critérios de filtro para mostrar células com um número menor ou igual ao especificado.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells less than or equal to 10 and sets it to
// column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberLessThanOrEqualTo(10).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
number	Number	O número mais alto a ser mostrado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberNotBetween(start, end)

Define os critérios de filtro para mostrar células com um número que não está entre dois números especificados e não é nenhum deles.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that hides cells with numbers that fall between 1-25,
// inclusively, and sets it to column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberNotBetween(1, 25).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
start	Number	O número mais baixo é oculto.
end	Number	O número mais alto a ser ocultado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberNotEqualTo(number)

Define os critérios do filtro para mostrar células com um número que não é igual ao especificado.

É possível usar esse critério com qualquer tipo de filtro. Se você usar esse critério com dados conectados a um banco de dados, o tipo de dados da coluna por onde você está filtrando precisa ser um número. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna por que você está filtrando não precisa ser um número, mas, se não for, você poderá ter resultados inesperados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that hides cells that are equal to 25 and sets it to column
// B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenNumberNotEqualTo(25).build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
number	Number	O número a ser ocultado.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenNumberNotEqualToAny(numbers)

Define os critérios de filtro para mostrar células com um número que não é igual a nenhum dos números especificados.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "amount" column that hides cells with the number 10, 20,
// or 30.
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenNumberNotEqualToAny([10, 20, 30])
                     .build();
dataSheet.addFilter('amount', criteria);

Parâmetros

Nome	Tipo	Descrição
numbers	Number[]	Os números a serem ocultados.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextContains(text)

Define os critérios de filtro para mostrar células com texto que contenha o texto especificado. O texto não diferencia maiúsculas de minúsculas.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells that contain "Northwest" and sets it to
// column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenTextContains('Northwest').build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
text	String	O texto que a célula precisa conter.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextDoesNotContain(text)

Define os critérios de filtro para mostrar células com texto que não contenha o texto especificado. O texto não diferencia maiúsculas de minúsculas.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that hides cells that contain "Northwest" and sets it to
// column B.
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenTextDoesNotContain('Northwest')
                     .build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
text	String	O texto que a célula não pode conter.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextEndsWith(text)

Define os critérios de filtro para mostrar células com texto que termina com o texto especificado. O texto não diferencia maiúsculas de minúsculas.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells with text that ends with "est" and sets it
// to column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenTextEndsWith('est').build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
text	String	Texto que o final do texto da célula precisa conter.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextEqualTo(text)

Define os critérios de filtro para mostrar células com texto igual ao especificado. O texto não diferencia maiúsculas de minúsculas.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells with text that equals "hello" and sets it
// to column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenTextEqualTo('hello').build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
text	String	O texto que a célula precisa ser igual.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextEqualToAny(texts)

Define os critérios de filtro para mostrar células com texto igual a qualquer um dos valores de texto especificados. O texto não diferencia maiúsculas de minúsculas.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that shows cells with the text "tech"
// or "business."
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenTextEqualToAny(['tech', 'business'])
                     .build();
dataSheet.addFilter('category', criteria);

Parâmetros

Nome	Tipo	Descrição
texts	String[]	Os valores de texto que uma célula precisa ter.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextNotEqualTo(text)

Define os critérios de filtro para mostrar células com texto que não é igual ao especificado. O texto não diferencia maiúsculas de minúsculas.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that hides cells with text equal to
// "tech."
const criteria =
    SpreadsheetApp.newFilterCriteria().whenTextNotEqualTo('tech').build();
dataSheet.addFilter('category', criteria);

Parâmetros

Nome	Tipo	Descrição
text	String	O texto que a célula não pode ser igual.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextNotEqualToAny(texts)

Define os critérios de filtro para mostrar células com texto que não é igual a nenhum dos valores especificados. O texto não diferencia maiúsculas de minúsculas.

Só é possível usar esse critério com dados conectados a um banco de dados. Por exemplo, use esse critério com filtros em uma página DataSource, uma página conectada a um banco de dados ou uma DataSourcePivotTable, uma tabela dinâmica criada a partir de uma página DataSource.

// Gets the sheet that's connected to a database.
const ss = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data Sheet');
const dataSheet = ss.asDataSourceSheet();
// Adds criteria to the "category" column that hides cells with the text "tech"
// or "business."
const criteria = SpreadsheetApp.newFilterCriteria()
                     .whenTextNotEqualToAny(['tech', 'business'])
                     .build();
dataSheet.addFilter('category', criteria);

Parâmetros

Nome	Tipo	Descrição
texts	String[]	Os valores de texto que uma célula não pode ter.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

whenTextStartsWith(text)

Define os critérios de filtro para mostrar células com texto que começa com o texto especificado. O texto não diferencia maiúsculas de minúsculas.

É possível usar esse critério com qualquer tipo de filtro.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Creates criteria that shows cells with text that starts with "pre" and sets
// it to column B.
const criteria =
    SpreadsheetApp.newFilterCriteria().whenTextStartsWith('pre').build();
filter.setColumnFilterCriteria(2, criteria);

Parâmetros

Nome	Tipo	Descrição
text	String	Texto que o início do texto da célula precisa conter.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.

---

withCriteria(criteria, args)

Define os critérios de filtro para uma condição booleana definida por valores BooleanCriteria, como CELL_EMPTY ou NUMBER_GREATER_THAN. Para copiar a condição booleana de critérios existentes, defina os parâmetros para esse método usando getCriteriaType() e getCriteriaValues() em um critério existente.

É possível usar esse critério com qualquer tipo de filtro, mas alguns BooleanCriteria não são aplicáveis a todos os filtros.

// Builds a filter criteria that is based on existing boolean conditions from
// another criteria. Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();
// Gets the existing boolean conditions applied to Column B and adds criteria to
// column C that has the same boolean conditions and additional criteria that
// hides the value, "Northwest."
const filterCriteria = filter.getColumnFilterCriteria(2);
const criteria = SpreadsheetApp.newFilterCriteria()
                     .withCriteria(
                         filterCriteria.getCriteriaType(),
                         filterCriteria.getCriteriaValues(),
                         )
                     .setHiddenValues(['Northwest'])
                     .build();
filter.setColumnFilterCriteria(3, criteria);

Parâmetros

Nome	Tipo	Descrição
criteria	BooleanCriteria	O tipo de critérios booleanos.
args	Object[]	Uma matriz de argumentos apropriados ao tipo de critérios. O número de argumentos e seus tipos correspondem aos métodos when...() correspondentes acima.

Retornar

FilterCriteriaBuilder: este builder, para encadeamento.