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

Dodatki do Google Workspace, które rozszerzają Gmaila, mogą stanowić kolejny interfejs, gdy użytkownik pisze nową wiadomość lub odpowiada na istniejące. Dzięki temu dodatki do Google Workspace mogą zautomatyzować proces tworzenia e-maili dla użytkownika.

Dostęp do interfejsu tworzenia dodatku

Istnieją 2 sposoby wyświetlania interfejsu tworzenia dodatku. Pierwszym krokiem jest utworzenie nowej wersji roboczej lub odpowiedzi, gdy dodatek jest już otwarty. Drugi sposób to uruchomienie dodatku podczas tworzenia wersji roboczej.

W każdym z tych przypadków dodatek powoduje wykonanie odpowiadającej mu funkcji aktywacji zdefiniowanej w pliku manifestu. Funkcja aktywatora tworzenia tworzy interfejs tworzenia wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do tworzenia wiadomości

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

1. Dodaj pole gmail.composeTrigger do pliku manifestu projektu dodatku i zaktualizuj zakresy pliku manifestu, aby uwzględnić w nim wymagane pola tworzenia wiadomości.
2. Zaimplementuj funkcję aktywatora tworzenia, która kompiluje interfejs po uruchomieniu aktywatora. Funkcje uruchamiające tworzenie wiadomości zwracają pojedynczy obiekt Card lub tablicę obiektów Card, które składają się z interfejsu tworzenia wiadomości.
3. Zaimplementować powiązane funkcje wywołania zwrotnego niezbędne do reagowania na interakcje użytkownika z tworzeniem interfejsu. Te funkcje nie są działaniem działania tworzenia wiadomości (co powoduje pojawianie się tylko interfejsu tworzenia wiadomości). Są to indywidualne funkcje, które określają, co się dzieje po wybraniu różnych elementów interfejsu. Na przykład karta interfejsu zawierająca przycisk ma zwykle powiązaną funkcję wywołania zwrotnego, która jest wykonywana, gdy użytkownik kliknie ten przycisk. Funkcja wywołania zwrotnego widżetów, które aktualizują treść wersji roboczej wiadomości, powinna zwracać obiekt UpdateDraftActionResponse.

Utwórz funkcję aktywatora

Interfejs tworzenia dodatku jest tworzony w taki sam sposób jak interfejs wiadomości dodatku – używa usługi Card Script Apps Script, aby tworzyć karty i wypełniać je za pomocą widżetów.

Musisz zaimplementować gmail.composeTrigger.selectActions[].runFunction zdefiniowane w pliku manifestu. Funkcja aktywatora tworzenia wiadomości musi zwracać pojedynczy obiekt Card lub tablicę obiektów Card, które składają się na interfejs tworzenia wiadomości dla tego działania. Te funkcje 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ą dyskretnie zmieniać uprawnień dostępu do Google Workspace ani plików innych firm. Na przykład dodatek nie może dyskretnie dodawać adresatów e-maila 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ą zostać sprawdzone.

Utwórz obiekty aktywatora

Po wybraniu działania tworzenia wykonuje ona odpowiednią funkcję aktywatora tworzenia wiadomości i przekazuje ją jako obiekt zdarzenia. Obiekt zdarzenia może zawierać informacje o kontekście dodatku i wersji roboczej tworzonej dla funkcji aktywatora.

Szczegółowe informacje o rozmieszczeniu informacji o obiektach znajdziesz w artykule Struktura obiektu zdarzenia. Informacje zawarte w obiekcie zdarzenia są częściowo kontrolowane przez wartość pola gmail.composeTrigger.draftAccess pliku manifestu:

• Jeśli pole manifestu gmail.composeTrigger.draftAccess ma wartość NONE lub go nie ma, obiekt zdarzenia zawiera tylko podstawowe informacje.

• Jeśli pole gmail.composeTrigger.draftAccess ma wartość METADATA, obiekt zdarzenia przekazany do funkcji aktywatora tworzenia wiadomości jest uzupełniany na listy adresatów e-maila.

Uwaga: użycie wersji roboczej METADATA wymaga, aby dodatek pliku manifestu zawierał https://www.googleapis.com/auth/gmail.addons.current.message.metadatazakres zakresu Gmaila.

Wstawianie treści do aktywnych wersji roboczych

Zwykle interfejs tworzenia dodatku w Google Workspace zapewnia opcje użytkownika i elementy sterujące, które pomagają w tworzeniu wiadomości. W takich przypadkach, gdy użytkownik dokona wyboru w interfejsie, dodatek zinterpretuje wybrane opcje i odpowiednio zaktualizuje bieżącą wersję roboczą e-maila.

Aby ułatwić aktualizowanie bieżącej wersji roboczej e-maila, dodaliśmy usługę kart do tych klas:

• ContentType – tablica, która określa, czy należy dodać zmieniany kod HTML, stały HTML (których użytkownicy Gmaila nie mogą edytować) lub zwykły tekst.
• UpdateDraftActionResponse – odpowiedź na działanie, które aktualizuje bieżącą wersję roboczą e-maila.
• UpdateDraftActionResponseBuilder – kompilator dla obiektów UpdateDraftActionResponse.
• UpdateDraftBodyAction – działanie powodujące zaktualizowanie treści bieżącej wersji roboczej e-maila.
• UpdateDraftBodyType – tablica, w której określono sposób zmiany treści.
• UpdateDraftSubjectAction – działanie polegające na zaktualizowaniu pola tematu bieżącego e-maila.
• UpdateDraftToRecipientsAction – działanie polegające na zaktualizowaniu adresata.
• UpdateDraftCcRecipientsAction – działanie powodujące zaktualizowanie adresatów w polu DW bieżącego e-maila.
• UpdateDraftBccRecipientsAction – działanie powodujące zaktualizowanie adresatów w polu UDW bieżącego e-maila.

Zwykle interfejs tworzenia dodatków zawiera widżet „Zapisz” lub „Wstaw”, który użytkownik może kliknąć, aby wskazać, że zaznaczył już coś w interfejsie użytkownika i poprosił o dodanie elementów do tworzonego e-maila. Aby dodać tę interaktywność, widżet powinien mieć powiązany obiekt Action, który po kliknięciu widżetu powoduje uruchomienie określonej funkcji wywołania zwrotnego. Musisz wdrożyć te funkcje wywołania zwrotnego. Każda funkcja wywołania zwrotnego powinna wyświetlić utworzony obiekt UpdateDraftActionResponse ze szczegółami zmian, które mają zostać wprowadzone w bieżącym wersji roboczej e-maila.

Przykład 1

Fragment kodu poniżej pokazuje, jak utworzyć interfejs tworzenia wiadomości aktualizujący temat, a także adresatów w polach DW, UDW 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

Fragment kodu poniżej pokazuje, jak utworzyć interfejs tworzenia wiadomości ze wstawieniem obrazów do bieżącej wersji roboczej 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;
    }