Tabelas

Este guia descreve como e por que usar a API Google Sheets para criar tabelas nas suas planilhas.

O que é uma tabela?

Com as tabelas, é possível simplificar a criação de dados e reduzir a necessidade de formatar, inserir e atualizar dados várias vezes, aplicando formato e estrutura aos intervalos de dados de maneira automática.

As tabelas têm muitos recursos, como cabeçalhos, rodapés, tipos de coluna, filtros, visualizações, referências e nomes. Saiba mais no anúncio do recurso e aprenda a usar tabelas nas Planilhas.

Você pode usar as tabelas para tarefas como acompanhamento de projetos, planejamento de eventos e gerenciamento de inventário.

Adicionar uma tabela

Para adicionar uma tabela, use o método batchUpdate e forneça uma solicitação addTable. Use essa solicitação para adicionar uma tabela à planilha.

O exemplo a seguir cria uma tabela chamada "Project Tracker" no range especificado com duas colunas definidas. Uma coluna de porcentagem na primeira coluna e um tipo de coluna de menu suspenso na segunda.

{
  "addTable": {
    "table": {
      "name": "Project Tracker",
      "tableId": "123",
      "range": {
        "sheetId": 0,
        "startColumnIndex": 0,
        "endColumnIndex": 5,
        "startRowIndex": 0,
        "endRowIndex": 5,
      },
      "columnProperties": [
        {
          "columnIndex": 0,
          "columnName": "Column 1",
          "columnType": "PERCENT"
        },
        {
          "columnIndex": 1,
          "columnName": "Column 2",
          "columnType": "DROPDOWN",
          "dataValidationRule": {
            "condition": {
              "type": "ONE_OF_LIST",
              "values": [
                {
                  "userEnteredValue": "Not Started"
                },
                {
                  "userEnteredValue": "In Progress"
                },
                {
                  "userEnteredValue": "Complete"
                }
              ]
            }
          }
        }
      ],
    }
  }
}

Tipos de coluna

As tabelas têm tipos de coluna, como numérica, data, menu suspenso, ícone inteligente e caixa de seleção. Os tipos de coluna de classificação e caixa de seleção são preenchidos com os valores padrão 0 e FALSE, respectivamente.

O tipo de coluna "menu suspenso" cria um menu suspenso de ícones. Se um tipo de coluna for definido como menu suspenso, o dataValidationRule da coluna precisará ser definido com uma condição ONE_OF_LIST. Outros tipos de coluna não devem definir o campo `dataValidationRule`.

Atualizar uma tabela

Use o método spreadsheets.batchUpdate e forneça um UpdateTableRequest.

Modificar o tamanho da tabela

Use o método UpdateTableRequest para modificar o range que a tabela precisa para adicionar novas linhas/colunas.

Se você precisar adicionar uma nova linha ou coluna à tabela, use o InsertRangeRequest ou o InsertDimensionRequest

Se você precisar excluir uma linha da tabela, use DeleteRangeRequest. Caso contrário, use DeleteDimensionRequest para excluir uma linha inteira da planilha.

Se você estiver atualizando uma tabela sem rodapé para adicionar um, o range vai aumentar em uma linha. Se você estiver atualizando uma tabela com um rodapé e removendo o rodapé, o range vai diminuir em uma linha.

Anexar valores a uma tabela

Use AppendCellsRequest com tableId para adicionar linhas ao final de uma tabela. Isso anexa os valores à primeira linha livre e reconhece linhas completas e rodapés. Se não houver linhas vazias, isso vai inserir linhas no final da tabela e antes de qualquer rodapé, se aplicável.

Excluir uma tabela

Use o método spreadsheets.batchUpdate e forneça um DeleteTableRequest. Use o DeleteTableRequest para excluir toda a tabela e o conteúdo dela.

Use o DeleteBandingRequest para remover a formatação da tabela, mas manter os dados.

Usar tabelas com outros recursos das Planilhas Google

Outros recursos da API que oferecem suporte a tabelas como dados de apoio incluem filtros, visualizações de filtro e intervalos protegidos.