Como trabalhar com tabelas

Com a API Google 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 nos Documentos Google são representadas como um tipo de StructuralElement no documento. Cada tabela contém uma lista de linhas da tabela, em que cada linha contém uma lista de células da tabela. Como todos os elementos estruturais, a tabela tem índices de início e fim, 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 largura das colunas e padding.

O fragmento JSON a seguir mostra uma tabela simples de 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 o InsertTableRequest. Ao inserir uma tabela, especifique 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 final de um segmento. Qualquer uma delas 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 o DeleteContentRangeRequest, especificando um intervalo que abranja 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 correspondente 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 fim), é necessário extrair esses índices de algum lugar. O exemplo mostra uma maneira de extrair esses índices do conteúdo do documento.

O exemplo anterior inseriu a tabela no início do corpo. Portanto, este exemplo espera que ela seja o terceiro elemento (indexação zero). Os dois primeiros elementos são a primeira quebra de seção e o primeiro parágrafo. Eles estão sempre presentes e não podem ser removidos.

Como inserir e excluir linhas

Se o documento já tiver uma tabela, a API Google Docs permitirá inserir e excluir linhas. Use o InsertTableRowRequest para inserir linhas acima ou abaixo de uma célula de tabela especificada e o DeleteTableRowRequest para remover uma linha que abrange o local 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()

Como inserir e excluir colunas

Para inserir uma coluna em uma tabela, use o 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. Você especifica a localização da célula em uma coluna de destino da mesma forma que mostrado anteriormente para inserir uma coluna.

Leitura do conteúdo das células da tabela

Uma célula de tabela contém uma lista de elementos estruturais. Cada um deles 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 em Extrair texto.

Inserir conteúdo em células de tabela

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

Como modificar propriedades de colunas

Com o UpdateTableColumnPropertiesRequest é possível modificar as propriedades de uma ou mais colunas em uma tabela.

É necessário 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 a seguir atualiza 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(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()

Como 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, 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 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()