通用操作是指菜单项元素,让用户能够通过这些元素 网页、显示新的界面卡片,或在以下情况下运行特定的 Apps 脚本功能: 已选择。实际上,它们与 卡片操作、 不同的是,通用操作始终会放置在插件中的每张卡片上, 无论当前插件上下文如何。
通过使用通用操作,您可以确保用户始终有权访问 某些功能,而不管他们与插件的哪个部分交互 以下是通用操作的一些用例示例:
- 打开设置网页(或显示设置卡片)。
- 向用户显示帮助信息。
- 启动新工作流程,例如“添加新客户”。
- 显示一张卡片,让用户能够发送有关插件的反馈。
每当出现不依赖于当前上下文的操作时, 您应考虑将其纳入一项普遍适用的行动。
使用通用操作
插件的项目中配置了通用操作 manifest 的文件。配置好 通用操作,因此您插件的用户始终可以使用。如果用户 当您查看卡片时,系统会始终显示您定义的一组通用操作 (在卡片菜单中 卡片操作 您为该卡片定义的维度通用操作显示在 它们在插件清单中的定义顺序相同。
配置通用操作
在插件的清单中配置通用操作;请参阅 清单 了解详情。
对于每项操作,您都可以指定其菜单中显示的文本
操作。然后,您可以指定一个 openLink
字段,指示该操作
应直接在新标签页中打开网页。或者,您可以指定
runFunction
字段,用于指定 Apps 脚本回调函数
在选择通用操作时执行什么操作。
使用 runFunction
时,指定的回调函数通常会执行
以下项:
- 通过返回已构建的
UniversalActionResponse
对象。 - 通过返回构建的
UniversalActionResponse
对象。 - 执行不会切换到新卡片或打开网址的后台任务。 在这种情况下,回调函数不会返回任何内容。
被调用时,系统会向该回调函数传递 事件对象 包含有关打开的卡片和插件上下文的信息。
示例
以下代码段显示了 支持通用操作的 Google Workspace 插件 同时扩展 Gmail。该代码明确设置了元数据范围,以便 插件可以确定打开邮件的发件人。
"oauthScopes": [
"https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
],
"addOns": {
"common": {
"name": "Universal Actions Only Addon",
"logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
"openLinkUrlPrefixes": [
"https://www.google.com",
"https://www.example.com/urlbase"
],
"universalActions": [{
"label": "Open google.com",
"openLink": "https://www.google.com"
}, {
"label": "Open contact URL",
"runFunction": "openContactURL"
}, {
"label": "Open settings",
"runFunction": "createSettingsResponse"
}, {
"label": "Run background sync",
"runFunction": "runBackgroundSync"
}],
...
},
"gmail": {
"contextualTriggers": [
{
"unconditional": {},
"onTriggerFunction": "getContextualAddOn"
}
]
},
...
},
...
上述示例中定义的三个通用操作会执行以下操作:
- 打开 google.com 打开 https://www.google.com 打开新的标签页
- 打开联系人网址会运行一个函数来确定要打开哪个网址
然后使用
OpenLink
对象。通过 代码使用发件人的电子邮件地址构建网址。 - 打开设置会运行在
createSettingsCards()
插件脚本项目。此函数会返回一个有效的UniversalActionResponse
对象包含一组具有插件设置和其他信息的卡片。 函数构建完此对象后,界面会显示列表 卡片数量(请参阅 返回多张卡片)。 - 运行后台同步:运行在
runBackgroundSync()
插件脚本项目。此函数不会构建卡片;取而代之的是 可执行一些不会更改界面的其他后台任务。由于 函数不会返回UniversalActionResponse
, 函数完成时,界面不会显示新卡片。取而代之的是, 当函数运行时,界面会显示一个加载指示器旋转图标。
以下示例展示了如何构建 openContactURL()
。
createSettingsResponse()
和 runBackgroundSync()
函数:
/**
* Open a contact URL.
* @param {Object} e an event object
* @return {UniversalActionResponse}
*/
function openContactURL(e) {
// Activate temporary Gmail scopes, in this case so that the
// open message metadata can be read.
var accessToken = e.gmail.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);
// Build URL to open based on a base URL and the sender's email.
// This URL must be included in the openLinkUrlPrefixes whitelist.
var messageId = e.gmail.messageId;
var message = GmailApp.getMessageById(messageId);
var sender = message.getFrom();
var url = "https://www.example.com/urlbase/" + sender;
return CardService.newUniversalActionResponseBuilder()
.setOpenLink(CardService.newOpenLink()
.setUrl(url))
.build();
}
/**
* Create a collection of cards to control the add-on settings and
* present other information. These cards are displayed in a list when
* the user selects the associated "Open settings" universal action.
*
* @param {Object} e an event object
* @return {UniversalActionResponse}
*/
function createSettingsResponse(e) {
return CardService.newUniversalActionResponseBuilder()
.displayAddOnCards(
[createSettingCard(), createAboutCard()])
.build();
}
/**
* Create and return a built settings card.
* @return {Card}
*/
function createSettingCard() {
return CardService.newCardBuilder()
.setHeader(CardService.newCardHeader().setTitle('Settings'))
.addSection(CardService.newCardSection()
.addWidget(CardService.newSelectionInput()
.setType(CardService.SelectionInputType.CHECK_BOX)
.addItem("Ask before deleting contact", "contact", false)
.addItem("Ask before deleting cache", "cache", false)
.addItem("Preserve contact ID after deletion", "contactId", false))
// ... continue adding widgets or other sections here ...
).build(); // Don't forget to build the card!
}
/**
* Create and return a built 'About' informational card.
* @return {Card}
*/
function createAboutCard() {
return CardService.newCardBuilder()
.setHeader(CardService.newCardHeader().setTitle('About'))
.addSection(CardService.newCardSection()
.addWidget(CardService.newTextParagraph()
.setText('This add-on manages contact information. For more '
+ 'details see the <a href="https://www.example.com/help">'
+ 'help page</a>.'))
// ... add other information widgets or sections here ...
).build(); // Don't forget to build the card!
}
/**
* Run background tasks, none of which should alter the UI.
* Also records the time of sync in the script properties.
*
* @param {Object} e an event object
*/
function runBackgroundSync(e) {
var props = PropertiesService.getUserProperties();
props.setProperty("syncTime", new Date().toString());
syncWithContacts(); // Not shown.
updateCache(); // Not shown.
validate(); // Not shown.
// no return value tells the UI to keep showing the current card.
}