本页面介绍如何构建 Google Workspace 插件,以便 Google 文档用户能够预览来自第三方服务的链接。
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 互动性的回调函数。例如,如果您添加一个显示“查看链接”的按钮,则可以创建一个操作,用于指定可在新窗口中打开链接的回调函数。如需详细了解微件互动,请参阅插件操作。
以下代码会创建回调函数 caseLinkPreview
:
Apps 脚本
Node.js
Python
Java
预览卡片支持的组件
对于链接预览卡片,Google Workspace 插件支持以下 widget 和操作:
Apps 脚本
“银行卡服务”字段 | 类型 |
---|---|
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 插件,该插件可以预览指向公司支持请求和员工个人资料的链接。
该示例执行以下操作:
- 预览链接,指向支持案例,例如
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"
}
]
}
}
}