Google Sheets API 可讓您視需要在試算表中建立及更新圖表。本頁面的範例將說明如何使用 Sheets API 完成一些常見的圖表作業。
這些範例以 HTTP 要求的形式呈現,可達成語言中立的目標。如要瞭解如何使用 Google API 用戶端程式庫,以不同語言實作批次更新,請參閱「更新試算表」。
在這些範例中,預留位置 SPREADSHEET_ID 和 SHEET_ID 會指出您會在哪些位置提供這些 ID。你可以在試算表網址中找到試算表 ID。您可以使用 spreadsheets.get
方法取得工作表 ID。範圍是使用 A1 標記法來指定。範例範圍是 Sheet1!A1:D5。
此外,預留位置 CHART_ID 表示特定圖表的 ID。您可以在使用 Sheets API 建立圖表時設定此 ID,或允許 Sheets API 為您產生圖表。您可以使用 spreadsheets.get
方法取得現有圖表的 ID。
最後,預留位置 SOURCE_SHEET_ID 會指出包含來源資料的工作表。在以下範例中,這是「圖表來源資料」下方所列的表格。
圖表來源資料
以這些範例來說,假設目前使用的試算表在第一份工作表 (「Sheet1」) 中具有下列來源資料。第一列的字串是個別資料欄的標籤。如要查看如何讀取試算表中其他工作表的範例,請參閱 A1 標記法。
A | B | C | D | E | |
1 | 型號 | 銷售人員 - 1 月 | 銷售量 - 2 月 | 銷售 - 3 月 | 總銷售金額 |
2 | D-01X | 68 | 74 | 60 | 202 |
3 | FR-0B1 | 97 | 76 | 88 | 261 |
4 | P-034 | 27 | 49 | 32 | 108 |
5 | P-105 | 46 | 44 | 67 | 157 |
6 | W-11 | 75 | 68 | 87 | 230 |
7 | W-24 | 74 | 52 | 62 | 188 |
新增柱狀圖
下列 spreadsheets.batchUpdate
程式碼範例說明如何使用 AddChartRequest
從來源資料建立柱狀圖,並放在新的工作表中。要求會執行以下設定圖表:
- 將圖表類型設為柱狀圖。
- 在圖表底部新增圖例。
- 設定圖表標題和軸標題。
- 使用預設格式設定和顏色,設定 3 個資料序列,代表 3 個不同月份的銷售活動。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "addChart": { "chart": { "spec": { "title": "Model Q1 Sales", "basicChart": { "chartType": "COLUMN", "legendPosition": "BOTTOM_LEGEND", "axis": [ { "position": "BOTTOM_AXIS", "title": "Model Numbers" }, { "position": "LEFT_AXIS", "title": "Sales" } ], "domains": [ { "domain": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 0, "endColumnIndex": 1 } ] } } } ], "series": [ { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 1, "endColumnIndex": 2 } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 2, "endColumnIndex": 3 } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 3, "endColumnIndex": 4 } ] } }, "targetAxis": "LEFT_AXIS" } ], "headerCount": 1 } }, "position": { "newSheet": true } } } } ] }
這項要求會在新工作表中建立圖表,如下所示:
新增圓餅圖
以下 spreadsheets.batchUpdate
程式碼範例說明如何使用 AddChartRequest
從來源資料建立 3D 圓餅圖。要求會執行下列操作來設定圖表:
- 設定圖表標題。
- 在圖表右側加入圖例。
- 將圖表設為 3D 圓餅圖。請注意,3D 圓餅圖的中央不能有「甜甜圈」的形狀,像平坦圓餅圖一樣。
- 將圖表資料序列設為每個型號的總銷售額。
- 將圖表固定在 SHEET_ID 指定的工作表 C3 儲存格,X 和 Y 方向皆有 50 像素偏移。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "addChart": { "chart": { "spec": { "title": "Model Q1 Total Sales", "pieChart": { "legendPosition": "RIGHT_LEGEND", "threeDimensional": true, "domain": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 0, "endColumnIndex": 1 } ] } }, "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 7, "startColumnIndex": 4, "endColumnIndex": 5 } ] } }, } }, "position": { "overlayPosition": { "anchorCell": { "sheetId": SHEET_ID, "rowIndex": 2, "columnIndex": 2 }, "offsetXPixels": 50, "offsetYPixels": 50 } } } } } ] }
這項要求會建立如下圖表:
或者,您也可以在要求中將圖例 Position 值從 RIGHT_LEGEND 更新為 LABELED_LEGEND,讓圖例值連結至圓餅圖配量。
'legendPosition': 'LABELED_LEGEND',
更新後的要求會建立如下圖表:
新增多個非相鄰範圍的折線圖
以下 spreadsheets.batchUpdate
程式碼範例說明如何使用 AddChartRequest
,從來源資料建立折線圖,並放在來源工作表中。選取非相鄰範圍可用來排除 ChartSourceRange
中的資料列。
要求會執行以下設定圖表:
- 將圖表類型設為折線圖。
- 設定水平 x 軸標題。
- 設定代表銷售的資料序列。使用預設格式設定和顏色,並將 A1:A3 和 A6:A7 設為
domain
,並將 B1:B3 和 B6:B7 設為series
。範圍是透過要求網址中的 A1 標記法來指定。 - 將圖表固定在 SHEET_ID 指定的工作表 H8 儲存格中。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "addChart": { "chart": { "spec": { "basicChart": { "chartType": "LINE", "domains": [ { "domain": { "sourceRange": { "sources": [ { "startRowIndex": 0, "endRowIndex": 3, "startColumnIndex": 0, "endColumnIndex": 1, "sheetId": SOURCE_SHEET_ID }, { "startRowIndex": 5, "endRowIndex": 7, "startColumnIndex": 0, "endColumnIndex": 1, "sheetId": SOURCE_SHEET_ID } ] } } } ], "series": [ { "series": { "sourceRange": { "sources": [ { "startRowIndex": 0, "endRowIndex": 3, "startColumnIndex": 1, "endColumnIndex": 2, "sheetId": SOURCE_SHEET_ID }, { "startRowIndex": 5, "endRowIndex": 7, "startColumnIndex": 1, "endColumnIndex": 2, "sheetId": SOURCE_SHEET_ID } ] } } } ] } }, "position": { "overlayPosition": { "anchorCell": { "sheetId": SOURCE_SHEET_ID, "rowIndex": 8, "columnIndex": 8 } } } } } } ] }
這項要求會在新工作表中建立圖表,如下所示:
刪除圖表
下列 spreadsheets.batchUpdate
程式碼範例說明如何使用 DeleteEmbeddedObjectRequest
刪除 CHART_ID 指定的圖表。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "deleteEmbeddedObject": { "objectId": CHART_ID } } ] }
編輯圖表屬性
以下 spreadsheets.batchUpdate
程式碼範例說明如何使用 UpdateChartSpecRequest
編輯「新增柱狀圖」方案中建立的圖表,以及修改資料、類型和外觀。圖表屬性的子集無法個別變更。如要編輯,您必須為整個 spec
欄位提供 UpdateChartSpecRequest
。基本上,編輯圖表規格時,必須替換為新的規格。
以下要求會更新原始圖表 (由 CHART_ID 指定):
- 將圖表類型設為
BAR
。 - 將圖例移至圖表右側。
- 反轉軸,讓「Sales」顯示在底部軸,左軸為「Model Numbers」。
- 將軸標題格式設為 24 點字型、粗體以及斜體。
- 移除圖表中的「W-24」資料 (圖表來源資料中的第 7 列)。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "updateChartSpec": { "chartId": CHART_ID, "spec": { "title": "Model Q1 Sales", "basicChart": { "chartType": "BAR", "legendPosition": "RIGHT_LEGEND", "axis": [ { "format": { "bold": true, "italic": true, "fontSize": 24 }, "position": "BOTTOM_AXIS", "title": "Sales" }, { "format": { "bold": true, "italic": true, "fontSize": 24 }, "position": "LEFT_AXIS", "title": "Model Numbers" } ], "domains": [ { "domain": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 0, "endColumnIndex": 1 } ] } } } ], "series": [ { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 1, "endColumnIndex": 2 } ] } }, "targetAxis": "BOTTOM_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 2, "endColumnIndex": 3 } ] } }, "targetAxis": "BOTTOM_AXIS" }, { "series": { "sourceRange": { "sources": [ { "sheetId": SOURCE_SHEET_ID, "startRowIndex": 0, "endRowIndex": 6, "startColumnIndex": 3, "endColumnIndex": 4 } ] } }, "targetAxis": "BOTTOM_AXIS" } ], "headerCount": 1 } } } } ] }
要求產生圖表後,圖表應如下所示:
移動圖表或調整圖表大小
下列 spreadsheets.batchUpdate
程式碼範例說明如何使用 UpdateEmbeddedObjectPositionRequest
移動圖表及調整大小。要求之後,CHART_ID 指定的圖表如下:
- 固定在原始工作表的 A5 儲存格中。
- 垂直 X 方向 100 像素。
- 已調整為 1200 x 742 像素 (圖表的預設大小為 600 x 371 像素)。
這項要求只會變更以 fields
參數指定的屬性。
其他屬性 (例如 offsetYPixels
) 會保留原始值。
要求通訊協定如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{ "requests": [ { "updateEmbeddedObjectPosition": { "objectId": CHART_ID, "newPosition": { "overlayPosition": { "anchorCell": { "rowIndex": 4, "columnIndex": 0 }, "offsetXPixels": 100, "widthPixels": 1200, "heightPixels": 742 } }, "fields": "anchorCell(rowIndex,columnIndex),offsetXPixels,widthPixels,heightPixels" } } ] }
讀取圖表資料
以下 spreadsheets.get
程式碼範例顯示如何從試算表取得圖表資料。fields
查詢參數會指定只傳回圖表資料。
這個方法呼叫的回應為 spreadsheet
物件,其中包含 sheet
物件的陣列。工作表中顯示的任何圖表都會以 sheet
物件表示。如果將回應欄位設為預設值,回應中會省略該欄位。
在本例中,第一張工作表 (SOURCE_SHEET_ID) 沒有任何圖表,因此會傳回一組空白的大括號。第二張工作表是由「Add a column chart」(新增柱狀圖) 建立的圖表,不含其他圖表。
要求通訊協定如下所示。
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(charts)
{ "sheets": [ {}, { "charts": [ { "chartId": CHART_ID, "position": { "sheetId": SHEET_ID }, "spec": { "basicChart": { "axis": [ { "format": { "bold": false, "italic": false }, "position": "BOTTOM_AXIS", "title": "Model Numbers" }, { "format": { "bold": false, "italic": false }, "position": "LEFT_AXIS", "title": "Sales" } ], "chartType": "COLUMN", "domains": [ { "domain": { "sourceRange": { "sources": [ { "endColumnIndex": 1 "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 0, "startRowIndex": 0, } ] } } } ], "legendPosition": "BOTTOM_LEGEND", "series": [ { "series": { "sourceRange": { "sources": [ { "endColumnIndex": 2, "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 1, "startRowIndex": 0, } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "endColumnIndex": 3, "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 2, "startRowIndex": 0, } ] } }, "targetAxis": "LEFT_AXIS" }, { "series": { "sourceRange": { "sources": [ { "endColumnIndex": 4, "endRowIndex": 7, "sheetId": SOURCE_SHEET_ID, "startColumnIndex": 3, "startRowIndex": 0, } ] } }, "targetAxis": "LEFT_AXIS" } ] }, "hiddenDimensionStrategy": "SKIP_HIDDEN_ROWS_AND_COLUMNS", "title": "Model Q1 Sales", }, } ] } ] }