Rozszerzanie interfejsu tworzenia wiadomości za pomocą działań związanych z tworzeniem 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 mogą automatyzować zadanie tworzenia e-maili.

Dostęp do interfejsu tworzenia dodatku do Google Workspace

Interfejs tworzenia dodatku możesz wyświetlić na 2 sposoby. Pierwszy sposób to rozpoczęcie tworzenia nowego roboczego e-maila lub odpowiedzi, gdy dodatek jest już otwarty. Drugi sposób to uruchomienie dodatku podczas tworzenia roboczego e-maila.

W obu przypadkach dodatek wykonuje odpowiednią funkcję aktywatora tworzenia, która jest zdefiniowana w pliku manifestu dodatku. Funkcja aktywatora tworzenia tworzy interfejs tworzenia dla tego działania, który Gmail wyświetla użytkownikowi.

Tworzenie dodatku do tworzenia

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

  1. Dodaj pole gmail.composeTrigger do pliku manifestu projektu skryptu dodatku i zaktualizuj zakresy manifestu aby uwzględnić te, które są wymagane do działań związanych z tworzeniem.
  2. Zaimplementuj funkcję aktywatora tworzenia, która tworzy interfejs tworzenia, gdy aktywator się uruchomi. Funkcje aktywatora tworzenia zwracają pojedynczy Card obiekt lub tablicę obiektów Card, które tworzą interfejs tworzenia dla działania tworzenia.
  3. Zaimplementuj powiązane funkcje wywołania zwrotnego, które są potrzebne do reagowania na interakcje użytkownika z interfejsem tworzenia. Te funkcje nie są samym działaniem tworzenia (które 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 dla widżetów, które aktualizują treść roboczego e-maila powinna zwracać UpdateDraftActionResponse obiekt.

Funkcja aktywatora tworzenia

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

Musisz zaimplementować gmail.composeTrigger.selectActions[].runFunction , którą zdefiniujesz w pliku manifestu. Funkcja aktywatora tworzenia musi zwracać pojedynczy obiekt Card lub tablicę obiektów Card które tworzą interfejs tworzenia dla tego działania. Te funkcje są bardzo podobne do funkcji aktywatora kontekstowego i powinny tworzyć karty w ten sam sposób.

Obiekty zdarzeń aktywatora tworzenia

Gdy wybierzesz działanie tworzenia, zostanie wykonana odpowiednia funkcja aktywatora tworzenia i przekazany jej zostanie obiekt zdarzenia jako parametr. Obiekt zdarzenia może przekazywać do funkcji aktywatora informacje o kontekście dodatku i tworzonym roboczym e-mailu.

Szczegółowe informacje o tym, jak informacje są ułożone w obiekcie zdarzenia, znajdziesz w artykule Struktura obiektu zdarzenia. Informacje zawarte w obiekcie zdarzenia są częściowo kontrolowane przez wartość pola gmail.composeTrigger.draftAccess w pliku manifestu:

Wstawianie treści do aktywnych roboczych e-maili

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

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

Zazwyczaj interfejs tworzenia dodatku zawiera widżet „Zapisz” lub „Wstaw”, który użytkownik może kliknąć, aby wskazać, że zakończył wybieranie 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 UpdateDraftActionResponse obiekt, który zawiera szczegółowe informacje o zmianach, jakie należy wprowadzić w bieżącym roboczym e-mailu.

Przykład 1

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