Class FilterCriteriaBuilder

FilterCriteriaBuilder

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 dessa classe.
  3. Use build() para criar os critérios com as configurações especificadas.

Usos comuns

Ocultar valores em uma página

O exemplo a seguir acessa o filtro existente de uma página e adiciona critérios que ocultam as células na coluna C que contêm "hello" ou "world". Os critérios nesta amostra só podem ser usados com filtros em planilhas Grid, o tipo padrão.
let ss = SpreadsheetApp.getActiveSheet();
let filter = ss.getFilter();
let 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 página DataSource, uma página conectada a um banco de dados, com critérios que mostram apenas células na coluna "Category" que não estão vazias.
// Gets the sheet named "Connected sheet," which is connected to a database.
let sheet = SpreadsheetApp.getActiveSpreadsheet()
                          .getSheetByName("Connected sheet")
                          .asDataSourceSheet();
// Creates criteria that only shows non-empty cells.
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenCellNotEmpty()
                             .build();
// Applies the criteria to the column named "Category."
sheet.addFilter("Category", criteria);

Métodos

MétodoTipo de retornoBreve descrição
build()FilterCriteriaMonta os critérios de filtro usando as configurações que você adiciona ao criador de critérios.
copy()FilterCriteriaBuilderCopia esses critérios de filtro e cria um criador de critérios que você pode aplicar 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 fundo usada como critérios de filtro.
getVisibleForegroundColor()ColorRetorna a cor do primeiro plano usada como critério de filtro.
getVisibleValues()String[]Retorna os valores exibidos pelo filtro da tabela dinâmica.
setHiddenValues(values)FilterCriteriaBuilderDefine os valores a serem ocultados.
setVisibleBackgroundColor(visibleBackgroundColor)FilterCriteriaBuilderDefine a cor do plano de fundo usada como critério de filtro.
setVisibleForegroundColor(visibleForegroundColor)FilterCriteriaBuilderDefine a cor do primeiro plano usada como critério de filtro.
setVisibleValues(values)FilterCriteriaBuilderDefine os valores a serem mostrados em uma tabela dinâmica.
whenCellEmpty()FilterCriteriaBuilderDefine os critérios do filtro para mostrar células vazias.
whenCellNotEmpty()FilterCriteriaBuilderDefine os critérios de filtro para mostrar as células que não estão vazias.
whenDateAfter(date)FilterCriteriaBuilderDefine os critérios de filtro que mostram as células com datas posteriores à data especificada.
whenDateAfter(date)FilterCriteriaBuilderDefine os critérios de filtro que mostram as células com datas posteriores à data relativa especificada.
whenDateBefore(date)FilterCriteriaBuilderDefine os critérios de filtro que mostram as células com datas anteriores à data especificada.
whenDateBefore(date)FilterCriteriaBuilderDefine os critérios de filtro que mostram as células com datas anteriores à data relativa especificada.
whenDateEqualTo(date)FilterCriteriaBuilderDefine os critérios de filtro que mostram as células com datas iguais à data especificada.
whenDateEqualTo(date)FilterCriteriaBuilderDefine os critérios de filtro que mostram as células com datas iguais à data relativa especificada.
whenDateEqualToAny(dates)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com datas iguais a qualquer uma das datas especificadas.
whenDateNotEqualTo(date)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células que não sejam iguais à data especificada.
whenDateNotEqualToAny(dates)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com datas que não são iguais a nenhuma das datas especificadas.
whenFormulaSatisfied(formula)FilterCriteriaBuilderDefine 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)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número que esteja entre dois números especificados ou seja um dos dois.
whenNumberEqualTo(number)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número igual ao especificado.
whenNumberEqualToAny(numbers)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número igual a qualquer um dos números especificados.
whenNumberGreaterThan(number)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número maior que o especificado.
whenNumberGreaterThanOrEqualTo(number)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número maior ou igual ao número especificado.
whenNumberLessThan(number)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número menor que o especificado.
whenNumberLessThanOrEqualTo(number)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número menor ou igual ao número especificado.
whenNumberNotBetween(start, end)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número que não esteja entre os dois números especificados.
whenNumberNotEqualTo(number)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com um número diferente do especificado.
whenNumberNotEqualToAny(numbers)FilterCriteriaBuilderDefine 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)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto que contenha o texto especificado.
whenTextDoesNotContain(text)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto que não contém o texto especificado.
whenTextEndsWith(text)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto que termine com o texto especificado.
whenTextEqualTo(text)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto igual ao texto especificado.
whenTextEqualToAny(texts)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto igual a qualquer um dos valores de texto especificados.
whenTextNotEqualTo(text)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto diferente do texto especificado.
whenTextNotEqualToAny(texts)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto diferente de nenhum dos valores especificados.
whenTextStartsWith(text)FilterCriteriaBuilderDefine os critérios de filtro para mostrar células com texto que comece com o texto especificado.
withCriteria(criteria, args)FilterCriteriaBuilderDefine os critérios de filtro como 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 que você adiciona ao criador de critérios.

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

