基本格式

您可以使用 Google Sheets API 更新試算表中的儲存格和範圍格式。本頁的範例說明如何使用 Google 試算表 API 執行一些常見的格式設定作業。如要查看更多條件式格式設定範例，請前往「條件式格式設定」食譜頁面。

更新試算表時，部分類型的要求可能會傳回回應。 這些回應會以陣列形式傳回，每個回應佔用的索引與對應要求相同。部分要求沒有回應，因此回應為空白。如要查看這些範例的回應結構，請前往 spreadsheets.batchUpdate。

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

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

在上方影片中，您將瞭解如何以各種方式設定試算表儲存格格式，包括建立凍結列、將儲存格設為粗體、套用貨幣格式、執行儲存格驗證，以及限制儲存格值。

編輯儲存格框線

下列程式碼範例顯示如何使用 spreadsheets.batchUpdate 為 A1:F10 範圍內的每個儲存格加上藍色虛線上下框線。UpdateBordersRequestinnerHorizontal 欄位會在範圍內部建立水平邊框。如果省略這個欄位，系統只會在整個範圍的頂端和底部新增框線。

圖 1. 在試算表中，為每個儲存格加上藍色虛線上下框線。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateBorders": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 6
        },
        "top": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
        "bottom": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
        "innerHorizontal": {
          "style": "DASHED",
          "width": 1,
          "color": {
            "blue": 1.0
          },
        },
      }
    }
  ]
}

設定標題列格式

下列程式碼範例說明如何使用 spreadsheets.batchUpdate RepeatCellRequest 格式化試算表中的標題列。第一個要求會更新文字顏色、背景顏色、文字字型大小和文字對齊方式，並將文字設為粗體。如果省略 range 欄位中的資料欄索引，系統會格式化整列資料。第二個要求會調整試算表屬性，凍結標題列。

圖 2. 設定試算表中的標題列格式。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 1
        },
        "cell": {
          "userEnteredFormat": {
            "backgroundColor": {
              "red": 0.0,
              "green": 0.0,
              "blue": 0.0
            },
            "horizontalAlignment" : "CENTER",
            "textFormat": {
              "foregroundColor": {
                "red": 1.0,
                "green": 1.0,
                "blue": 1.0
              },
              "fontSize": 12,
              "bold": true
            }
          }
        },
        "fields": "userEnteredFormat(backgroundColor,textFormat,horizontalAlignment)"
      }
    },
    {
      "updateSheetProperties": {
        "properties": {
          "sheetId": SHEET_ID,
          "gridProperties": {
            "frozenRowCount": 1
          }
        },
        "fields": "gridProperties.frozenRowCount"
      }
    }
  ]
}

合併儲存格

下列 spreadsheets.batchUpdate 程式碼範例說明如何使用 MergeCellsRequest 合併儲存格。第一個要求會將 A1:B2 範圍合併為單一儲存格。第二個要求會合併 A3:B6 中的資料欄，但資料列會保持分開。

圖 3. 合併工作表中的儲存格。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "mergeCells": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 2,
          "startColumnIndex": 0,
          "endColumnIndex": 2
        },
        "mergeType": "MERGE_ALL"
      }
    },
    {
      "mergeCells": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 2,
          "endRowIndex": 6,
          "startColumnIndex": 0,
          "endColumnIndex": 2
        },
        "mergeType": "MERGE_COLUMNS"
      }
    },
  ]
}

為範圍設定自訂日期時間或十進位格式

下列spreadsheets.batchUpdate程式碼範例說明如何使用 RepeatCellRequest 更新儲存格，使其採用自訂日期時間和數字格式。第一個要求會將 A1:A10 範圍內的儲存格設為自訂日期時間格式 hh:mm:ss am/pm, ddd mmm dd yyyy。此格式的日期時間範例如下：「02:05:07 PM, Sun Apr 03 2016」。

第二個要求會將 B1:B10 儲存格的自訂數字格式設為 #,##0.0000，表示數字應以半形逗號分隔，小數點後應有 4 位數，且除了開頭的零以外，其餘零都應捨去。舉例來說，數字「3.14」會顯示為「3.1400」，而「12345.12345」會顯示為「12,345.1235」。

詳情請參閱「日期和數字格式」。

圖 4 在試算表中更新儲存格，自訂日期時間和數字格式。

要求通訊協定如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 1
        },
        "cell": {
          "userEnteredFormat": {
            "numberFormat": {
              "type": "DATE",
              "pattern": "hh:mm:ss am/pm, ddd mmm dd yyyy"
            }
          }
        },
        "fields": "userEnteredFormat.numberFormat"
      }
    },
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 2
        },
        "cell": {
          "userEnteredFormat": {
            "numberFormat": {
              "type": "NUMBER",
              "pattern": "#,##0.0000"
            }
          }
        },
        "fields": "userEnteredFormat.numberFormat"
      }
    }
  ]
}