数据操作

利用 Google Sheets API,您可以通过多种方式操作电子表格内的数据。用户使用 Google 表格界面实现的大多数功能也可以通过 Google 表格 API 实现。本页面上的示例说明了如何使用 Sheets API 实现一些常见的电子表格操作。

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

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

向范围应用数据验证

以下 spreadsheets.batchUpdate 代码示例展示了如何使用 SetDataValidationRequest 将数据验证规则(其中“值 > 5”)应用于范围 A1:D10 中的每个单元格。

请求协议如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

复制和粘贴单元格格式

以下 spreadsheets.batchUpdate 代码示例展示了如何使用 CopyPasteRequest 仅复制范围 A1:D10 中的格式,并将其粘贴到同一工作表中的范围 F1:I10。该方法将 PasteType 枚举与 PASTE_FORMAT 结合使用,仅用于粘贴格式设置和数据验证。A1:D10 中的原始值保持不变。

请求协议如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

剪切和粘贴单元格

以下 spreadsheets.batchUpdate 代码示例展示了如何使用 CutPasteRequest。它会剪切范围 A1:D10,并使用 PasteType 枚举与 PASTE_NORMAL 结合将其值、公式、格式粘贴到同一工作表中的范围 F1:I10 中并与之合并。源范围单元格中的原始内容将移除。

请求协议如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

在一个范围内重复公式

以下 spreadsheets.batchUpdate 代码示例展示了如何使用 RepeatCellRequest 将公式 =FLOOR(A1*PI()) 复制到范围 B1:D10。公式的范围将从左上角的单元格开始,在范围内的每行和每列中自动递增。例如,单元格 B1 的公式为 =FLOOR(A1*PI()),而单元格 D6 的公式则为 =FLOOR(C6*PI())

请求协议如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

使用多种排序规范对范围进行排序

以下 spreadsheets.batchUpdate 代码示例展示了如何使用 SortRangeRequest 对范围 A1:D10 进行排序:先按 B 列升序排序,然后按 C 列降序排序,最后按 D 列降序排序。

请求协议如下所示。

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}