Uniwersalne działania

Uniwersalne działania to elementy elementów menu, które umożliwiają użytkownikowi otwieranie nowych stron internetowych, wyświetlanie nowych kart interfejsu lub uruchamianie określonej funkcji Apps Script. Ich działanie jest bardzo podobne do czynności na karcie, z tą różnicą, ż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 zapewnić użytkownikowi stały dostęp do określonych funkcji niezależnie od tego, z której części dodatku korzysta. Oto kilka przykładowych zastosowań działań uniwersalnych:

  • Otwórz stronę ustawień (lub wyświetl kartę ustawień).
  • wyświetlać użytkownikowi informacje o pomocy.
  • Uruchom nowy przepływ pracy, np. „Dodaj nowego klienta”.
  • wyświetlić kartę, która pozwala użytkownikowi przesłać opinię na temat dodatku;

Jeśli masz działanie, które nie zależy od bieżącego kontekstu, rozważ uczynienie go uniwersalnym.

Korzystanie z działań uniwersalnych

Działania uniwersalne są konfigurowane w pliku manifestu projektu dodatku. Po skonfigurowaniu uniwersalnego działania 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 czynnościach zdefiniowanych dla tej karty. Działania uniwersalne są widoczne w menu kart w tej samej kolejności, w jakiej zostały zdefiniowane w manifeście dodatku.

Konfigurowanie działań uniwersalnych

Uniwersalne działania konfigurujesz w pliku manifestu dodatku. Więcej informacji znajdziesz w artykule Pliki manifestu.

W przypadku każdego działania określasz tekst, który ma się wyświetlać w menu tego działania. Następnie możesz określić pole openLink, aby wskazać, że działanie powinno bezpośrednio otworzyć stronę internetową w nowej karcie. Możesz też podać pole runFunction, które określa funkcję wywołania zwrotnego Apps Script do wykonania po wybraniu działania uniwersalnego.

Gdy używasz funkcji runFunction, wywołanie zwrotne zwykle wykonuje jedną z tych czynności:

  • Tworzy karty interfejsu użytkownika, aby wyświetlić je natychmiast, zwracając utworzony obiekt UniversalActionResponse.
  • Otwiera adres URL, być może po wykonaniu innych zadań, zwracając 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 nic.

Gdy zostanie wywołana, funkcji wywołania zwrotnego zostanie przekazany obiekt zdarzenia zawierający informacje o otwartej karcie i kontekście dodatku.

Przykład

Ten fragment kodu pokazuje przykładowy fragment pliku manifestu dodatku Google Workspace, który używa działań uniwersalnych, rozszerzając jednocześnie Gmaila. Kod wyraźnie określa zakres metadanych, aby wtyczka mogła 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 uniwersalne działania zdefiniowane w poprzednim przykładzie:

  • Otwórz google.com otwiera stronę https://www.google.com w nowej karcie.
  • Otwórz adres URL kontaktu uruchamia funkcję, która określa, jaki adres URL otworzyć, a następnie otwiera go w nowej karcie za pomocą obiektu OpenLink. Kod generuje adres URL na podstawie adresu e-mail nadawcy.
  • Otwórz ustawienia uruchamia funkcję createSettingsCards() zdefiniowaną w projekcie skryptu dodatku. Ta funkcja zwraca prawidłowy obiekt UniversalActionResponse zawierający zestaw kart z ustawieniem dodatku 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, ale wykonuje inne zadania w tle, które nie zmieniają interfejsu użytkownika. Ponieważ funkcja nie zwracaUniversalActionResponse, interfejs użytkownika nie wyświetla nowej karty po zakończeniu działania funkcji. Zamiast tego interfejs wyświetla wskaźnik ładowania, gdy funkcja jest wykonywana.

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