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

Dodatki do Google Workspace, które rozszerzają Gmaila, nie tylko udostępniają interfejs oparty na kartach, ale też interfejs oparty na kartach, gdy użytkownik czyta wiadomość w Gmailu. Dzięki temu dodatki do Google Workspace mogą zautomatyzować tworzenie e-maili dla użytkownika.

Uzyskiwanie dostępu do interfejsu tworzenia dodatku

Interfejs tworzenia dodatku można 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 uruchamianie dodatku podczas tworzenia wersji roboczej.

W obu przypadkach dodatek wykonuje odpowiednią funkcję aktywatora tworzenia zdefiniowaną w pliku manifestu dodatku. Funkcja aktywatora tworzenia wiadomości tworzy interfejs tworzenia wiadomości, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do tworzenia wiadomości

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

  1. Dodaj pole gmail.composeTrigger do pliku manifestu projektu dodatku i zaktualizuj zakresy pliku manifestu, aby uwzględnić te elementy wymagane do tworzenia treści.
  2. Zaimplementuj funkcję aktywatora tworzenia, która tworzy interfejs tworzenia po uruchomieniu reguły. Funkcje aktywatora tworzenia wiadomości zwracają pojedynczy obiekt Card lub tablicę obiektów Card, które składają się na interfejs tworzenia, dla działania tworzenia wiadomości.
  3. Zaimplementuj powiązane funkcje wywołania zwrotnego niezbędne do reagowania na interakcje użytkownika w interfejsie tworzenia wiadomości. Te funkcje nie są działaniem tworzenia (które powoduje tylko wyświetlenie interfejsu tworzenia), a raczej indywidualnymi funkcjami, które określają, co się dzieje, gdy wybrane są różne elementy tego 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 został stworzony w taki sam sposób jak interfejs wiadomości dodatku, czyli przy użyciu usługi karty Apps Script, która pozwala tworzyć karty i wypełniać je widżetami.

Musisz zaimplementować gmail.composeTrigger.selectActions[].runFunction zdefiniowany 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 dla danego działania. Te funkcje są bardzo podobne do funkcji aktywatorów kontekstowych i powinny tworzyć karty w ten sam sposób.

Tworzenie obiektów zdarzeń aktywatora

Po wybraniu działania tworzenia wiadomości wykonywana jest odpowiednia funkcja wyzwalacza tworzenia i przekazuje tę funkcję jako parametr obiekt zdarzenia. Obiekt zdarzenia może zawierać informacje o kontekście dodatku i wersji roboczej tworzonej dla funkcji aktywującej.

Szczegółowe informacje o rozmieszczeniu informacji w obiekcie zdarzenia znajdziesz w sekcji Struktura obiektu zdarzenia. Informacje zawarte w obiekcie zdarzenia zależą częściowo od wartości pola manifestu gmail.composeTrigger.draftAccess:

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

  • Jeśli właściwość gmail.composeTrigger.draftAccess ma wartość METADATA, obiekt zdarzenia przekazywany do funkcji aktywatora tworzenia wiadomości jest zapełniany listami odbiorców tworzonego e-maila.

Wstawianie treści do aktywnych wersji roboczych

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

Aby ułatwić aktualizowanie bieżącej wersji roboczej e-maila, rozszerzyliśmy usługę kart o te klasy:

Zwykle interfejs tworzenia dodatku zawiera widżet „Zapisz” lub „Wstaw”, który użytkownik może kliknąć, aby wskazać, że dany element został już wybrany i dodać wybrany element do tworzonego e-maila. Aby można było dodać tę interaktywność, widżet powinien mieć powiązany obiekt Action, który instruuje dodatek, by po kliknięciu widżetu uruchomił określoną funkcję wywołania zwrotnego. Musisz wdrożyć te funkcje wywołań zwrotnych. Każda funkcja wywołania zwrotnego powinna zwracać utworzony obiekt UpdateDraftActionResponse ze szczegółowymi informacjami o zmianach, które należy wprowadzić w bieżącej wersji roboczej e-maila.

Przykład 1

Poniższy fragment kodu pokazuje, jak utworzyć interfejs tworzenia, który aktualizuje temat oraz adresatów Do, DW i UDW 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 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 tworzenia, który wstawia obrazy 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;
    }