Retorno

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


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.

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


setHiddenValues(values)

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

Só é possível usar esses critérios para filtros em páginas Grid, o tipo padrão.

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

Parâmetros

NomeTipoDescrição
valuesString[]Lista de valores a serem ocultados.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


setVisibleBackgroundColor(visibleBackgroundColor)

Define a cor do plano de fundo usada como critério de filtro. As células com essa cor de plano de fundo permanecem visíveis. A definição de um critério de filtro de cor de segundo plano remove todos os critérios atuais de filtro de cor desse builder.

Só é possível usar esses critérios para filtros em páginas Grid, o tipo padrão.

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

Parâmetros

NomeTipoDescrição
visibleBackgroundColorColorA cor do plano de fundo a ser definida. A cor precisa ser no estilo RGB. Esse método não oferece suporte a cores de tema.

Retorno

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 de primeiro plano permanecem visíveis. A definição de um critério de filtro de cor em primeiro plano remove todos os critérios atuais de filtro de cor desse builder.

Só é possível usar esses critérios para filtros em páginas Grid, o tipo padrão.

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

Parâmetros

NomeTipoDescrição
visibleForegroundColorColorA cor do primeiro plano a ser definida. A cor precisa ser no estilo RGB. Esse método não oferece suporte a cores de tema.

Retorno

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

Só é possível usar esses critérios 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."
let pivotTable = ss.getPivotTables()[0];
let criteria = SpreadsheetApp.newFilterCriteria()
                             .setVisibleValues(["Northeast", "Southwest"])
                             .build();
pivotTable.addFilter(2, criteria);

Parâmetros

NomeTipoDescrição
valuesString[]Lista de valores a serem exibidos.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenCellEmpty()

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

Você pode usar esses critérios com qualquer tipo de filtro.

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

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenCellNotEmpty()

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

Você pode usar esses critérios com qualquer tipo de filtro.

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

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateAfter(date)

Define os critérios de filtro que mostram as células com datas posteriores à data especificada.

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está filtrando não precisará ser uma data. Se não estiver, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
dateDateA data mais recente a ser ocultada.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateAfter(date)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está filtrando não precisará ser uma data. Se não estiver, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
dateRelativeDateA data relativa mais recente.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateBefore(date)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está filtrando não precisará ser uma data. Se não estiver, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
dateDateA data mais antiga a ser ocultada.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateBefore(date)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está filtrando não precisará ser uma data. Se não estiver, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
dateRelativeDateA data relativa mais antiga a ser ocultada.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateEqualTo(date)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está filtrando não precisará ser uma data. Se não estiver, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
dateDateA data em que os valores das células precisam ser correspondentes.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateEqualTo(date)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará ser uma data. Se os dados não estiverem conectados a um banco de dados, o tipo de dados da coluna que você está filtrando não precisará ser uma data. Se não estiver, você poderá receber resultados inesperados.

// Gets the existing filter on the range.
const ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
let filter = range.getFilter();
// Creates criteria that only shows cells with dates that fall within the past month
// and sets it to column A.
let date = SpreadsheetApp.RelativeDate.PAST_MONTH;
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenDateEqualTo(date)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

NomeTipoDescrição
dateRelativeDateA data relativa em que os valores das células precisam ser correspondentes.

Retorno

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 esses critérios com dados conectados a um banco de dados. Por exemplo, use esses critérios com filtros em uma página DataSource, uma página conectada a um banco de dados ou um DataSourcePivotTable, uma tabela dinâmica criada com base em uma página DataSource.

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

Parâmetros

NomeTipoDescrição
datesDate[]As datas a serem exibidas.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenDateNotEqualTo(date)

Define os critérios de filtro para mostrar células que não sejam iguais à data especificada.

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

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

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

Parâmetros

NomeTipoDescrição
dateDateA data a ser ocultada.

Retorno

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 esses critérios com dados conectados a um banco de dados. Por exemplo, use esses critérios com filtros em uma página DataSource, uma página conectada a um banco de dados ou um DataSourcePivotTable, uma tabela dinâmica criada com base em uma página DataSource.

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

Parâmetros

NomeTipoDescrição
datesDate[]As datas a serem ocultadas.

Retorno

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.

Você só pode usar esses critérios para filtrar dados que não estejam conectados a um banco de dados.

