通用動作是選單項目元素,可讓使用者開啟新的 網頁、顯示新的 UI 卡片,或在擷取作業通知時,執行特定的 Apps Script 函式 已選取。執行時非常類似 資訊卡動作 但通用動作一律會顯示在外掛程式的每張卡片上 無論目前的加購內容為何
透過通用動作 特定功能,無論這些外掛程式互動的哪個部分 。以下是通用動作的幾個應用實例:
- 開啟設定網頁 (或顯示設定資訊卡)。
- 向使用者顯示說明資訊。
- 開始新的工作流程,例如「新增客戶」。
- 顯示資訊卡,讓使用者針對這個外掛程式提供意見。
當您執行的動作不需依賴目前情境 建議將目標對象納入全球
使用通用動作
通用動作是在外掛程式專案中設定 manifest。設定好 通用動作,則一律可供外掛程式的使用者使用。如果使用者 正在查看資訊卡,您定義的通用動作集永遠會顯示 資訊卡選單中 資訊卡動作 您設定的資訊卡通用動作會顯示在 和外掛程式資訊清單中定義的順序相同。
設定通用動作
您可以在外掛程式的資訊清單中設定通用動作。看 資訊清單 ,掌握更多詳細資訊。
您可以指定每個動作的選單文字
動作。接著,您可以指定 openLink
欄位來指出該動作
應該會直接在新分頁中開啟網頁。另外,您也能指定
runFunction
欄位,用來指定 Apps Script 回呼函式
請選取通用動作時執行
使用 runFunction
時,指定的回呼函式通常會執行
下列項目:
- 藉由傳回建構完成,建構立即顯示的 UI 資訊卡
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
物件,包含一組含有外掛程式設定和其他資訊的資訊卡。 函式完成建構這個物件後,UI 會顯示清單 資訊卡 (請參閱 退回多張卡片)。 - 執行背景同步處理會執行
runBackgroundSync()
外掛程式指令碼專案。這個函式不會建構資訊卡;相反地 會執行其他不會變更 UI 的背景工作。由於 函式不會傳回UniversalActionResponse
, 當函式完成時,UI 不會顯示新卡片。請改以 當函式執行時,UI 會顯示載入指標的旋轉圖示。
以下舉例說明如何建構 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.
}