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

Oprócz interfejsu opartego na kartach, który jest wyświetlany, gdy użytkownik czyta wiadomość w Gmailu, dodatki do 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 do Google Workspace mogą automatyzować zadanie tworzenia e-maili dla użytkownika.

Dostęp do interfejsu tworzenia dodatku

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

W obu przypadkach dodatek wykonuje odpowiednią funkcję aktywatora tworzenia zdefiniowaną w pliku manifestu dodatku. Funkcja wywołująca tworzenie interfejsu tworzenia wiadomości tworzy interfejs tworzenia wiadomości dla tej czynności tworzenia wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do pisania

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

1. Dodaj pole gmail.composeTrigger do projektu skryptu dodatku manifestu i zaktualizuj zakresy manifestu, aby uwzględnić te, które są wymagane w przypadku działań związanych z tworzeniem.
2. Zaimplementuj funkcję aktywatora tworzenia, która tworzy interfejs tworzenia, gdy aktywator zostanie uruchomiony. Funkcje wyzwalające tworzenie zwracają pojedynczy obiekt Card lub tablicę obiektów Card, które składają się na interfejs tworzenia dla działania tworzenia.
3. Zaimplementuj powiązane funkcje wywołania zwrotnego potrzebne do reagowania na interakcje użytkownika z interfejsem tworzenia wiadomości. Te funkcje nie są samą czynnością tworzenia (która powoduje tylko wyświetlenie interfejsu tworzenia), ale poszczególnymi funkcjami, które określają, co się dzieje po wybraniu różnych elementów interfejsu tworzenia. Na przykład karta interfejsu zawierająca przycisk zwykle ma powiązaną funkcję wywołania zwrotnego, która jest wykonywana, gdy użytkownik kliknie ten przycisk. Funkcja wywołania zwrotnego w przypadku widżetów, które aktualizują treść wersji roboczej wiadomości, powinna zwracać obiekt UpdateDraftActionResponse.

Tworzenie funkcji aktywatora

Interfejs tworzenia dodatku jest tworzony w taki sam sposób jak interfejs wiadomości dodatku – za pomocą usługi Card Apps Script do tworzenia kart i wypełniania ich widżetami.

Musisz zaimplementować zdefiniowany w pliku manifestu element gmail.composeTrigger.selectActions[].runFunction. Funkcja wywołująca musi zwracać pojedynczy obiekt Card lub tablicę obiektów Card, które składają się na interfejs tworzenia dla danego działania. Funkcje te są bardzo podobne do funkcji reguł kontekstowych i powinny tworzyć karty w ten sam sposób.

Ostrzeżenie: ze względów bezpieczeństwa dodatki nie mogą bez powiadomienia zmieniać uprawnień dostępu do plików Google Workspace ani plików innych firm. Na przykład dodatek nie może w sposób niewidoczny dla użytkownika dodawać adresatów e-maila do zestawu kont, które mogą wyświetlać plik w Dropbox. Zamiast tego dodatek musi informować użytkowników o wprowadzanych zmianach uprawnień. Dodatki, które nie informują użytkowników o takich zmianach, nie mogą przejść weryfikacji.

Tworzenie obiektów zdarzeń aktywujących

Gdy wybierzesz działanie tworzenia, zostanie wykonana odpowiednia funkcja wyzwalacza tworzenia i przekazany do niej obiekt zdarzenia jako parametr. Obiekt zdarzenia może przekazywać do funkcji aktywującej informacje o kontekście dodatku i tworzonej wersji roboczej.

Szczegółowe informacje o tym, jak informacje są ułożone 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 gmail.composeTrigger.draftAccess w pliku manifestu ma wartość NONE lub nie jest uwzględnione, obiekt zdarzenia zawiera tylko podstawowe informacje.

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

Uwaga: korzystanie z dostępu do wersji roboczych METADATA wymaga, aby plik manifestu dodatku zawierał https://www.googleapis.com/auth/gmail.addons.current.message.metadata zakres Gmaila.

wstawianie treści do aktywnych wersji roboczych,

Zazwyczaj interfejs tworzenia wiadomości dodatku Google Workspace udostępnia użytkownikowi opcje i elementy sterujące, które pomagają w tworzeniu wiadomości. W tych przypadkach, gdy użytkownik dokona wyboru w interfejsie, dodatek interpretuje te wybory i odpowiednio aktualizuje bieżącą wersję roboczą e-maila.

Aby ułatwić aktualizowanie bieżącego e-maila w wersji roboczej, usługa Card została rozszerzona o te klasy:

• ContentType – wyliczenie określające, czy dodać treści w formacie HTML z możliwością edycji, HTML bez możliwości edycji (którego użytkownicy Gmaila nie mogą edytować) czy zwykłego tekstu.
• UpdateDraftActionResponse – reprezentuje odpowiedź na działanie, które aktualizuje bieżącą wersję roboczą e-maila.
• UpdateDraftActionResponseBuilder – kreator obiektów UpdateDraftActionResponse.
• UpdateDraftBodyAction – reprezentuje działanie, które aktualizuje treść bieżącego e-maila w wersji roboczej.
• UpdateDraftBodyType – wyliczenie określające sposób zmiany treści.
• UpdateDraftSubjectAction – reprezentuje działanie, które aktualizuje pole tematu bieżącego e-maila w wersji roboczej.
• UpdateDraftToRecipientsAction – reprezentuje działanie, które aktualizuje odbiorców w polu „Do” bieżącego e-maila w wersji roboczej.
• UpdateDraftCcRecipientsAction – reprezentuje działanie, które aktualizuje odbiorców w polu DW bieżącego e-maila w wersji roboczej.
• 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ł wybieranie opcji w interfejsie i chce, aby jego wybory zostały dodane do tworzonego e-maila. Aby dodać tę interaktywność, widżet powinien mieć powiązany obiekt Action, który instruuje dodatek, aby po kliknięciu widżetu uruchomił określoną funkcję wywołania zwrotnego. Musisz zaimplementować te funkcje wywołania zwrotnego. Każda funkcja wywołania zwrotnego powinna zwracać utworzony obiekt UpdateDraftActionResponse, który zawiera szczegółowe informacje o zmianach, jakie należy wprowadzić w bieżącym e-mailu w wersji roboczej.

Przykład 1

Poniższy fragment kodu pokazuje, jak utworzyć interfejs do pisania wiadomości, który aktualizuje temat oraz odbiorców w polach „Do”, „Cc” i „Bcc” bieżącego roboczego 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

Poniższy fragment kodu pokazuje, jak utworzyć interfejs komponowania, który wstawia obrazy do bieżącego roboczego 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 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;
    }