Como trabalhar com tabelas

A API Google Docs permite editar o conteúdo da tabela. As operações que você pode realizar incluem:

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

As tabelas nos Documentos Google são representadas como um tipo de StructuralElement no documento. Cada tabela contém uma lista de linhas de tabela em que cada linha contém uma lista de células de tabela. Como todos os elementos estruturais, a tabela tem índices de início e final, indicando a posição dela no documento. Consulte a estrutura para mais informações sobre indexação. As propriedades da tabela incluem muitos elementos de estilo, como larguras de coluna e padding.

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

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

Inserir e excluir tabelas

Para adicionar uma nova tabela a um documento, use a InsertTableRequest. Ao inserir uma tabela, é necessário especificar o seguinte:

  • As dimensões da tabela em linhas e colunas.
  • O local para inserir a nova tabela: pode ser um índice em um segmento ou o fim de um segmento. Qualquer um deles precisa incluir o ID da aba especificada.

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 o DeleteContentRangeRequest, especificando um intervalo que cubra toda a tabela.

O exemplo a seguir insere 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(TAB_ID))
                .setRows(3)
                .setColumns(3)));

BatchUpdateDocumentRequest body =
    new BatchUpdateDocumentRequest().setRequests(requests);
BatchUpdateDocumentResponse response =
    docsService.documents().batchUpdate(DOCUMENT_ID, 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': TAB_ID
        }
    },
}
]

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

Este exemplo mostra como excluir a tabela inserida anteriormente:

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(DOCUMENT_ID).setIncludeTabsContent(true).execute();
String tabId = document.getTabs()[0].getTabProperties().getTabId();
DocumentTab documentTab = document.getTabs()[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(DOCUMENT_ID, 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=DOCUMENT_ID, body={'requests': requests}).execute()

Como você exclui uma tabela como conteúdo comum, especificando índices de início e final, é necessário extrair esses índices de algum lugar. O exemplo mostra uma maneira de extrair esses índices do conteúdo do documento.

Como inserir e excluir linhas

Se o documento já tiver uma tabela, a API Documentos Google permite inserir e excluir linhas de tabela. Use a InsertTableRowRequest para inserir linhas acima ou abaixo de uma célula de tabela especificada e a DeleteTableRowRequest para remover uma linha que abrange a localização da célula especificada.

O exemplo a seguir insere texto na primeira célula de uma tabela e adiciona uma linha.

Java

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

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

Python

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

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

Inserir e excluir colunas

Para inserir uma coluna em uma tabela, use a 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 a seguir mostra como inserir uma coluna na tabela 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(TAB_ID))
                        .setRowIndex(0)
                        .setColumnIndex(0))
                .setInsertRight(true)));

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

Python

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

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

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

Como ler conteúdo de células de tabela

Uma célula de tabela contém uma lista de elementos estruturais. 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, você pode inspecionar recursivamente cada elemento, conforme mostrado em Extrair texto.

Como inserir conteúdo em células de tabela

Para gravar em uma célula de tabela, use uma InsertTextRequest em um índice na célula que você quer atualizar. Os índices de tabela são ajustados para considerar o texto atualizado. O mesmo se aplica à exclusão de texto de célula com o DeleteContentRangeRequest.

Como modificar as propriedades da coluna

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

É necessário fornecer o índice inicial da tabela com 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 na tabela, forneça uma lista vazia.

O exemplo a seguir atualiza as larguras das colunas de uma tabela, definindo todas as colunas com 100 pontos de largura e, em seguida, a largura da primeira coluna para 200 pontos:

Java

List<Request> requests = new ArrayList<>();
requests.add(
    new Request()
        .setUpdateTableColumnProperties(
            new UpdateTableColumnPropertiesRequest()
                .setTableStartLocation(
                    new Location()
                        .setIndex(2)
                        .setTabId(TAB_ID))
                .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(TAB_ID))
                .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(DOCUMENT_ID, body).execute();

Python

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

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

Modificar estilos de linha

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

É necessário fornecer o índice inicial da tabela com 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 na tabela, forneça uma lista vazia.

O exemplo a seguir define a altura mínima da linha 3 de 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(TAB_ID))
                .setRowIndices(rowIndices)
                .setTableRowStyle(
                    new TableRowStyle()
                        .setMinRowHeight(
                            new Dimension().setMagnitude(18d).setUnit("PT")))
                .setFields("*")));

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

Python

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

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