Działania uniwersalne to elementy menu, które umożliwiają użytkownikowi otwarcie strony internetowej, wyświetlanie nowych kart interfejsu lub uruchamianie określonej funkcji Apps Script, zaznaczono. W działaniu są bardzo podobne do działania kart, z tą różnicą, że uniwersalne działania są zawsze umieszczane na każdej karcie dodatku, niezależnie od bieżącego kontekstu dodatku.
Korzystając z działań uniwersalnych, możesz zapewnić użytkownikowi stały dostęp do tych informacji: określonych funkcji niezależnie od tego, z której części dodatku wchodzą w interakcję. z naszymi usługami. Oto kilka przykładów użycia działań uniwersalnych:
- Otwórz stronę ustawień (lub wyświetl kartę ustawień).
- Pokaż użytkownikowi informacje pomocy.
- Rozpocznij nowy przepływ pracy, na przykład „Dodaj nowego klienta”.
- Wyświetl kartę, która pozwala użytkownikowi przesłać opinię o dodatku.
Jeśli jakaś czynność nie zależy od bieżącego kontekstu, warto rozważyć działanie uniwersalne.
Korzystanie z działań uniwersalnych
Działania uniwersalne są skonfigurowane w projekcie dodatku manifest. Po skonfigurowaniu działania uniwersalnego, jest ona zawsze dostępna dla użytkowników Twojego dodatku. Jeśli użytkownik wyświetla kartę, zawsze pojawia się zestaw zdefiniowanych przez Ciebie działań uniwersalnych w menu karty, po elemencie działania na karcie zdefiniowane dla tej karty. Działania uniwersalne pojawiają się w menu kart w sekcji w tej samej kolejności, w jakiej są zdefiniowane w pliku manifestu dodatku.
Konfigurowanie działań uniwersalnych
Działania uniwersalne konfigurujesz w pliku manifestu dodatku. zobacz Pliki manifestu .
Dla każdej czynności określasz tekst, który ma być widoczny w menu danego działania
działania. Następnie możesz określić pole openLink
wskazujące, że działanie
powinien otworzyć bezpośrednio stronę internetową w nowej karcie. Możesz też określić
pole runFunction
, które określa funkcję wywołania zwrotnego Apps Script do
jest wykonywane po wybraniu działania uniwersalnego.
Gdy używana jest funkcja runFunction
, określona funkcja wywołania zwrotnego zwykle ją wykonuje
spośród następujących:
- Tworzy karty interfejsu, które wyświetlają się natychmiast przez zwrócenie kompilacji
UniversalActionResponse
obiektu. - Otwiera adres URL, np. po wykonaniu innych zadań, przez zwrócenie kompilacji
UniversalActionResponse
obiekt. - Wykonuje zadania w tle, które nie przełączają się na nową kartę ani nie otwierają adresu URL. W takim przypadku funkcja wywołania zwrotnego nie zwraca niczego.
Po jej wywołaniu funkcja wywołania zwrotnego jest przekazywana w obiekt zdarzenia który zawiera informacje o otwartej karcie i kontekście dodatku.
Przykład
Ten fragment kodu zawiera przykładowy fragment pliku manifestu dla Dodatek do Google Workspace, który używa działań uniwersalnych rozszerzenie Gmaila. Kod bezpośrednio ustawia zakres metadanych, aby pozwalają określić, kto wysłał otwartą wiadomość.
"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"
}
]
},
...
},
...
Trzy uniwersalne działania zdefiniowane w poprzednim przykładzie są wykonywane w taki sposób:
- Otwórz google.com, otwiera https://www.google.com w nową kartę.
- Otwórz adres URL kontaktu uruchamia funkcję, która określa adres URL do otwarcia.
i otwiera ją w nowej karcie za pomocą
OpenLink
. tworzy adres URL na podstawie adresu e-mail nadawcy. - Otwórz ustawienia – uruchamia funkcję
createSettingsCards()
zdefiniowaną w w projekcie skryptu. Ta funkcja zwraca prawidłową wartośćUniversalActionResponse
zawierający zestaw kart z ustawieniem dodatku i innymi informacjami. Gdy funkcja zakończy kompilowanie tego obiektu, w interfejsie wyświetli się lista kart (patrz Zwracanie wielu kart). - Uruchom synchronizację w tle – uruchamia funkcję
runBackgroundSync()
zdefiniowaną w projektu dodatkowego. Ta funkcja nie tworzy kart. zamiast tego wykonuje inne działania w tle, które nie zmieniają interfejsu użytkownika. Ponieważ funkcja nie zwracaUniversalActionResponse
, interfejs nie wyświetla nowej karty po zakończeniu działania funkcji. Zamiast tego Interfejs użytkownika wyświetla wskaźnik postępu ładowania, gdy funkcja jest uruchomiona.
Oto przykład, w jaki sposób można utworzyć openContactURL()
,
Funkcje createSettingsResponse()
i 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.
}