使用表格

本文档介绍了如何在 Google Docs API 中处理表格。

借助 Docs API，您可以修改表格内容。您可以执行的操作包括：

  • 插入和删除行、列或整个表格。
  • 将内容插入到表格单元格中。
  • 读取表格单元格中的内容。
  • 修改列属性和行的样式。

Google 文档中的表格在文档中表示为 StructuralElement 类型。每个 Table 都包含一个 TableRow 对象列表，其中每行都包含一个 TableCell 对象列表。与所有结构化元素一样，表格具有开始和结束索引，用于指示表格在文档中的位置。表格属性包括许多样式元素，例如列宽和内边距。

示例表格

以下 JSON 代码段显示了一个 2x2 表格，其中大部分详细信息已被移除：

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

下表显示了 2x2 表中每个结构元素的索引偏移量，假设该表从索引 S 开始，并且所有单元格均为空（每个单元格仅包含一个换行符 \n，长度为 1）：

元素 路径 起始索引 结束索引
表格 / S S + 12
    TableRow 0 /rows[0] S + 1 S + 6
        TableCell (0,0) /rows[0]/cells[0] S + 2 S + 4
            段落 /rows[0]/cells[0]/p[0] S + 3 S + 4
        TableCell (0,1) /rows[0]/cells[1] S + 4 S + 6
            段落 /rows[0]/cells[1]/p[0] S + 5 S + 6
    第 1 行 /rows[1] S + 6 S + 11
        TableCell (1,0) /rows[1]/cells[0] S + 7 S + 9
            段落 /rows[1]/cells[0]/p[0] S + 8 S + 9
        TableCell (1,1) /rows[1]/cells[1] S + 9 S + 11
            段落 /rows[1]/cells[1]/p[0] S + 10 S + 11

插入和删除表格

如需向文档添加表格，请使用 InsertTableRequest。 插入表格时，您必须指定以下内容：

  • 表格的维度（以行和列为单位）。
  • 插入表格的位置：可以是段落（例如正文、标题或页脚）中的索引，也可以是段落的末尾。其中一个应包含指定标签页的 ID。

如需在正文末尾插入表格，请指定 EndOfSegmentLocation 对象，并将 segmentId 留空。

没有用于删除表的明确方法。如需从文档中删除表格，请像处理任何其他内容一样处理该表格：使用 DeleteContentRangeRequest，并指定涵盖整个表格的 range。

以下代码示例展示了如何在空文档末尾插入一个 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(<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()

以下代码示例展示了如何通过指定表的起始和结束索引来删除表。此示例演示了如何从文档内容中检索这些索引。

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

插入和删除行

如果文档已包含表格，您可以使用 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(<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()

插入和删除列

如需将列插入现有表中，请使用 InsertTableColumnRequest。您必须指定以下各项：

  • 您要在其旁边插入新列的单元格。
  • 新列的插入位置（左侧或右侧）。

以下代码示例展示了如何将列插入到前面显示的示例 2x2 表格中：

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

如需删除列，请使用 DeleteTableColumnRequest。您必须指定目标列中的单元格位置，如前面插入列时所示。

读取表格单元格中的内容

表格单元格包含 StructuralElement 对象的列表。这些结构元素可以是包含文本的段落，也可以是其他类型的结构，甚至是另一个表格。如需读取表格内容，您可以递归检查每个元素，如使用 Docs API 从文档中提取文本代码示例所示。

在表格单元格中插入内容

如需写入表格单元格，请使用 InsertTextRequest 设置为要更新的单元格的 location。表格索引会进行调整，以适应更新后的文本。同样，使用 DeleteContentRangeRequest 删除单元格文本时也是如此。

以下代码示例展示了如何写入表格单元格：

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

修改列属性

借助 UpdateTableColumnPropertiesRequest，您可以修改表中一列或多列的属性。

您必须提供表的起始索引以及 TableColumnProperties 对象。如需仅修改所选列，请在请求中添加列号列表。如需修改表中的所有列，请提供一个空列表。

以下代码示例展示了如何更新表格的列宽，将所有列设置为 100 磅宽，然后将第一列的宽度设置为 200 磅：

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

修改行样式

借助 UpdateTableRowStyleRequest，您可以修改表格中一行或多行的样式。

您必须提供表的起始索引以及 TableRowStyle 对象。如需仅修改所选行，请在请求中添加行号列表。如需修改表中的所有行，请提供一个空列表。

以下代码示例展示了如何设置表格中第三行的最小高度：

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