基本格式

使用 Google 表格 API,您可以更新电子表格中的单元格和范围的格式。本页面上的示例说明了如何使用 Tables API 实现一些常见的格式设置操作。您可以在条件格式设置方案页面中找到更多条件格式示例。

更新电子表格时,某些类型的请求可能会返回响应。这些响应以数组形式返回,每个响应占用与相应请求相同的索引。有些请求没有响应,对于这些请求,响应为空。这些示例的响应结构可在 spreadsheets.batchUpdate 下找到。

出于中性考虑,这些示例以 HTTP 请求的形式呈现。如需了解如何使用 Google API 客户端库以不同语言实现批量更新,请参阅更新电子表格

在这些示例中,占位符 SPREADSHEET_IDSHEET_ID 表示您要提供这些 ID 的位置。您可以在电子表格网址中找到电子表格 ID。您可以使用 spreadsheets.get 方法获取工作表 ID。范围使用 A1 表示法指定。例如,“Sheet1!A1:D5”是范围。

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

编辑单元格边框

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

3x3 表格,每个单元格都带有蓝色顶部和底部虚线边框。
图 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 字段中省略列索引会导致系统对整行进行格式设置。第二个请求会调整工作表属性,使标题行冻结。

表格中包含 3x3 的表格,其中包含设置了格式的标题行。
图 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 中的列,同时使行保持分隔状态。

工作表中包含合并单元格的 3x3 表格。
图 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”。

表格中包含自定义日期时间和数字格式的 3 x 3 表格。
图 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"
      }
    }
  ]
}