借助 Google 表格 API,您可以向单元格、范围、范围集以及整个工作表写入值和公式。本页面上的示例说明了如何使用 Tables API 的 spreadsheets.values
资源实现一些常见的写入操作。
请注意,您也可以使用 spreadsheet.batchUpdate
方法写入单元格值,当您想同时更新单元格格式设置或 spreadsheets.values
资源不会影响的其他属性时,该方法会非常有用。例如,如果要将一系列单元格从一个工作表复制到另一个工作表,同时覆盖单元格公式和单元格格式,您可以将 UpdateCellsRequest
方法与 spreadsheet.batchUpdate
结合使用。
不过,对于简单值写入,使用 spreadsheets.values.update
方法或 spreadsheets.values.batchUpdate
方法更简单。
出于中性考虑,这些示例以 HTTP 请求的形式呈现。如需了解如何使用 Google API 客户端库以不同语言实现写入,请参阅读取和写入单元格值。
在这些示例中,占位符 SPREADSHEET_ID
表示您应提供电子表格 ID 的位置,可通过电子表格网址找到此 ID。要写入的范围使用 A1 表示法指定。例如,“Sheet1!A1:D5”是范围。
写入单个范围
以下 spreadsheets.values.update
代码示例从一个新的空白电子表格开始,演示了如何将值写入范围。ValueInputOption
查询参数是必需参数,用于确定是否解析写入的值(例如,是否将字符串转换为日期)。
请求正文是一个 ValueRange
对象,用于描述要写入的范围值。majorDimension
字段表示数组是由行整理的值列表。目标范围内的现有值会被覆盖。
请求协议如下所示。
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION
{ "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", "3/20/2016"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
响应包含一个 UpdateValuesResponse
对象,如下所示:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}
生成的工作表如下所示:
A | B | C | D | |
1 | 商品 | 费用 | 有货 | 发货日期 |
2 | 摩天轮 | 20.50 美元 | 4 | 2016 年 3 月 1 日 |
3 | 门 | 港元 | 2 | 2016 年 3 月 15 日 |
4 | 引擎 | 港元 | 1 | 2016 年 3 月 20 日 |
5 | 总计 | 135.5 | 7 | 2016 年 3 月 20 日 |
向范围选择性写入
向某个范围写入值时,可以通过将相应的数组元素设置为 null
来避免更改某些现有单元格。您也可以通过向单元格中写入空字符串 (""
) 来清除该单元格。
以下 spreadsheets.values.update
代码示例以包含上述示例所生成的数据的工作表开头,展示了如何将值写入 B1:D4 范围,选择性地保持某些单元格不变并清除其他单元格。ValueInputOption
查询参数是必需参数,用于确定是否解析写入的值(例如,是否将字符串转换为日期)。
请求正文是一个 ValueRange
对象,用于描述要写入的范围值。majorDimension
字段表示数组是由列整理的值列表。
请求协议如下所示。
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION
{ "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": SPREADSHEET_ID
,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}
生成的工作表如下所示:
A | B | C | D | |
1 | 商品 | 费用 | 有货 | 发货日期 |
2 | 摩天轮 | 1.00 美元 | 4 | 2016 年 4 月 1 日 |
3 | 门 | $2 | 2 | 2016 年 4 月 15 日 |
4 | 引擎 | 1 | ||
5 | 总计 | 3.00 美元 | 7 | 2016 年 4 月 15 日 |
请注意,尽管“总计”行不会经此请求直接更改,但会发生变化,因为其单元格包含依赖于更改后的单元格的公式。
写入多个范围
以下 spreadsheets.values.batchUpdate
代码示例从空白工作表开始,演示了如何将值写入范围 Sheet1!A1:A4 和 Sheet1!B1:D2。目标范围中的现有值会被覆盖。请求正文包含一个 ValueInputOption
对象(展示如何解读输入数据)和一个 ValueRange
对象数组(对应于写入的每个范围)。majorDimension
字段用于确定包含的数组是否解释为列或行的数组。
请求协议如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values:batchUpdate
{ "valueInputOption": "VALUE_INPUT_OPTION", "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":SPREADSHEET_ID
, "totalUpdatedRows": 4, "totalUpdatedColumns": 4, "totalUpdatedCells": 10, "totalUpdatedSheets": 1, "responses": [ { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!A1:A4", "updatedRows": 4, "updatedColumns": 1, "updatedCells": 4, }, { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!B1:D2", "updatedRows": 2, "updatedColumns": 3, "updatedCells": 6, } ], }
生成的工作表如下所示:
A | B | C | D | |
1 | 商品 | 费用 | 有货 | 发货日期 |
2 | 摩天轮 | 20.50 美元 | 4 | 2016 年 3 月 1 日 |
3 | 门 | |||
4 | 引擎 | |||
5 |
写入值但不解析
以下 spreadsheets.values.update
代码示例从空白工作表开始,展示了如何将值写入范围 Sheet1!A1:E1,但使用了 RAW
ValueInputOption
查询参数来防止写入的字符串被解析为公式、布尔值或数字。它们以字符串形式显示,且文本对齐方式在工作表中处于两端。
请求正文是一个 ValueRange
对象,用于描述要写入的范围值。majorDimension
字段表示数组是由行整理的值列表。目标范围内的现有值会被覆盖。
请求协议如下所示。
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:E1?valueInputOption=RAW
{ "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Data", 123.45, true, "=MAX(D2:D4)", "10"] ], }
响应包含一个 UpdateValuesResponse
对象,如下所示:
{
"spreadsheetId": SPREADSHEET_ID
,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}
生成的工作表如下所示:
A | B | C | D | E | |
1 | 数据 | 123.45 | TRUE | =MAX(D2:D4) | 10 |
2 |
请注意,“TRUE”居中且是一个布尔值,而“123.45”由于是一个数字而右对齐,而“10”由于是一个字符串而左对齐。公式不会解析,并且会以字符串形式显示。
附加值
从类似下表的工作表开始:
A | B | C | D | |
1 | 商品 | 费用 | 有货 | 发货日期 |
2 | 摩天轮 | 20.50 美元 | 4 | 2016 年 3 月 1 日 |
3 |
以下 spreadsheets.values.append
代码示例展示了如何添加从第 3 行开始的两行新值。ValueInputOption
查询参数是必需参数,用于确定是否解析写入的值(例如,是否将字符串转换为日期)。
请求正文是一个 ValueRange
对象,用于描述要写入的范围值。majorDimension
字段表示数组是由行整理的值列表。
请求协议如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION
{ "range": "Sheet1!A1:E1", "majorDimension": "ROWS", "values": [ ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "3/20/2016"], ], }
响应包含一个 AppendValuesResponse
对象,如下所示:
{ "spreadsheetId":SPREADSHEET_ID
, "tableRange": "Sheet1!A1:D2", "updates": { "spreadsheetId":SPREADSHEET_ID
, "updatedRange": "Sheet1!A3:D4", "updatedRows": 2, "updatedColumns": 4, "updatedCells": 8, } }
生成的工作表如下所示:
A | B | C | D | |
1 | 商品 | 费用 | 有货 | 发货日期 |
2 | 摩天轮 | 20.50 美元 | 4 | 2016 年 3 月 1 日 |
3 | 门 | 港元 | 2 | 2016 年 3 月 15 日 |
4 | 引擎 | 港元 | 1 | 2016 年 3 月 20 日 |
5 |