圖表

您可以使用 Google Sheets API 在試算表中建立及更新圖表, 。本頁的範例將說明如何達成一些常見的 透過 Sheets API 執行圖表作業

這些範例是以 HTTP 要求的形式呈現 中立。如要瞭解如何使用 Google API 用戶端程式庫,請參閱 試算表

在這些範例中,預留位置 SPREADSHEET_IDSHEET_ID 代表這些 ID 的提供位置。您可以找到這份試算表 ID。您可以 工作表 ID spreadsheets.get 方法。 範圍是使用 A1 標記法來指定。一個 範例範圍是 Sheet1!A1:D5

此外,預留位置 CHART_ID 表示指定的 ID 圖表。使用 Sheets API 建立圖表時,您可以設定這組 ID。 或允許 Sheets API 為您產生您可以取得 現有的圖表 spreadsheets.get 方法,增加圍繞地圖邊緣的邊框間距。

最後,預留位置 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
            }
          }
        }
      }
    }
  ]
}

這項要求會建立如下圖表:

新增圓餅圖的食譜結果

或者,您也可從 RIGHT_LEGEND 更新此圖例 Position 值 要求中的 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」(銷售)位於底部軸和「型號」 就是左側軸
  • 將軸標題格式設為 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 物件。如果 response 欄位設為預設值,而會省略此回應。

在本例中,第一張工作表 (SOURCE_SHEET_ID) 沒有任何 圖表,因此會傳回一組空白的大括號。第二張工作表包含 圖表是由新增柱狀圖所製作的圖表,除此之外不會顯示任何圖表。

要求通訊協定如下所示。

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",
          },
        }
      ]
    }
  ]
}