Uniwersalne działania

Działania uniwersalne to elementy menu, które umożliwiają użytkownikowi otwarcie nowej strony internetowej, wyświetlenie nowych kart interfejsu lub uruchomienie określonej funkcji Apps Script po jej wybraniu. W trakcie działania te działania są bardzo podobne do działań związanych z kartą. Różnica polega na tym, że działania uniwersalne są zawsze umieszczane na każdej karcie w dodatku, niezależnie od bieżącego kontekstu dodatku.

Wykorzystując działania uniwersalne, zyskujesz pewność, że użytkownik ma zawsze dostęp do określonych funkcji, niezależnie od tego, z której części dodatku korzysta. 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 proces, np. „Dodaj nowego klienta”.
  • Wyświetl kartę, na której użytkownik może przesłać opinię o dodatku.

Gdy wykonujesz działanie, które nie jest zależne od bieżącego kontekstu, zastanów się nad przekształceniem go w działanie uniwersalne.

Korzystanie z działań uniwersalnych

Działania uniwersalne są konfigurowane w pliku manifestu projektu dodatku. Gdy skonfigurujesz działanie uniwersalne, będzie ono zawsze dostępne dla użytkowników Twojego dodatku. Jeśli użytkownik wyświetla kartę, zdefiniowany przez Ciebie zestaw działań uniwersalnych zawsze pojawia się w menu karty, po wszelkich działaniach związanych z kartą zdefiniowanych dla tej karty. Działania uniwersalne pojawiają się w menu karty w takiej 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 plikach manifestu.

Przy każdym działaniu musisz określić tekst, który będzie widoczny w menu danej 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 określające funkcję wywołania zwrotnego Apps Script do wykonania po wybraniu działania uniwersalnego.

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

  • Tworzy karty interfejsu do wyświetlenia od razu, zwracając skompilowany obiekt UniversalActionResponse.
  • Otwiera adres URL, np. 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 zwróci niczego.

Po wywołaniu funkcja wywołania zwrotnego jest przekazywana obiektem zdarzenia zawierającym informacje o otwartej karcie i kontekście dodatku.

Przykład

Poniższy fragment kodu zawiera przykładowy fragment pliku manifestu dodatku do Google Workspace, który wykorzystuje działania uniwersalne, jednocześnie rozszerzając Gmaila. Kod wyraźnie ustawia zakres metadanych, tak 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 działania uniwersalne zdefiniowane w poprzednim przykładzie są następujące:

  • Otwórz google.com – w nowej karcie otworzy się strona https://www.google.com.
  • Otwórz adres URL kontaktu uruchamia funkcję określającą, który adres URL ma zostać otwarty, a potem otwiera go w nowej karcie za pomocą obiektu OpenLink. Kod ten tworzy adres URL przy użyciu adresu e-mail nadawcy.
  • Otwórz ustawienia uruchamia funkcję createSettingsCards() zdefiniowaną w projekcie skryptu dodatku. Ta funkcja zwraca prawidłowy obiekt UniversalActionResponse zawierający zbiór kart z ustawieniem dodatku i innymi informacjami. Gdy funkcja zakończy tworzenie 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, tylko wykonuje inne zadania w tle, które nie zmieniają interfejsu użytkownika. Ta funkcja nie zwraca UniversalActionResponse, więc po jej zakończeniu w interfejsie użytkownika nie pojawi się nowa karta. Zamiast tego, gdy funkcja jest uruchomiona, interfejs wyświetla wskaźnik ł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.
}