Uniwersalne działania

Działania uniwersalne to elementy menu, które po wybraniu przez użytkownika umożliwiają otwarcie nowej strony internetowej, wyświetlenie nowych kart interfejsu lub uruchomienie określonej funkcji Apps Script. Działają one bardzo podobnie do działań na kartach, z tym że działania uniwersalne są zawsze umieszczane na każdej karcie w dodatku, niezależnie od bieżącego kontekstu dodatku.

Dzięki działaniom uniwersalnym możesz mieć pewność, że użytkownik zawsze ma dostęp do określonych funkcji, niezależnie od tego, z którą częścią dodatku wchodzi w interakcję. Oto kilka przykładowych zastosowań działań uniwersalnych:

  • Otwórz stronę ustawień (lub wyświetl kartę ustawień).
  • Wyświetl użytkownikowi informacje o pomocy.
  • Rozpocznij nowy przepływ pracy, np. „Dodaj nowego klienta”.
  • Wyświetl kartę, która umożliwia użytkownikowi przesłanie opinii o dodatku.

Jeśli masz działanie, które nie zależy od bieżącego kontekstu, rozważ przekształcenie go w działanie uniwersalne.

Korzystanie z działań uniwersalnych

Działania uniwersalne konfiguruje się w manifeście projektu dodatku. Po skonfigurowaniu działania uniwersalnego jest ono zawsze dostępne dla użytkowników dodatku. Jeśli użytkownik wyświetla kartę, zdefiniowany przez Ciebie zestaw działań uniwersalnych zawsze pojawia się w menu karty po wszystkich działaniach na karcie zdefiniowanych dla tej karty. Działania uniwersalne pojawiają się w menu kart w tej samej kolejności, w jakiej są zdefiniowane w manifeście dodatku.

Konfigurowanie działań uniwersalnych

Działania uniwersalne konfiguruje się w pliku manifestu dodatku. Więcej informacji znajdziesz w sekcji Pliki manifestu.

W przypadku każdego działania określasz tekst, który ma się pojawiać w menu tego działania. Następnie możesz określić pole openLink, które wskazuje, że działanie powinno bezpośrednio otwierać stronę internetową w nowej karcie. Możesz też określić pole runFunction, które zawiera funkcję zwrotną Apps Script do wykonania po wybraniu działania uniwersalnego.

Gdy używana jest funkcja runFunction, określone wywołanie zwrotne zwykle wykonuje jedną z tych czynności:

  • Tworzy karty interfejsu, które mają być wyświetlane od razu, zwracając utworzony obiekt UniversalActionResponse.
  • Otwiera adres URL, być może po wykonaniu innych zadań, zwracając utworzony obiekt UniversalActionResponse.
  • Wykonuje zadania w tle, które nie powodują przełączenia na nową kartę ani otwarcia adresu URL. W tym przypadku funkcja wywołania zwrotnego nie zwraca żadnych danych.

Po wywołaniu funkcji zwrotnej przekazywany jest do niej obiekt zdarzenia zawierający informacje o otwartej karcie i kontekście dodatku.

Przykład

Poniższy fragment kodu pokazuje przykładowy fragment pliku manifestu dodatku do Google Workspace, który korzysta z działań uniwersalnych, rozszerzając Gmaila. Kod wyraźnie 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"
        }
      ]
    },
    ...
  },
  ...

3 działania uniwersalne zdefiniowane w poprzednim przykładzie wykonują te czynności:

  • Otwórz google.com otwiera https://www.google.com w nowej karcie.
  • Open contact URL uruchamia funkcję, która określa, jaki adres URL ma zostać otwarty, a następnie otwiera go w nowej karcie za pomocą obiektu OpenLink. Kod 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 obiektUniversalActionResponse zawierający zestaw kart z ustawieniami dodatków i innymi informacjami. Gdy funkcja zakończy tworzenie tego obiektu, interfejs wyświetli listę 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. Ponieważ funkcja nie zwraca wartości UniversalActionResponse, interfejs nie wyświetla nowej karty po zakończeniu działania funkcji. Zamiast tego interfejs wyświetla wskaźnik ładowania, gdy funkcja jest uruchomiona.

Oto przykład konstrukcji 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.
}