本页介绍了如何构建可让 Google 文档用户预览第三方服务链接的 Google Workspace 插件。
Google Workspace 插件可以检测服务的链接,并提示 Google 文档用户进行预览。您可以配置插件以预览多个网址格式,例如支持请求链接、潜在客户信息和员工个人资料链接。
用户如何预览链接
要预览 Google 文档文档中的链接,用户与智能条状标签和卡片进行互动:
当用户将网址输入或粘贴到文档中时,Google 文档会提示用户将链接替换为智能条状标签。智能条状标签会显示链接内容的图标和短标题或说明。当用户将光标悬停在条状标签上时,就会看到一个卡片界面,其中会显示有关文件或链接的更多信息。
以下视频展示了用户如何将链接转换为智能条状标签并预览卡片:
前提条件
Apps 脚本
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此快速入门中的说明操作。
Node.js
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此快速入门中的说明操作。
Python
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此快速入门中的说明操作。
Java
- Google Workspace 帐号。
- Google Workspace 插件。如需构建插件,请按照此快速入门中的说明操作。
可选:设置发送到第三方服务的身份验证
如果您的插件连接到需要授权的服务,则用户必须向该服务进行身份验证才能预览链接。这意味着,当用户首次将服务中的链接粘贴到 Google 文档文档中时,您的插件必须调用授权流程。
如需设置 OAuth 服务或自定义授权提示,请参阅以下指南之一:
如果您使用 Apps 脚本构建了插件,请参阅从 Google Workspace 插件连接到非 Google 服务。
如果您使用其他运行时构建了插件,请参阅将插件与第三方服务相关联。
为插件设置链接预览
本部分介绍了如何为插件设置链接预览,包括以下步骤:
- 在插件的部署资源或清单文件中配置链接预览。
- 为您的链接构建智能条状标签和卡片界面。
配置链接预览
如需配置链接预览,请在插件的部署资源或清单文件中指定以下部分和字段:
- 在
addOns
部分下,添加docs
字段以扩展 Google 文档。 在
docs
字段中,实现包含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"
}
}
]
}
}
}
在本示例中,Google Workspace 插件会预览公司的支持请求服务的链接。该插件指定用于预览链接的三种网址格式。每当链接与 Google 文档文档中的某个网址格式匹配时,回调函数 caseLinkPreview
都会构建并显示智能条状标签和卡片。
构建智能条状标签和卡片
如需返回链接的智能条状标签和卡片,您必须实现您在 linkPreviewTriggers
对象中指定的任何函数。
当用户与与指定网址格式匹配的链接互动时,系统会触发 linkPreviewTriggers
触发器,并且其回调函数会将事件对象 docs.matchedUrl.url
作为参数传递。您将使用此事件对象的载荷来构建智能条状标签和卡片,以用于链接预览。
例如,对于指定网址格式 example.com/cases
的插件,如果用户预览链接 https://www.example.com/cases/123456
,则系统会返回以下事件载荷:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
如需创建卡片界面,请使用 widget 显示该链接的相关信息。您还可以构建操作,使用户能够打开链接或修改其内容。如需查看可用的 widget 和操作列表,请参阅预览卡片支持的组件。
如需构建智能条状标签和卡片以进行链接预览,请执行以下操作:
- 实现您在插件的部署资源或清单文件的
linkPreviewTriggers
部分中指定的函数:- 该函数必须接受包含
docs.matchedUrl.url
作为参数的事件对象,并返回单个Card
对象。 - 如果您的服务需要授权,该函数还必须调用授权流程。
- 该函数必须接受包含
- 对于每张预览卡片,请实现所有为界面提供 widget 互动功能的回调函数。例如,如果您添加了内容为“查看链接”的按钮,则可以创建一个用于指定回调函数的操作,用于在新窗口中打开链接。如需详细了解 widget 交互,请参阅插件操作。
以下代码会创建回调函数 caseLinkPreview
:
Apps 脚本
Node.js
Python
Java
预览卡片支持的组件
对于链接预览卡片,Google Workspace 插件支持以下微件和操作:
Apps 脚本
Card Service 字段 | 类型 |
---|---|
TextParagraph |
微件 |
DecoratedText |
微件 |
Image |
微件 |
IconImage |
微件 |
ButtonSet |
微件 |
TextButton |
微件 |
ImageButton |
微件 |
Grid |
微件 |
Divider |
微件 |
OpenLink |
操作 |
Navigation |
操作 仅支持 updateCard 方法。 |
JSON
卡片 (google.apps.card.v1 ) 字段 |
类型 |
---|---|
TextParagraph |
微件 |
DecoratedText |
微件 |
Image |
微件 |
Icon |
微件 |
ButtonList |
微件 |
Button |
微件 |
Grid |
微件 |
Divider |
微件 |
OpenLink |
操作 |
Navigation |
操作 仅支持 updateCard 方法。 |
完整示例:支持请求插件
以下示例展示了一个 Google Workspace 插件,可用于预览指向公司的支持请求和员工个人资料的链接。
该示例执行以下操作:
- 预览链接至支持案例,例如
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"
}
]
}
}
}