Trabalhar com tabelas

Este documento explica como trabalhar com tabelas na API Google Docs.

Com a API Docs, é possível editar o conteúdo das tabelas. As operações que você pode realizar incluem:

• Inserir e excluir linhas, colunas ou tabelas inteiras.
• Inserir conteúdo em células da tabela.
• Ler conteúdo de células da tabela.
• Modifique as propriedades da coluna e o estilo das linhas.

As tabelas no Google Docs são representadas como um tipo de StructuralElement no documento. Cada Table contém uma lista de objetos TableRow em que cada linha contém uma lista de objetos TableCell. Como todos os elementos estruturais, a tabela tem índices de início e fim, indicando a posição dela em um documento. As propriedades da tabela incluem muitos elementos de estilo, como largura das colunas e padding.

Exemplo de tabela

O fragmento JSON a seguir mostra uma tabela 2x2 com a maioria dos detalhes removidos:

"table": {
    "columns": 2,
    "rows": 2,
    "tableRows": [
        { "tableCells": [
                {
                    "content": [ { "paragraph": { ...  }, } ],
                },
                {
                    "content": [ { "paragraph": { ... }, } ],
                }
            ],
        },
        {
            "tableCells": [
                {
                    "content": [ { "paragraph": { ... }, } ],
                },
                {
                    "content": [ { "paragraph": { ... }, } ],
                }
            ],
        }
    ]
}

A tabela a seguir mostra os deslocamentos de índice para cada elemento estrutural em uma tabela 2x2, supondo que a tabela comece no índice S e que todas as células estejam vazias (cada uma contendo apenas um único caractere de nova linha \n com um comprimento = 1):

Elemento	Caminho	Índice inicial	Índice final
Tabela	/	S	S + 12
TableRow 0	/rows[0]	S + 1	S + 6
TableCell (0,0)	/rows[0]/cells[0]	S + 2	S + 4
Parágrafo	/rows[0]/cells[0]/p[0]	S + 3	S + 4
TableCell (0,1)	/rows[0]/cells[1]	S + 4	S + 6
Parágrafo	/rows[0]/cells[1]/p[0]	S + 5	S + 6
Linha 1 da tabela	/rows[1]	S + 6	S + 11
TableCell (1,0)	/rows[1]/cells[0]	S + 7	S + 9
Parágrafo	/rows[1]/cells[0]/p[0]	S + 8	S + 9
TableCell (1,1)	/rows[1]/cells[1]	S + 9	S + 11
Parágrafo	/rows[1]/cells[1]/p[0]	S + 10	S + 11

Inserir e excluir tabelas

Para adicionar uma tabela a um documento, use o InsertTableRequest. Ao inserir uma tabela, especifique o seguinte:

• As dimensões da tabela em linhas e colunas.
• O local para inserir a tabela: pode ser um índice em um segmento (como corpo, cabeçalho ou rodapé) ou o final de um segmento. Um deles precisa incluir o ID da guia especificada.

Para inserir uma tabela no final do corpo, especifique o objeto EndOfSegmentLocation e deixe segmentId vazio.

Não há um método explícito para excluir tabelas. Para excluir uma tabela de um documento, trate-a como qualquer outro conteúdo: use DeleteContentRangeRequest, especificando um range que abranja toda a tabela.

O exemplo de código a seguir mostra como inserir uma tabela 3x3 no final de um documento vazio:

Java

