Uniwersalne działania

Działania uniwersalne to elementy menu, które umożliwiają użytkownikowi otwarcie strony internetowej, wyświetlać nowe karty interfejsu lub uruchamiać określoną funkcję 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, należy rozważyć działanie uniwersalne.

Korzystanie z działań uniwersalnych

Działania uniwersalne są skonfigurowane w projekcie dodatku manifest. Po skonfigurowaniu działanie uniwersalne, 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 dowolnym 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 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 zwraca UniversalActionResponse 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.
}