此页面由 Cloud Translation API 翻译。

基本书写

借助 Google Sheets API，您可以向单元格、范围、范围和整个工作表。本页中的示例说明了可以使用 spreadsheets.values 。

请注意，也可以使用 spreadsheet.batchUpdate 方法，这适用于您希望同时更新单元格格式或其他属性 spreadsheets.values 则不受影响。例如，如果您想从将一个工作表移到另一个工作表，同时覆盖单元格公式和单元格格式，您可以使用 UpdateCellsRequest 方法，其中包含 spreadsheet.batchUpdate。

不过，对于简单的值写入，使用 spreadsheets.values.update 方法或 spreadsheets.values.batchUpdate 方法。

这些示例以 HTTP 请求的形式呈现，中性。了解如何使用 Google API 客户端库，请参阅阅读和写入单元格值。

在这些示例中，占位符 SPREADSHEET_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