Uniwersalne działania

Działania uniwersalne to elementy menu, które pozwalają użytkownikowi otworzyć nową stronę internetową, wyświetlić nowe karty interfejsu lub uruchomić określoną funkcję Apps Script, gdy jest zaznaczona. W działaniu są one bardzo podobne do działań karty z tą różnicą, że uniwersalne akcje są zawsze umieszczane na każdej karcie w dodatku, niezależnie od jego kontekstu.

Korzystając z działań uniwersalnych, możesz sprawić, że użytkownik zawsze będzie miał dostęp do określonych funkcji niezależnie od tego, z którą częścią dodatku wejdzie w interakcję. 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.

Za każdym razem, gdy jakaś czynność nie zależy od bieżącego kontekstu, zastanów się, czy nie jest to działanie uniwersalne.

Korzystanie z działań uniwersalnych

Działania uniwersalne są skonfigurowane w pliku manifestu projektu dodatku. Po skonfigurowaniu działania uniwersalnego będzie ono zawsze dostępne dla użytkowników Twojego dodatku. Jeśli użytkownik wyświetla kartę, zdefiniowane przez Ciebie działania uniwersalne zawsze pojawiają się w menu karty po wszystkich określonych przez Ciebie działaniach karty. Działania uniwersalne pojawiają się w menu karty 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. Więcej informacji znajdziesz w sekcji Pliki manifestu.

Dla każdej czynności określasz tekst, który ma się wyświetlać w menu czynności. Następnie możesz określić pole openLink wskazujące, że działanie powinno bezpośrednio otworzyć stronę internetową w nowej karcie. Możesz też określić pole runFunction, które określa funkcję wywołania zwrotnego Apps Script, która ma być wykonywana po wybraniu działania uniwersalnego.

Gdy używana jest funkcja runFunction, określona funkcja wywołania zwrotnego zwykle wykonuje jedną z tych czynności:

• Tworzy karty interfejsu do wyświetlenia natychmiast przez zwrócenie utworzonego obiektu UniversalActionResponse.
• Otwiera adres URL, być może po wykonaniu innych zadań, przez zwrócenie skompilowanego obiektu UniversalActionResponse.
• 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 wywołaniu funkcja wywołania zwrotnego jest przekazywana do obiektu zdarzenia zawierającego informacje o otwartej karcie i kontekście dodatku.

Przykład

Ten fragment kodu zawiera przykładowy fragment pliku manifestu dla dodatku do Google Workspace, który używa działań uniwersalnych przy jednoczesnym rozszerzeniu Gmaila. Kod bezpośrednio ustawia zakres metadanych, aby dodatek mógł 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 – strona https://www.google.com otwiera się w nowej karcie.
• Otwórz adres URL kontaktu uruchamia funkcję, która określa adres URL do otworzenia i otwiera go w nowej karcie za pomocą obiektu OpenLink. Kod tworzy adres URL na podstawie adresu e-mail nadawcy.
• Otwórz ustawienia – uruchamia funkcję createSettingsCards() zdefiniowaną w projekcie skryptu dodatkowego. Ta funkcja zwraca prawidłowy obiekt UniversalActionResponse zawierający zbiór kart z ustawieniem dodatku i inne informacje. Gdy funkcja zakończy kompilowanie tego obiektu, w interfejsie pojawi się lista kart (patrz Zwracanie wielu kart).
• Uruchom synchronizację w tle – uruchamia funkcję runBackgroundSync() zdefiniowaną w projekcie skryptu dodatku. Ta funkcja nie tworzy kart. Zamiast tego wykonuje w tle pewne inne zadania, które nie zmieniają interfejsu użytkownika. Funkcja nie zwraca UniversalActionResponse, więc interfejs użytkownika nie wyświetla nowej karty po jej zakończeniu. Zamiast tego podczas działania funkcji interfejs wyświetla wskaźnik postępu ładowania.

Oto przykład tworzenia funkcji openContactURL(), 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.
}