Os filtros permitem classificar e filtrar os dados que você vê ao visualizar uma planilha. Os filtros não alteram os valores dos dados na planilha. Você pode usar filtros para ocultar ou classificar informações temporariamente. Os dados que correspondem aos critérios de filtro especificados não aparecem enquanto o filtro está ativado. Com as visualizações de filtro, também é possível salvar diferentes filtros nomeados e alternar entre eles sempre que quiser.
Confira a seguir alguns exemplos de casos de uso de filtros:
- classificar dados por uma coluna específica; Por exemplo, classifique registros de usuários pelo sobrenome.
- Oculte dados que atendam a uma condição específica. Por exemplo, oculte todos os registros com mais de 2 anos.
- Oculta dados que correspondem a um determinado valor. Por exemplo, oculte todos os problemas com status "fechado".
Filtro básico
O BasicFilter
de uma planilha é o filtro padrão aplicado sempre que alguém visualiza a planilha. Uma planilha pode ter um filtro básico por planilha. Você pode desativar o filtro básico
limpando-o. Isso remove o filtro e todas as configurações dele da planilha.
Se você quiser reativar o mesmo filtro, precisará definir os critérios outra vez.
Gerenciar o filtro básico
Para definir ou limpar o filtro básico, use o método
spreadsheets.batchUpdate
com o tipo de solicitação adequado:
- Para definir o filtro básico, use o método
SetBasicFilterRequest
. - Para limpar o filtro básico, use o método
ClearBasicFilterRequest
.
Para listar o filtro básico, use o método spreadsheets.get
e defina o parâmetro de URL fields
como sheets/basicFilter
. O exemplo de código spreadsheets.get
a seguir mostra um URL das Planilhas Google com uma máscara de campo:
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/basicFilter)
Visualizações com filtro
Um FilterView
é um filtro nomeado que você pode ativar e desativar sempre que quiser. Uma planilha pode ter diversas visualizações de filtro, mas só é possível aplicar uma de cada vez.
Confira a seguir alguns exemplos de casos de uso de visualizações com filtro:
- Há vários filtros diferentes que você quer alternar ao visualizar os dados.
- Você não tem acesso para editar a uma planilha, mas ainda quer aplicar um filtro. Nesse caso, você pode criar uma visualização de filtro temporária que só fica visível para você.
É recomendável que cada pessoa com quem você compartilha sua planilha visualizem os dados de maneira diferente. Para especificar a visualização com filtro que você quer aplicar, informe
spreadsheetId
efilterViewId
no URL da planilha. Para fazer isso, use ofilterViewId
retornado na resposta ao criar a visualização com filtro.O exemplo de código a seguir mostra um URL das Planilhas Google com uma visualização de filtro:
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0&fvid=FILTER_VIEW_ID
Gerenciar visualizações com filtro
Para criar, duplicar, modificar ou excluir visualizações de filtro, use o método
spreadsheets.batchUpdate
com o tipo de solicitação apropriado:
- Para criar uma visualização com filtro, use o método
AddFilterViewRequest
. - Para fazer uma cópia de uma visualização com filtro, use o método
DuplicateFilterViewRequest
. - Para modificar as propriedades de uma visualização de filtro, use o
método
UpdateFilterViewRequest
. - Para excluir uma visualização de filtro, use o método
DeleteFilterViewRequest
.
Para listar todas as visualizações com filtro, use o método spreadsheets.get
e defina o parâmetro de URL fields
como sheets/filterViews
. O exemplo de código spreadsheets.get
a seguir mostra um URL das Planilhas Google com uma máscara de campo:
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets/filterViews)
Filtrar representação
O exemplo de código a seguir mostra a representação JSON para um
objeto
FilterView
. O objeto
BasicFilter
é o mesmo, mas não tem os campos filterViewId
e title
e não pode usar um intervalo nomeado.
{
"filterViewId": number,
"title": string,
"range": {
object(GridRange)
},
"namedRangeId": string,
"sortSpecs": [
{
object(SortSpec)
}
],
"criteria": {
string: {
object(FilterCriteria)
},
...
}
}
Exemplo
O restante deste documento faz referência ao exemplo de tabela de dados de vendas abaixo:
R | B | C | D | E | F | G | |
1 | Categoria do item | Número do modelo | Custo | Quantidade | Região | Vendedor | Data de envio |
2 | Roda gigante | W-24 | US$ 20,50 | 4 | Oeste | Bete | 01/03/2016 |
3 | Porta | D-01X | US$ 15,00 | 2 | Sul | Amir | 15/03/2016 |
4 | Quadro | FR-0B1 | US$ 34,00 | 8 | Leste | Hannah | 12/03/2016 |
5 | Painel | P-034 | US$ 6,00 | 4 | Norte | Devan | 15/03/2016 |
6 | Painel | P-052 | US$ 11,50 | 7 | Leste | Erik | 16/05/2016 |
7 | Roda gigante | W-24 | US$ 20,50 | 11 | Sul | Sheldon | 30/04/2016 |
8 | Mecanismo | ENG-0161 | US$ 330,00 | 2 | Norte | Jéssica | 02/07/2016 |
Classificar especificações
Um filtro pode ter várias especificações de classificação. Essas especificações determinam
como classificar os dados e são aplicadas na ordem especificada. O atributo
SortSpec.dimensionIndex
especifica o índice de colunas ao qual a classificação precisa ser aplicada.
O exemplo de código a seguir mostra uma especificação de classificação:
[
{
"dimensionIndex": 3,
"sortOrder": "ASCENDING"
},
{
"dimensionIndex": 6,
"sortOrder": "ASCENDING"
}
]
Quando aplicada aos dados de vendas de exemplo, essa especificação classifica primeiro por "Quantidade" e, em seguida, se duas linhas tiverem a mesma quantidade, por "Data de envio".
R | B | C | D | E | F | G | |
1 | Categoria do item | Número do modelo | Custo | Quantidade | Região | Vendedor | Data de envio |
2 | Porta | D-01X | US$ 15,00 | 2 | Sul | Amir | 15/03/2016 |
3 | Mecanismo | ENG-0161 | US$ 330,00 | 2 | Norte | Jéssica | 02/07/2016 |
4 | Roda gigante | W-24 | US$ 20,50 | 4 | Oeste | Bete | 01/03/2016 |
5 | Painel | P-034 | US$ 6,00 | 4 | Norte | Devan | 15/03/2016 |
6 | Painel | P-052 | US$ 11,50 | 7 | Leste | Erik | 16/05/2016 |
7 | Quadro | FR-0B1 | US$ 34,00 | 8 | Leste | Hannah | 12/03/2016 |
8 | Roda gigante | W-24 | US$ 20,50 | 11 | Sul | Sheldon | 30/04/2016 |
Critérios de filtro
O método FilterCriteria
determina quais dados da planilha são mostrados ou ocultos em um filtro básico ou visualização de filtro. Cada critério depende dos valores em uma coluna específica. Forneça os critérios de filtro como um mapa em que as chaves são os índices de coluna e os valores são os critérios.
Para os critérios especificados usando um booleano condition
, a condição precisa ser True
para que os valores sejam exibidos. A condição não substitui hiddenValues
. Se um
valor estiver listado em hiddenValues
, todas as correspondências dele ainda estarão ocultas.
O exemplo de código a seguir mostra um mapa de critérios de filtro:
{
0: {
'hiddenValues': ['Panel']
},
6: {
'condition': {
'type': 'DATE_BEFORE',
'values': {
'userEnteredValue': '4/30/2016'
}
}
}
}
Quando aplicado aos dados de vendas de exemplo, esse critério mostra apenas linhas em que "Categoria do item" não é "Painel" e em que a "Data de envio" é anterior a 30 de abril de 2016.
R | B | C | D | E | F | G | |
1 | Categoria do item | Número do modelo | Custo | Quantidade | Região | Vendedor | Data de envio |
2 | Roda gigante | W-24 | US$ 20,50 | 4 | Oeste | Bete | 01/03/2016 |
3 | Porta | D-01X | US$ 15,00 | 2 | Sul | Amir | 15/03/2016 |
4 | Quadro | FR-0B1 | US$ 34,00 | 8 | Leste | Hannah | 12/03/2016 |
Exemplo
O exemplo de código a seguir mostra como criar uma visualização de filtro, duplicá-la e atualizar a versão duplicada usando os dados de vendas de exemplo acima.