// Gets the existing filter on the sheet.
const ss = SpreadsheetApp.getActiveSheet();
let 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.
let formula = "=B:B<C:C";
let criteria = SpreadsheetApp.newFilterCriteria()
                             .whenFormulaSatisfied(formula)
                             .build();
filter.setColumnFilterCriteria(1, criteria);

Parâmetros

NomeTipoDescrição
formulaStringUma fórmula personalizada que é avaliada como true se a entrada é válida.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenNumberBetween(start, end)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
startNumberO menor número a ser exibido.
endNumberO número mais alto a ser exibido.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenNumberEqualTo(number)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
numberNumberO número a ser exibido.

Retorno

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 esses critérios com dados conectados a um banco de dados. Por exemplo, use esses critérios com filtros em uma página DataSource, uma página conectada a um banco de dados ou um DataSourcePivotTable, uma tabela dinâmica criada com base em uma página DataSource.

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

Parâmetros

NomeTipoDescrição
numbersNumber[]Os números a serem exibidos.

Retorno

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.

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
numberNumberO número mais alto a ser ocultado.

Retorno

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 número especificado.

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
numberNumberO menor número a ser exibido.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenNumberLessThan(number)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
numberNumberO menor número a ser ocultado.

Retorno

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 número especificado.

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
numberNumberO número mais alto a ser exibido.

Retorno

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 esteja entre os dois números especificados.

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
startNumberO número mais baixo é ocultado.
endNumberO número mais alto a ser ocultado.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenNumberNotEqualTo(number)

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

Você pode usar esses critérios com qualquer tipo de filtro. Se você usar esses critérios com dados conectados a um banco de dados, o tipo de dados da coluna que você está filtrando precisará 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á filtrando não precisará ser um número. Se não for, você poderá receber resultados inesperados.

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

Parâmetros

NomeTipoDescrição
numberNumberO número a ser ocultado.

Retorno

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 esses critérios com dados conectados a um banco de dados. Por exemplo, use esses critérios com filtros em uma página DataSource, uma página conectada a um banco de dados ou um DataSourcePivotTable, uma tabela dinâmica criada com base em uma página DataSource.

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

Parâmetros

NomeTipoDescrição
numbersNumber[]Os números a serem ocultados.

Retorno

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.

Você pode usar esses critérios com qualquer tipo de filtro.

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

Parâmetros

NomeTipoDescrição
textStringO texto que a célula precisa conter.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenTextDoesNotContain(text)

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

Você pode usar esses critérios com qualquer tipo de filtro.

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

Parâmetros

NomeTipoDescrição
textStringO texto que a célula não pode conter.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenTextEndsWith(text)

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

Você pode usar esses critérios com qualquer tipo de filtro.

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

Parâmetros

NomeTipoDescrição
textStringTexto que o final do texto da célula precisa conter.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenTextEqualTo(text)

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

Você pode usar esses critérios com qualquer tipo de filtro.

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

Parâmetros

NomeTipoDescrição
textStringO texto que deve ser igual ao texto da célula.

Retorno

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 esses critérios com dados conectados a um banco de dados. Por exemplo, use esses critérios com filtros em uma página DataSource, uma página conectada a um banco de dados ou um DataSourcePivotTable, uma tabela dinâmica criada com base em uma página DataSource.

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

Parâmetros

NomeTipoDescrição
textsString[]Os valores de texto aos quais uma célula precisa ser igual.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenTextNotEqualTo(text)

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

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

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

Parâmetros

NomeTipoDescrição
textStringO texto ao qual o texto da célula não pode ser igual.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenTextNotEqualToAny(texts)

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

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

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

Parâmetros

NomeTipoDescrição
textsString[]Os valores de texto que uma célula não pode igualar.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


whenTextStartsWith(text)

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

Você pode usar esses critérios com qualquer tipo de filtro.

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

Parâmetros

NomeTipoDescrição
textStringTexto que o início do texto da célula precisa conter.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.


withCriteria(criteria, args)

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

Você pode usar esses critérios 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();
let 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."
let filter = ss.getFilter();
let filterCriteria = filter.getColumnFilterCriteria(2);
let criteria = SpreadsheetApp.newFilterCriteria()
    .withCriteria(filterCriteria.getCriteriaType(), filterCriteria.getCriteriaValues())
    .setHiddenValues(["Northwest"])
    .build();
filter.setColumnFilterCriteria(3, criteria);

Parâmetros

NomeTipoDescrição
criteriaBooleanCriteriaO tipo de critério booleano.
argsObject[]Uma matriz de argumentos apropriados ao tipo de critério. O número de argumentos e o tipo correspondem aos métodos when...() correspondentes acima.

Retorno

FilterCriteriaBuilder: este builder, para encadeamento.