智能条状标签

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

什么是智能条状标签？

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

添加智能条状标签

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

请求必须包含 chipRuns 字段。芯片运行描述了芯片的属性以及它在单元格文本中的位置。

编写 chipRuns 时，您还必须提供一个 userEnteredValue，其中包含您打算添加的每个 chip 的占位字符 (@)。chipRuns 数组中的每次运行都将对应于一个占位变量。在写入时可以省略非芯片跑步数据。

以下示例展示了如何将文件 chip、人员 chip 和纯文本写入单个单元格 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 日历）的链接，但只有指向 Google 云端硬盘文件的链接可以作为功能块写入。

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

读取智能条状标签

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

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

  • 分段跑步：这些部分将包含一个已填充的 chip 对象，其中包含 personProperties 或 richLinkProperties。
  • 非分块运行：纯文本部分也会有一个运行对象，但其 chip 字段将为空。

如需获取功能块的显示文本，请添加 formattedValue 作为字段。

更新智能条状标签

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

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

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

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