借助 Google 表格 API,您可以创建、清除、复制和删除工作表,还可以控制其属性。本页面上的示例说明了如何使用 Tables API 实现一些常见的 Google 表格操作。
出于中性考虑,这些示例以 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
,则会从工作表中移除 Tables 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
资源组成,其中包含具有 SheetProperties
元素的 Sheet
对象。如果给定响应字段设置为默认值,响应中将省略该字段。
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID
,
"title": "Sheet1",
"index": 0,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1
}
"tabColor": {
"blue": 1.0
}
},
...
],
}