基本格式

您可以使用 Google Sheets API 更新单元格和范围的格式 生成自己的代码。本页中的示例说明了一些常见的 格式设置操作可通过 Sheets API 实现。您可以 如需更多条件格式设置示例,请参阅条件格式 格式食谱页面中。

在更新电子表格时,某些类型的请求可能会返回响应。 这些响应以数组形式返回,并且每个响应与 相应的请求有些请求没有响应 响应为空。您可以在以下位置找到这些示例的响应结构: spreadsheets.batchUpdate

这些示例以 HTTP 请求的形式呈现, 中性。了解如何使用 请参阅更新 电子表格

在这些示例中,占位符 SPREADSHEET_IDSHEET_ID 指明提供这些 ID 的位置。您可以在电子表格 ID。您可以获得 工作表 ID spreadsheets.get 方法。通过 范围使用 A1 表示法指定。一个 示例范围是“Sheet1!A1:D5”。

在上面的视频中,您学习了如何通过各种方式设置电子表格单元格的格式, 包括:创建冻结行、加粗单元格、实施货币 格式设置、执行单元格验证以及限制单元格值。

编辑单元格边框

以下 spreadsheets.batchUpdate 代码示例展示了如何使用 UpdateBordersRequest 为 A1:F10 范围中的每个单元格添加蓝色虚线边框,该边框为蓝色。通过 innerHorizontal 字段用于在范围的内部创建水平边框。 如果省略此字段,则系统只会向顶部添加边框, 整个范围的底部。

3 x 3 表格,每个单元格都有蓝色的上下虚线边框。
图 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 字段中的列索引会导致整个 行设置格式。第二个请求会调整工作表属性,以便 标题行被冻结。

工作表中带有格式化标题行的 3 x 3 表格。
图 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 x 3 表格。
图 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”。

工作表中采用自定义日期时间和数字格式的 3x3 表格。
图 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"
      }
    }
  ]
}