借助 Google Docs API,您可以修改表格内容。您可以执行的操作包括:
- 插入和删除行、列或整个表格。
- 将内容插入到表格单元格中。
- 读取表格单元格中的内容。
- 修改列属性和行的样式。
Google 文档中的表格在文档中表示为一种 StructuralElement。每个表格都包含一个表格行列表,其中每行都包含一个表格单元格列表。与所有结构元素一样,表格具有开始和结束索引,用于指示表格在文档中的位置。如需详细了解索引编制,请参阅结构。表格属性包括许多样式元素,例如列宽和内边距。
以下 JSON 代码段显示了一个简单的 2x2 表,其中大部分细节都已移除:
"table": {
"columns": 2,
"rows": 2,
"tableRows": [
{ "tableCells": [
{
"content": [ { "paragraph": { ... }, } ],
},
{
"content": [ { "paragraph": { ... }, } ],
}
],
},
{
"tableCells": [
{
"content": [ { "paragraph": { ... }, } ],
},
{
"content": [ { "paragraph": { ... }, } ],
}
],
}
]
}
插入和删除表格
如需向文档中添加新表格,请使用 InsertTableRequest。 插入表格时,您必须指定以下内容:
- 表格的行数和列数。
- 要插入新表格的位置:可以是段落中的某个索引,也可以是段落的末尾。其中一个应包含指定标签页的 ID。
没有明确的方法可用于删除表格。如需从文档中删除表格,请像处理任何其他内容一样处理该表格:使用 DeleteContentRangeRequest,并指定涵盖整个表格的范围。
以下示例在空白文档末尾插入一个 3x3 表格:
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()
以下相应示例展示了如何删除之前插入的表格:
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()
由于您需要通过指定开始和结束索引来删除表格(就像删除普通内容一样),因此您需要从某个位置获取这些索引。该示例展示了一种从文档内容中提取这些索引的方法。
插入和删除行
如果您的文档已包含表格,则 Google Docs API 允许您插入和删除表格行。使用 InsertTableRowRequest 可在指定表格单元格的上方或下方插入行,使用 DeleteTableRowRequest 可移除跨越指定单元格位置的行。
以下示例将文本插入到表格的第一个单元格中,并添加一个表格行。
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()
插入和删除列
如需将列插入现有表格,请使用 InsertTableColumnRequest。您必须指定以下各项:
- 您要在其旁边插入新列的单元格。
- 新列的插入位置(左侧或右侧)。
以下示例展示了如何将列插入到前面显示的 2x2 表中:
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()
如需删除列,请使用 DeleteTableColumnRequest。 您只需指定目标列中的单元格位置,就像之前介绍的插入列一样。
读取表格单元格中的内容
表格单元格包含一个结构元素列表;每个结构元素都可以是包含文本的段落或其他类型的结构,甚至是另一个表格。如需读取表格内容,您可以递归检查每个元素,如提取文本中所示。
将内容插入到表格单元格中
如需写入表格单元格,请向要更新的单元格内的索引使用 InsertTextRequest。表格索引会进行调整,以适应更新后的文本。使用 DeleteContentRangeRequest 删除单元格文本时也是如此。
修改列属性
借助 UpdateTableColumnPropertiesRequest,您可以修改表中一个或多个列的属性。
您必须提供表格的起始索引,以及一个 TableColumnProperties 对象。如需仅修改所选列,请在请求中添加列号列表;如需修改表中的所有列,请提供一个空列表。
以下示例更新了表格的列宽,将所有列的宽度设置为 100 磅,然后将第一列的宽度设置为 200 磅:
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()
修改行样式
借助 UpdateTableRowsStyleRequest,您可以修改表格中一行或多行的样式。
您必须提供表格的起始索引,以及一个 TableRowStyle 对象。如需仅修改所选行,请在请求中添加行号列表;如需修改表格中的所有行,请提供一个空列表。
以下示例设置了表格第 3 行的最小高度:
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()