您可以透過 Google Docs API 編輯表格內容。您可以執行的作業包括：
- 插入及刪除資料列、資料欄或整個資料表。
- 將內容插入表格儲存格。
- 讀取表格儲存格中的內容。
- 修改資料欄屬性和資料列樣式。
Google 文件中的資料表在文件中會顯示為 StructuralElement 類型。每個資料表都包含資料表資料列清單，而每個資料列都含有資料表儲存格清單。如同所有結構元素，資料表也有起始和結束索引，指出資料表在文件中的位置。如要進一步瞭解建立索引的作業，請參閱結構。表格屬性包含許多樣式元素，例如欄寬度和邊框間距。
下列 JSON 片段顯示已移除大多數詳細資料的簡易 2x2 資料表：
"table": {
"columns": 2,
"rows": 2,
"tableRows": [
{ "tableCells": [
{
"content": [ { "paragraph": { ... }, } ],
},
{
"content": [ { "paragraph": { ... }, } ],
}
],
},
{
"tableCells": [
{
"content": [ { "paragraph": { ... }, } ],
},
{
"content": [ { "paragraph": { ... }, } ],
}
],
}
]
}
插入及刪除資料表
如要將資料表新增至文件，請使用 InsertTableRequest。插入資料表時，您必須指定下列項目：
- 資料列和資料欄中的表格維度。
- 插入新資料表的位置：可以是一個區隔中的索引，也可以是區隔的結尾。
沒有明確的刪除資料表的方法。如要從文件中刪除資料表，請按照處理其他內容相同的方式來使用 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())
.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': ''
}
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()
以下對應範例說明如何刪除先前插入的資料表：
Java
// Delete a table that was inserted at the start of the body.
// (The table is the second element in the body:
// document.getBody().getContent().get(2).)
Document document = docsService.documents().get(DOCUMENT_ID).execute();
StructuralElement table = document.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()))));
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.
# (The table is the second element in the body: ['body']['content'][2].)
document = service.documents().get(documentId=DOCUMENT_ID).execute()
table = document['body']['content'][2]
requests = [{
'deleteContentRange': {
'range': {
'segmentId': '',
'startIndex': table['startIndex'],
'endIndex': table['endIndex']
}
},
}
]
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))));
requests.add(new Request().setInsertTableRow(new InsertTableRowRequest()
.setTableCellLocation(new TableCellLocation()
.setTableStartLocation(new Location()
.setIndex(2))
.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
},
'text': 'Hello'
}
},
{
'insertTableRow': {
'tableCellLocation': {
'tableStartLocation': {
'index': 2
},
'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))
.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
},
'rowIndex': 0,
'columnIndex': 0
},
'insertRight': True
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()
如要刪除資料欄，請使用 DeleteTableColumnRequest。如同先前插入資料欄所示，您可以在目標資料欄中指定儲存格位置。
讀取表格儲存格中的內容
表格儲存格包含結構元素的清單；每個結構元素可以是包含文字或其他類型的結構的段落，甚至是其他資料表。如要讀取資料表內容，您可以遞迴檢查每個元素，如擷取文字所示。
將內容插入表格儲存格
如要寫入資料表儲存格，請在您想更新的儲存格中，使用 InsertTextRequest 至索引。資料表索引會因應更新的文字而調整。這也適用於使用 DeleteContentRangeRequest 刪除儲存格文字的情況。
修改資料欄屬性
UpdateTableColumnPropertiesRequest 可讓您修改資料表中一或多個資料欄的屬性。
您必須提供資料表的起始索引和 TableColumnProperties 物件。如果只要修改所選資料欄，請在要求中加入欄號清單；如要修改資料表中的所有資料欄，請提供空白清單。
以下範例會更新資料表的欄寬度，將所有資料欄的寬度設為 100pt，接著將第一欄的寬度設為 200pt：
Java
List<Request> requests = new ArrayList<>();
requests.add(
new Request()
.setUpdateTableColumnProperties(
new UpdateTableColumnPropertiesRequest()
.setTableStartLocation(new Location().setIndex(2))
.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))
.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},
'columnIndices': [],
'tableColumnProperties': {
'widthType': 'FIXED_WIDTH',
'width': {
'magnitude': 100,
'unit': 'PT'
}
},
'fields': '*'
},
'updateTableColumnProperties': {
'tableStartLocation': {'index': 2},
'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))
.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},
'rowIndices': [3],
'tableRowStyle': {
'minRowHeight': {
'magnitude': 18,
'unit': 'PT'
}
},
'fields': '*'
},
}
]
result = service.documents().batchUpdate(documentId=DOCUMENT_ID, body={'requests': requests}).execute()