本指南介绍了如何以及为何使用 Google 表格 API 在电子表格中添加和管理智能条状标签。
什么是智能条状标签？
借助智能条状标签，您可以将其他 Google Workspace 应用中丰富的交互式数据直接导入 Google 表格。智能条状标签可让用户快速访问信息和操作，将单元格链接转换为动态对象。如需了解详情，请参阅在 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。 - 未嵌入条状标签的运行：纯文本部分也将包含一个 run 对象，但其
chip字段将为空。
如需获取条状标签的显示文本，请将 formattedValue 添加为字段。
更新智能条状标签
如需更新或替换智能条状标签，您必须覆盖单元格的内容。使用与添加条状标签相同的 UpdateCellsRequest 或 AppendCellsRequest，提供新的 userEnteredValue 和 chipRun。这将替换单元格中的现有条状标签。
将智能条状标签与其他 Google 表格功能搭配使用
表格：智能条状标签可用作表格列类型，用于跟踪项目所有者（“人员”条状标签）或相关文档（“文件”条状标签）。
过滤器：您可以根据范围内智能条状标签的文本值过滤范围。