智能条状标签

本指南介绍了如何以及为何使用 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：人员的电子邮件地址。

使用此属性创建富链接条状标签。虽然 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。这会将单元格中的现有条状标签替换为新条状标签。

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

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

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