// Insert a table at the end of the body.
// (An empty or unspecified segmentId field indicates the document's body.)

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setInsertTable(
            new InsertTableRequest()
                .setEndOfSegmentLocation(
                    new EndOfSegmentLocation().setTabId(<var>TAB_ID</var>))
                .setRows(3)
                .setColumns(3)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

# Insert a table at the end of the body.
# (An empty or unspecified segmentId field indicates the document's body.)

requests = [{
    'insertTable': {
        'rows': 3,
        'columns': 3,
        'endOfSegmentLocation': {
          'segmentId': '',
          'tabId': <var>TAB_ID</var>
        }
    },
}
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

O exemplo de código a seguir mostra como excluir uma tabela especificando os índices inicial e final. Este exemplo demonstra como recuperar esses índices do conteúdo do documento.

Java

// Delete a table that was inserted at the start of the body of the first tab.
// (The table is the second element in the body:
//  documentTab.getBody().getContent().get(2).)

Document document = docsService.documents().get(<var>DOCUMENT_ID</var>).setIncludeTabsContent(true).execute();
String tabId = document.getTabs().get(0).getTabProperties().getTabId();
DocumentTab documentTab = document.getTabs().get(0).getDocumentTab();
StructuralElement table = documentTab.getBody().getContent().get(2);

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setDeleteContentRange(
            new DeleteContentRangeRequest()
                .setRange(
                    new Range()
                        .setStartIndex(table.getStartIndex())
                        .setEndIndex(table.getEndIndex())
                        .setTabId(tabId))));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

# Delete a table that was inserted at the start of the body of the first tab.
# (The table is the second element in the body: ['body']['content'][2].)

document = service.documents().get(documentId=DOCUMENT_ID, includeTabsContent=True).execute()
tab_id = document['tabs'][0]['tabProperties']['tabId']
document_tab = document['tabs'][0]['documentTab']
table = document_tab['body']['content'][2]

requests = [{
    'deleteContentRange': {
      'range': {
        'segmentId': '',
        'startIndex': table['startIndex'],
        'endIndex':   table['endIndex'],
        'tabId': tab_id
      }
    },
}
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

Observação: como o exemplo de inserção insere a tabela no início do segmento do corpo, o exemplo de exclusão espera que ela seja o terceiro elemento (indexado em zero). Os dois primeiros elementos são a primeira quebra de seção e o primeiro parágrafo, que estão sempre presentes e não podem ser removidos.

Inserir e excluir linhas

Se o documento já tiver uma tabela, a API Docs permite inserir e excluir linhas. Use o InsertTableRowRequest para inserir linhas antes ou depois de uma célula de tabela especificada e o DeleteTableRowRequest para remover uma linha que abrange o local da célula especificada.

O exemplo de código a seguir mostra como inserir texto na primeira célula de uma tabela existente e adicionar uma linha:

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Hello")
        .setLocation(new Location().setIndex(5).setTabId(<var>TAB_ID</var>))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
        .setTableCellLocation(new TableCellLocation()
                .setTableStartLocation(new Location()
                        .setIndex(2).setTabId(<var>TAB_ID</var>))
                .setRowIndex(1)
                .setColumnIndex(1))
        .setInsertBelow(true)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

requests = [{
      'insertText': {
        'location': {
          'index': 5,
          'tabId': <var>TAB_ID</var>
        },
        'text': 'Hello'
    }
  },
  {
    'insertTableRow': {
        'tableCellLocation': {
            'tableStartLocation': {
                'index': 2,
                'tabId': <var>TAB_ID</var>
            },
            'rowIndex': 1,
            'columnIndex': 1
        },
        'insertBelow': 'true'
    }
  }
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

Inserir e excluir colunas

Para inserir uma coluna em uma tabela, use o comando InsertTableColumnRequest. Você deve especificar o seguinte:

• Uma célula ao lado de onde você quer inserir uma nova coluna.
• Em qual lado (esquerdo ou direito) inserir a nova coluna.

O exemplo de código a seguir mostra como inserir uma coluna na tabela de exemplo 2x2 mostrada anteriormente:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setInsertTableColumn(
            new InsertTableColumnRequest()
                .setTableCellLocation(
                    new TableCellLocation()
                        .setTableStartLocation(
                            new Location().setIndex(2).setTabId(<var>TAB_ID</var>))
                        .setRowIndex(0)
                        .setColumnIndex(0))
                .setInsertRight(true)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

requests = [{
    'insertTableColumn': {
      'tableCellLocation': {
        'tableStartLocation': {
          'segmentId': '',
          'index': 2,
          'tabId': <var>TAB_ID</var>
        },
        'rowIndex': 0,
        'columnIndex': 0
      },
      'insertRight': True
    },
}
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

Para excluir uma coluna, use o DeleteTableColumnRequest. É preciso especificar a localização da célula em uma coluna de destino, como mostrado anteriormente para inserir uma coluna.

Ler conteúdo de células de tabela

Uma célula da tabela contém uma lista de objetos StructuralElement. Cada um desses elementos estruturais pode ser um parágrafo com texto ou outro tipo de estrutura, até mesmo outra tabela. Para ler o conteúdo da tabela, inspecione recursivamente cada elemento, conforme mostrado no exemplo de código Extrair o texto de um documento com a API Docs.

Inserir conteúdo em células da tabela

Para gravar em uma célula da tabela, use um InsertTextRequest definido como o location da célula que você quer atualizar. Os índices da tabela são ajustados para considerar o texto atualizado. O mesmo vale para excluir o texto da célula com o DeleteContentRangeRequest.

Observação: não é possível inserir uma tabela e gravar nas células dela em uma única solicitação batchUpdate. Como a tradução de índice muda automaticamente os índices de inserção subsequentes após a nova tabela, primeiro insira a tabela, recupere o startIndex dela e envie uma solicitação batchUpdate separada usando os índices de coordenadas de célula calculados corretos.

O exemplo de código a seguir mostra como gravar em uma célula de tabela:

Java

List<Request> requests = new ArrayList<>();
requests.add(new Request().setInsertText(new InsertTextRequest()
        .setText("Hello")
        .setLocation(new Location().setIndex(5).setTabId(<var>TAB_ID</var>))));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response = docsService.documents()
        .batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

requests = [{
    'insertText': {
      'location': {
        'index': 5,
        'tabId': <var>TAB_ID</var>
      },
      'text': 'Hello'
    }
}]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

Como modificar propriedades de colunas

O UpdateTableColumnPropertiesRequest permite modificar as propriedades de uma ou mais colunas em uma tabela.

Você precisa fornecer o índice inicial da tabela, além de um objeto TableColumnProperties. Para modificar apenas as colunas selecionadas, inclua uma lista de números de colunas na solicitação. Para modificar todas as colunas da tabela, forneça uma lista vazia.

O exemplo de código a seguir mostra como atualizar as larguras das colunas de uma tabela, definindo todas as colunas com 100 pts de largura e, em seguida, a largura da primeira coluna com 200 pts:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .setColumnIndices(null)
                .setTableColumnProperties(
                    new TableColumnProperties()
                        .setWidthType("FIXED_WIDTH")
                        .setWidth(
                            new Dimension().setMagnitude(100d).setUnit("PT")))
                .setFields("*")));

List<Integer> columnIndices = new ArrayList<>();
columnIndices.add(0);
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .setColumnIndices(columnIndices)
                .setTableColumnProperties(
                    new TableColumnProperties()
                        .setWidthType("FIXED_WIDTH")
                        .setWidth(
                            new Dimension().setMagnitude(200d).setUnit("PT")))
                .setFields("*")));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

requests = [
  {
    'updateTableColumnProperties': {
      'tableStartLocation': {'index': 2, 'tabId': <var>TAB_ID</var>},
      'columnIndices': [],
      'tableColumnProperties': {
        'widthType': 'FIXED_WIDTH',
        'width': {
          'magnitude': 100,
          'unit': 'PT'
        }
      },
      'fields': '*'
    }
  },
  {
    'updateTableColumnProperties': {
      'tableStartLocation': {'index': 2, 'tabId': <var>TAB_ID</var>},
      'columnIndices': [0],
      'tableColumnProperties': {
        'widthType': 'FIXED_WIDTH',
        'width': {
          'magnitude': 200,
          'unit': 'PT'
        }
      },
      'fields': '*'
    }
  }
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

Modificar estilos de linha

O UpdateTableRowStyleRequest permite modificar o estilo de uma ou mais linhas em uma tabela.

Você precisa fornecer o índice inicial da tabela, além de um objeto TableRowStyle. Para modificar apenas as linhas selecionadas, inclua uma lista de números de linha na solicitação. Para modificar todas as linhas da tabela, forneça uma lista vazia.

O exemplo de código a seguir mostra como definir a altura mínima da terceira linha em uma tabela:

Java

List<Integer> rowIndices = new ArrayList<>();
rowIndices.add(3);

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableRowStyle(
            new UpdateTableRowStyleRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(<var>TAB_ID</var>))
                .setRowIndices(rowIndices)
                .setTableRowStyle(
                    new TableRowStyle()
                        .setMinRowHeight(
                            new Dimension().setMagnitude(18d).setUnit("PT")))
                .setFields("*")));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(<var>DOCUMENT_ID</var>, body).execute();

Python

requests = [{
    'updateTableRowStyle': {
        'tableStartLocation': {'index': 2, 'tabId': <var>TAB_ID</var>},
        'rowIndices': [3],
        'tableRowStyle': {
            'minRowHeight': {
              'magnitude': 18,
              'unit': 'PT'
            }
        },
        'fields': '*'
    },
}
]

result = service.documents().batchUpdate(documentId=<var>DOCUMENT_ID</var>, body={'requests': requests}).execute()

Temas relacionados

• Solicitações em lote
• Solicitações e respostas