工作表作業

Google 試算表 API 可讓您建立、清除、複製和刪除工作表,也可以控制工作表的屬性。本頁的範例說明如何使用 Sheets API 執行部分常見的試算表作業。

這些範例是以 HTTP 要求形式呈現,採用不受語言限制。如要瞭解如何使用 Google API 用戶端程式庫以不同語言實作批次更新,請參閱「更新試算表」。

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

新增工作表

以下 spreadsheets.batchUpdate 程式碼範例說明如何使用 AddSheetRequest 新增工作表至試算表,同時設定標題、格線大小和分頁顏色。

回應由 AddSheetResponse 組成,其中包含物件和已建立工作表的屬性 (例如其 SHEET_ID)。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

清除所有值的工作表,並保留格式

以下 spreadsheets.batchUpdate 程式碼範例說明如何使用 UpdateCellsRequest 移除工作表中的所有值,同時保留格式維持不變。

如果指定沒有對應值的 userEnteredValue 欄位,系統會將此解讀為清除範圍內值的指示。這項設定也可以與其他欄位搭配使用。舉例來說,如果將 fields 值變更為 userEnteredFormat,則會從工作表中移除 Sheet API 支援的所有格式,但儲存格的值維持不變。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

將工作表從一份試算表複製到其他試算表

以下 spreadsheet.sheets.copyTo 程式碼範例說明如何將 SHEET_ID 指定的單一工作表從一份試算表複製到另一份試算表。

要求主體中的 TARGET_SPREADSHEET_ID 變數會指定目的地試算表。副本會保留原始所有值、格式、公式和其他屬性。複製的工作表標題會設定為「Copy of <原始工作表標題>」。

回應包含描述所建立工作表屬性的 SheetProperties 物件。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo
{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

刪除工作表

以下 spreadsheets.batchUpdate 程式碼範例說明如何使用 DeleteSheetRequest 刪除 SHEET_ID 指定的工作表。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

讀取工作表資料

下列 spreadsheets.get 程式碼範例說明如何從 SHEET_IDSPREADSHEET_ID 指定的試算表中取得工作表屬性資訊。此方法經常用於判斷特定試算表中的工作表中繼資料,因此可讓其他作業指定這些工作表。fields 查詢參數指定只應傳回工作表屬性資料 (而非儲存格值資料或與整個試算表相關的資料)。

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

回應由 Spreadsheet 資源組成,該資源包含具有 SheetProperties 元素的 Sheet 物件。如果特定回應欄位設為預設值,回應會省略該欄位。

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}