借助 Google Sheets API，您可以将值和公式写入单元格、范围、一组范围和整个工作表。本页面的示例展示了如何使用 Google 表格 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 | 门 | $15 | 2 | 2016 年 3 月 15 日 |
| 4 | 引擎 | $100 | 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 | 门 | $15 | 2 | 2016 年 3 月 15 日 |
| 4 | 引擎 | $100 | 1 | 2016 年 3 月 20 日 |
| 5 |