利用 Sheets API,您可以向单元格、范围、范围集以及整个工作表写入值和公式。 本页面上的示例说明了如何使用此 API 的 spreadsheets.values 集合实现一些常用的写入操作。
请注意,也可以使用 spreadsheet.batchUpdate 方法写入单元格值,如果您希望同步更新单元格格式设置或 spreadsheets.values 集合不会影响的其他属性,此方法将非常实用。不过,对于简单的值写入操作,使用 spreadsheets.values.update 或 spreadsheets.values.batchUpdate 更简单。
在这些示例中,占位符 spreadsheetId 用于表示您需要提供电子表格 ID 的位置,可以从电子表格网址中找到此 ID。要写入的范围在请求网址中使用 A1 表示法指定。
向单个范围写入数据
下面的 spreadsheets.values.update 请求会从一个新的空电子表格开始,将值写入范围 Sheet1!A1:D5。ValueInputOption 查询参数是一个必要参数,并确定是否解析写入的值(例如,是否将字符串转换为日期)。
请求正文是一个 ValueRange
对象,该对象对要写入的范围值进行了说明。majorDimension 字段确定是否将包含的数组解释为列或行数组。目标范围中的现有值将被替换。
请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A1:D5?valueInputOption=USER_ENTERED { "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "3/1/2016"], ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "30/20/2016"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
响应将包含一个如下所示的 UpdateValuesResponse 对象:
{ "spreadsheetId": spreadsheetId, "updatedRange": "Sheet1!A1:D5", "updatedRows": 5, "updatedColumns": 4, "updatedCells": 20, }
生成的工作表将如下所示:
A | B | C | D | |
1 | Item | Cost | Stocked | Ship Date |
2 | Wheel | $20.50 | 4 | 3/1/2016 |
3 | Door | $15 | 2 | 3/15/2016 |
4 | Engine | $100 | 1 | 3/20/2016 |
5 | Totals | $135.5 | 7 | 3/20/2016 |
向范围选择性写入值
在向范围写入值时,将相应的数组元素设为 null
可以避免对某些现有单元格进行更改。 向单元格中写入空字符串也可以清除其数据。
下面的 spreadsheets.values.update 请求会从一个通过上面的示例生成并包含相同数据的工作表开始,将值写入范围 B1:D4,同时选择性保留某些单元格不变和清除其他单元格。ValueInputOption 查询参数是一个必要参数,并确定是否解析写入的值(例如,是否将字符串是否为日期)。
请求正文是一个 ValueRange
对象,该对象对要写入的范围值进行了说明。 majorDimension 字段指示数组是否为按列组织的值列表。
请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!B1?valueInputOption=USER_ENTERED { "range": "Sheet1!B1", "majorDimension": "COLUMNS", "values": [ [null,"$1","$2", ""], [], [null,"4/1/2016", "4/15/2016", ""] ] }
此处的 values 字段将列出对范围中的每一列进行的更改。 第一个数组指示 B1 保持不变(由于存在 null
数组元素),而 B4 将被清除(空字符串)。 B2 和 B3 的值将更新。 第三个数组会在 D 列执行相同操作,而第二个空数组则指示 C 列保持不变。
响应将包含一个如下所示的 UpdateValuesResponse 对象:
{ "spreadsheetId": spreadsheetId, "updatedRange": "Sheet1!B1:D5", "updatedRows": 3, "updatedColumns": 2, "updatedCells": 6, }
生成的工作表将如下所示:
A | B | C | D | |
1 | Item | Cost | Stocked | Ship Date |
2 | Wheel | $1.00 | 4 | 4/1/2016 |
3 | Door | $2 | 2 | 4/15/2016 |
4 | Engine | 1 | ||
5 | Totals | $3.00 | 7 | 4/15/2016 |
请注意,尽管“Totals”行不是直接通过此请求更改,该行也会发生变化,因为其单元格包含依赖于已更改单元格的公式。
向多个范围写入数据
下面的 spreadsheets.values.batchUpdate 请求会从一个空白工作表开始,写入来自范围 Sheet1!A1:A4 和 Sheet1!B1:D2 的值。目标范围中的现有值将被替换。 请求正文将包含一个带 ValueInputOption(用于写入)的对象和一组对应于每个已写入范围的 ValueRange
对象。majorDimension 字段确定是否将包含的数组解释为列或行数组。
请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate { "valueInputOption": "USER_ENTERED", "data": [ { "range": "Sheet1!A1:A4", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door", "Engine"] ] }, { "range": "Sheet1!B1:D2", "majorDimension": "ROWS", "values": [ ["Cost", "Stocked", "Ship Date"], ["$20.50", "4", "3/1/2016"] ] } ] }
响应将包含一个列出已更新单元格统计信息的对象和一组 UpdateValuesResponse 对象,每个对象对应于一个更新的范围。
例如:
{ "spreadsheetId": spreadsheetId, "totalUpdatedRows": 4, "totalUpdatedColumns": 4, "totalUpdatedCells": 10, "totalUpdatedSheets": 1, "responses": [ { "spreadsheetId": spreadsheetId, "updatedRange": "Sheet1!A1:A4", "updatedRows": 4, "updatedColumns": 1, "updatedCells": 4, }, { "spreadsheetId": spreadsheetId, "updatedRange": "Sheet1!B1:D2", "updatedRows": 2, "updatedColumns": 3, "updatedCells": 6, } ], }
生成的工作表将如下所示:
A | B | C | D | |
1 | Item | Cost | Stocked | Ship Date |
2 | Wheel | $20.50 | 4 | 3/1/2016 |
3 | Door | |||
4 | Engine | |||
5 |
写入值但不解析
下面的 spreadsheets.values.update 请求会从一个空白工作表开始,将值写入范围 Sheet1!A1:E1,不过将使用 RAW
ValueInputOption 查询参数来防止将写入的字符串解析为公式、布尔值或数字;这些数据将在工作表中以字符串形式显示和对齐。
请求正文是一个 ValueRange
对象,该对象对要写入的范围值进行了说明。majorDimension 字段确定是否将包含的数组解释为列或行数组。目标范围中的现有值将被替换。
请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A1:E1?valueInputOption=RAW { "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Data", 123.45, true, "=MAX(D2:D4)", "10"] ], }
响应将包含一个如下所示的 UpdateValuesResponse 对象:
{ "spreadsheetId": spreadsheetId, "updatedRange": "Sheet1!A1:E1", "updatedRows": 1, "updatedColumns": 5, "updatedCells": 5, }
生成的工作表将如下所示:
A | B | C | D | E | |
1 | Data | 123.45 | TRUE | =MAX(D2:D4) | 10 |
2 |
请注意“true”的居中方式以及它将成为原生的 TRUE 布尔值,“123.45”靠右对齐,因为它是一个数字,而“10”靠左对齐,因为它是一个字符串。公式不会解析,也将作为字符串显示。
追加值
从一个类似于下面表格的工作表开始:
A | B | C | D | |
1 | Item | Cost | Stocked | Ship Date |
2 | Wheel | $20.50 | 4 | 3/1/2016 |
3 |
根据上面的数据,以下 spreadsheets.values.append 请求将从第 3 行开始添加两行新值。ValueInputOption 查询参数是一个必要参数,并确定是否解析写入的值(例如,是否将字符串转换为日期)。
请求正文是一个 ValueRange
对象,该对象对要写入的范围值进行了说明。majorDimension 字段确定是否将包含的数组解释为列或行数组。
请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A1:E1:append?valueInputOption=USER_ENTERED { "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "3/20/2016"], ], }
响应将包含一个如下所示的 AppendValuesResponse 对象:
{ "spreadsheetId": spreadsheetId, "tableRange": "Sheet1!A1:D2", "updates": { "spreadsheetId": spreadsheetId, "updatedRange": "Sheet1!A3:D4", "updatedRows": 2, "updatedColumns": 4, "updatedCells": 8, } }
生成的工作表将如下所示:
A | B | C | D | |
1 | Item | Cost | Stocked | Ship Date |
2 | Wheel | $20.50 | 4 | 3/1/2016 |
3 | Door | $15 | 2 | 3/15/2016 |
4 | Engine | $100 | 1 | 3/20/2016 |
3 |