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