表格操作

借助 Google Sheets API，您可以创建、清除、复制和删除工作表，还可以控制其属性。本页面的示例说明了如何使用 Sheets API 实现一些常见的 Sheets 操作。

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

在这些示例中，占位符 SPREADSHEET_ID 和 SHEET_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 会从工作表中移除 Sheets 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 变量指定了目标电子表格。副本会保留原始工作表的所有值、格式、公式和其他属性。复制的工作表的标题设置为“[原始工作表标题] 的副本”。

响应包含一个 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_ID 和 SPREADSHEET_ID 指定的电子表格中获取工作表属性信息 。此方法通常用于确定特定电子表格中的工作表的元数据，以便其他操作可以针对这些工作表。fields 查询参数指定仅应返回工作表属性数据（而不是单元格值数据或与整个电子表格相关的数据）。

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

响应包含一个 Spreadsheet 资源，其中包含一个 Sheet对象，其中包含 SheetProperties 元素。如果给定响应字段设置为默认值，则该字段会从响应中省略。

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