Rozszerzenie interfejsu tworzenia wiadomości za pomocą działań tworzenia wiadomości.

Oprócz interfejsu opartego na kartach, który jest dostępny, gdy użytkownik czyta wiadomość w Gmailu, dodatki Google Workspace rozszerzające Gmaila mogą udostępniać inny interfejs, gdy użytkownik tworzy nowe wiadomości lub odpowiada na istniejące. Dzięki temu dodatki Google Workspace mogą automatyzować tworzenie e-maili dla użytkownika.

Otwieranie interfejsu tworzenia dodatku

Interfejs tworzenia dodatku możesz wyświetlić na 2 sposoby. Pierwszym sposobem jest rozpoczęcie tworzenia nowej wersji roboczej lub odpowiedzi, gdy dodatek jest już otwarty. Drugi sposób to uruchomienie dodatku podczas tworzenia wersji roboczej.

W obu przypadkach dodatek wykona odpowiednią funkcję komponowania aktywatora zdefiniowaną w pliku manifestu dodatku. Funkcja reguły tworzenia tworzy interfejs tworzenia dla danego działania, które Gmail wyświetla użytkownikowi.

Tworzenie dodatku do tworzenia wiadomości

Aby dodać do dodatku funkcję tworzenia, wykonaj te ogólne czynności:

1. Dodaj pole gmail.composeTrigger do manifestu projektu skryptu dodatku i zaktualizuj zakresy pliku manifestu, aby uwzględnić te wymagane do działania akcji tworzenia.
2. Wdrożyć funkcję komponowania, która tworzy interfejs tworzenia wiadomości, gdy uruchamia się odpowiedni aktywator. Funkcje ComposeTrigger zwracają pojedynczy obiekt Card lub tablicę obiektów Card, które tworzą interfejs tworzenia dla działania tworzenia.
3. Wdrożyć powiązane funkcje wywołania zwrotnego, które są potrzebne do reagowania na interakcje użytkownika z interfejsem tworzenia. Te funkcje nie są samą akcją tworzenia (która powoduje tylko wyświetlenie interfejsu tworzenia), ale są to poszczególne funkcje, które określają, co się dzieje, gdy wybrane są różne elementy interfejsu tworzenia. Na przykład karta interfejsu użytkownika zawierająca przycisk zwykle ma powiązaną funkcję wywołania, która jest wykonywana, gdy użytkownik kliknie ten przycisk. Funkcja wywołania zwrotnego dla widżetów, które aktualizują treść wersji roboczej wiadomości, powinna zwracać obiekt UpdateDraftActionResponse.

Tworzenie funkcji aktywatora

Interfejs tworzenia rozszerzenia jest tworzony w taki sam sposób jak interfejs wiadomości rozszerzenia – za pomocą usługi kart w Apps Script można tworzyć karty i wypełniać je widżetami.

Musisz zaimplementować gmail.composeTrigger.selectActions[].runFunctionokreślony w pliku manifestu. Funkcja reguły tworzenia musi zwracać albo pojedynczy obiekt Card, albo tablicę obiektów Card, które tworzą interfejs tworzenia dla danej czynności. Te funkcje są bardzo podobne do funkcji reguł kontekstowych i powinny tworzyć karty w taki sam sposób.

Ostrzeżenie: ze względów bezpieczeństwa dodatki nie mogą zmieniać uprawnień dostępu do plików Google Workspace ani aplikacji innych firm. Na przykład wtyczka nie może w sposób cichy dodawać odbiorców e-maili do zestawu kont, które mogą wyświetlać plik Dropbox. Zamiast tego dodatek musi informować użytkowników o zmianie uprawnień. Dodatki, które nie informują użytkowników o takich zmianach, nie mogą przejść sprawdzenia.

Tworzenie obiektów zdarzeń aktywujących

Gdy zostanie wybrane działanie w komponencie, powoduje ono wykonanie odpowiedniej funkcji tworzenia funkcji wyzwalającej i przekazuje jej jako parametr obiekt zdarzenia. Obiekt zdarzenia może zawierać informacje o kontekście dodatku i wersji roboczej, która jest tworzona dla funkcji aktywatora.

