基本书写

借助 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