智能条状标签

本指南介绍了如何以及为何使用 Google 表格 API 在电子表格中添加和管理智能条状标签。

什么是智能条状标签？

借助智能条状标签，您可以将其他 Google Workspace 应用中的丰富互动数据直接引入表格。智能条状标签可让用户快速访问信息和操作，将单元格链接转换为动态对象。如需了解详情，请参阅在 Google 表格中插入智能条状标签。

添加智能条状标签

条状标签以条状标签运行的形式表示，这些运行是 CellData 的一部分，因此您可以通过提供 UpdateCellsRequest 或 AppendCellsRequest，使用现有的 spreadsheets.batchUpdate 方法插入条状标签。

该请求必须包含 chipRuns 字段。条状标签运行描述了条状标签的属性及其在单元格文本中的位置。

编写 chipRuns 时，您还必须提供一个 userEnteredValue，其中包含您打算添加的每个条状标签的占位符字符 (@)。chipRuns 数组中的每个运行都将对应于其中一个占位符。在写入时，可以省略非条状标签运行。

以下示例展示了如何将文件条状标签、人员条状标签和纯文本写入单个单元格 A1。 * {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

配置条状标签属性

条状标签对象可以具有以下属性类型之一：

personProperties

使用此属性创建人员条状标签。

email：（必需）要链接的人员的电子邮件地址。
displayFormat：（可选）人员姓名的首选显示格式。可以是以下各项之一：
- DEFAULT：标准“名字姓氏”格式。
- LAST_NAME_COMMA_FIRST_NAME：“姓氏，名字”格式。
- EMAIL：人员的电子邮件地址。

richLinkProperties

使用此属性创建富链接条状标签。虽然 API 可以读取指向各种 Google 服务（例如 YouTube 或日历）的链接，但只有指向 Google 云端硬盘文件的链接可以作为条状标签写入。

uri：（必需）资源的 URI。对于写入，这必须是 Google 云端硬盘文件链接。URI 不得超过 2000 字节。

读取智能条状标签

如需读取智能条状标签的数据，请使用 spreadsheets.get 方法，并在 fields 参数中添加 sheets.data.rowData.values(chipRuns)。

响应中的 chipRuns 数组将包含单元格文本的所有子部分的对象。

条状标签运行：这些部分将包含填充的 chip 对象，其中包含 personProperties 或 richLinkProperties。
非条状标签运行：纯文本部分也将包含运行对象，但其 chip 字段将为空。

如需获取条状标签的显示文本，请添加 formattedValue 作为字段。

更新智能条状标签

如需更新或替换智能条状标签，您必须覆盖单元格的内容。使用与添加条状标签时相同的 UpdateCellsRequest 或 AppendCellsRequest，并提供新的 userEnteredValue 和 chipRun。这会将单元格中的现有条状标签替换为新条状标签。

将智能条状标签与其他表格功能搭配使用

表格：智能条状标签可用作表格列类型，以跟踪项目负责人（人员条状标签）或相关文档（文件条状标签）。

过滤条件：您可以根据范围内的智能条状标签的文本值过滤范围。