本页介绍了如何构建 Google Workspace 插件,以便 Google 文档、表格和幻灯片用户预览第三方服务的链接。
Google Workspace 插件可以检测服务的链接并提示用户预览这些链接。您可以配置插件以预览多种网址格式,例如支持案例、潜在客户和员工个人资料的链接。
用户如何预览链接
为了预览链接,用户可以与智能条状标签和卡片互动。
当用户在文档中输入或粘贴网址时,Google 文档会提示他们将链接替换为智能条状标签。智能条状标签会显示一个图标以及链接内容的简短标题或说明。当用户将光标悬停在条状标签上时,会看到一个卡片界面,该界面可预览有关文件或链接的更多信息。
以下视频展示了如何将链接转换为智能条状标签并预览卡片:
用户如何在表格和幻灯片中预览链接
表格和幻灯片中的链接预览的开发者预览版不支持第三方智能条状标签。当用户在电子表格或演示文稿中输入或粘贴网址时,Google 表格或幻灯片会提示他们将链接替换为链接文本(而不是条状标签)。当用户将鼠标悬停在链接标题上时,会看到一个卡片界面,其中预览了链接的相关信息。
下图显示了链接预览在 Google 表格和幻灯片中的呈现方式:
前提条件
Apps 脚本
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此quickstart进行操作。
Node.js
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此quickstart进行操作。
Python
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此quickstart进行操作。
Java
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此quickstart进行操作。
可选:设置针对第三方服务的身份验证
如果您的插件连接到需要授权的服务,则用户必须向该服务进行身份验证才能预览链接。这意味着,当用户首次将服务中的链接粘贴到 Google 文档、表格或幻灯片文件中时,您的插件必须调用授权流程。
如需设置 OAuth 服务或自定义授权提示,请参阅以下指南之一:
如果您使用 Apps 脚本构建插件,请参阅从 Google Workspace 插件连接到非 Google 服务。
如果您使用其他运行时构建插件,请参阅将插件连接到第三方服务。
为您的插件设置链接预览
本部分介绍了如何为插件设置链接预览,其中包括以下步骤:
- 在插件的部署资源或清单文件中配置链接预览。
- 为您的链接构建智能条状标签和卡片界面。
配置链接预览
要配置链接预览,请在插件的部署资源或清单文件中指定以下部分和字段:
- 在
addOns
部分下,添加docs
字段以扩展 Google 文档,添加sheets
字段以扩展 Google 表格,添加slides
字段以扩展幻灯片。 在每个字段中,实现包含
runFunction
的linkPreviewTriggers
触发器(您可以在下一部分构建智能条状标签和卡片中定义此函数)。如需了解您可以在
linkPreviewTriggers
触发器中指定的字段,请参阅 Apps 脚本清单文件或其他运行时的部署资源的参考文档。在
oauthScopes
字段中,添加范围https://www.googleapis.com/auth/workspace.linkpreview
,以便用户可以授权该插件代表自己预览链接。
例如,以下部署资源的 oauthScopes
和 addons
部分用于为支持请求服务配置链接预览。
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
},
"sheets": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
},
"slides": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
在此示例中,Google Workspace 插件会预览公司支持请求服务的链接。该插件指定了三种用于预览链接的网址格式。每当链接与其中一个网址格式匹配时,回调函数 caseLinkPreview
都会构建并显示卡片和智能条状标签,或者,在 Google 表格和幻灯片中,会将网址替换为链接标题。
构建智能芯片和卡片
如需为链接返回智能条状标签和卡片,您必须实现在 linkPreviewTriggers
对象中指定的所有函数。
当用户与符合指定网址格式的链接互动时,会触发 linkPreviewTriggers
触发器,其回调函数会将事件对象 EDITOR_NAME.matchedUrl.url
作为参数传递。您可以使用此事件对象的载荷为链接预览构建智能条状标签和卡片。
例如,对于指定 Google 文档网址格式 example.com/cases
的插件,如果用户预览链接 https://www.example.com/cases/123456
,系统会返回以下事件载荷:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
如需创建卡片界面,您需要使用 widget 来显示链接的相关信息。您还可以构建操作来允许用户打开链接或修改其内容。如需查看可用 widget 和操作的列表,请参阅预览卡片支持的组件。
如需构建用于链接预览的智能条状标签和卡片,请执行以下操作:
- 实现您在插件部署资源或清单文件的
linkPreviewTriggers
部分中指定的函数:- 该函数必须接受包含
EDITOR_NAME.matchedUrl.url
的事件对象作为参数,并返回单个Card
对象。 - 如果您的服务需要授权,该函数还必须调用授权流程。
- 该函数必须接受包含
- 对于每张预览卡片,请实现所有可为接口提供 widget 互动性的回调函数。例如,如果您添加一个显示“查看链接”的按钮,则可以创建一个操作,用于指定一个回调函数,以便在新窗口中打开链接。如需详细了解 widget 交互,请参阅插件操作。
以下代码会为 Google 文档创建回调函数 caseLinkPreview
:
Apps 脚本
Node.js
Python
Java
预览卡片支持的组件
Google Workspace 插件支持在链接预览卡片中使用以下微件和操作:
Apps 脚本
“Card Service”字段 | 类型 |
---|---|
TextParagraph |
widget |
DecoratedText |
widget |
Image |
widget |
IconImage |
widget |
ButtonSet |
widget |
TextButton |
widget |
ImageButton |
widget |
Grid |
widget |
Divider |
widget |
OpenLink |
操作 |
Navigation |
操作 。仅支持 updateCard 方法。 |
JSON
卡片 (google.apps.card.v1 ) 字段 |
类型 |
---|---|
TextParagraph |
widget |
DecoratedText |
widget |
Image |
widget |
Icon |
widget |
ButtonList |
widget |
Button |
widget |
Grid |
widget |
Divider |
widget |
OpenLink |
操作 |
Navigation |
操作 。仅支持 updateCard 方法。 |
完整示例:支持请求插件
以下示例展示了一个 Google Workspace 插件,该插件可在 Google 文档中预览指向公司支持请求和员工个人资料的链接。
该示例执行以下操作:
- 预览支持请求的链接,例如
https://www.example.com/support/cases/1234
。智能条状标签会显示一个支持图标,预览卡片包含支持请求 ID 和说明。 - 预览指向支持请求代理(例如
https://www.example.com/people/rosario-cruz
)的链接。智能条状标签会显示一个人形图标,预览卡片上包含员工的姓名、电子邮件地址、职位和个人资料照片。 - 如果用户的语言区域设置为西班牙语,智能条状标签会将其
labelText
本地化为西班牙语。
Deployment 资源
Apps 脚本
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}