Więcej informacji o tym, jak są uporządkowane dane w obiekcie zdarzenia, znajdziesz w sekcji Struktura obiektu zdarzenia. Informacje zawarte w obiekcie zdarzenia są częściowo kontrolowane przez wartość pola manifestu gmail.composeTrigger.draftAccess:

• Jeśli pole manifestu gmail.composeTrigger.draftAccess ma wartość NONE lub nie jest uwzględnione, obiekt zdarzenia zawiera tylko minimalne informacje.

• Jeśli parametr gmail.composeTrigger.draftAccess ma wartość METADATA, obiekt zdarzenia przekazany do funkcji aktywatora tworzenia jest wypełniany listami odbiorców tworzonego e-maila.

Uwaga: aby uzyskać dostęp do wersji roboczej METADATA, manifest dodatku musi zawierać https://www.googleapis.com/auth/gmail.addons.current.message.metadata zakres działania w Gmailu.

Wstawianie treści do aktywnych wersji roboczych

Interfejs tworzenia wiadomości w dodatku do Google Workspace zazwyczaj zawiera opcje i elementy sterujące, które ułatwiają tworzenie wiadomości. W takich przypadkach, gdy użytkownik wybierze opcje w interfejsie, dodatek interpretuje te wybory i odpowiednio aktualizuje bieżącą wersję roboczą e-maila.

Aby ułatwić aktualizowanie bieżącego e-maila w postaci szkicu, rozszerzyliśmy usługę Card service o te klasy:

• ContentType – enumeracja określająca, czy dodać zmienny kod HTML, niezmienny kod HTML (którego użytkownicy Gmaila nie mogą edytować) czy zwykły tekst.
• UpdateDraftActionResponse – reprezentuje odpowiedź na działanie, które aktualizuje bieżący e-mail.
• UpdateDraftActionResponseBuilder – kreator obiektów UpdateDraftActionResponse.
• UpdateDraftBodyAction – reprezentuje działanie, które aktualizuje treść bieżącego e-maila w wersji roboczej.
• UpdateDraftBodyType – liczba określająca sposób zmiany treści.
• UpdateDraftSubjectAction – reprezentuje działanie, które aktualizuje pole tematu bieżącego e-maila w postaci szkicu.
• UpdateDraftToRecipientsAction – reprezentuje działanie, które aktualizuje listę odbiorców bieżącego e-maila w wersji roboczej.
• UpdateDraftCcRecipientsAction – reprezentuje działanie, które aktualizuje odbiorców w polu DW bieżącego e-maila.
• UpdateDraftBccRecipientsAction – reprezentuje działanie, które aktualizuje odbiorców w polu UDW bieżącego e-maila w wersji roboczej.

Zazwyczaj interfejs tworzenia dodatku zawiera widżet „Zapisz” lub „Wstaw”, który użytkownik może kliknąć, aby wskazać, że zakończył dokonywanie wyborów w interfejsie i chce dodać swoje wybory do e-maila, który tworzy. Aby dodać tę interaktywność, widżet powinien mieć powiązany obiekt Action, który instruuje dodatek do uruchomienia określonej funkcji wywołania zwrotnego po kliknięciu widżetu. Musisz zaimplementować te funkcje wywołania zwrotnego. Każda funkcja wywołania zwrotnego powinna zwracać obiekt UpdateDraftActionResponse, który zawiera szczegółowe informacje o zmianach, które należy wprowadzić w bieżącym e-mailu.

Przykład 1

Poniższy fragment kodu pokazuje, jak utworzyć interfejs tworzenia, który aktualizuje temat oraz odbiorców w polach Do, DW i UDW bieżącego e-maila.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

Przykład 2

Ten fragment kodu pokazuje, jak utworzyć interfejs tworzenia, który wstawia obrazy do bieżącego e-maila w wersji roboczej.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }