Расширение пользовательского интерфейса создания с помощью действий создания

Помимо предоставления карточного интерфейса, когда пользователь читает сообщение Gmail, дополнения Google Workspace, расширяющие Gmail, могут предоставлять другой интерфейс, когда пользователь составляет новые сообщения или отвечает на существующие. Это позволяет дополнениям Google Workspace автоматизировать задачу составления писем для пользователя.

Доступ к пользовательскому интерфейсу создания дополнений

Есть два способа просмотреть пользовательский интерфейс создания дополнения. Первый способ — начать создание нового черновика или ответа, когда дополнение уже открыто. Второй способ — запустить дополнение во время создания черновика.

В любом случае надстройка выполняет соответствующую функцию триггера компоновки , определенную в манифесте надстройки. Функция триггера компоновки создает пользовательский интерфейс компоновки для этого действия компоновки, который Gmail затем отображает пользователю.

Создание дополнения для создания сообщений

Вы можете добавить функцию создания сообщений в дополнение, выполнив следующие общие шаги:

  1. Добавьте поле gmail.composeTrigger в манифест проекта скрипта надстройки и обновите области действия манифеста, включив в них те, которые требуются для действий по созданию сообщений.
  2. Реализуйте функцию триггера компоновки, которая создает пользовательский интерфейс компоновки при срабатывании триггера. Функции триггера компоновки возвращают либо один объект Card , либо массив объектов Card , которые составляют пользовательский интерфейс компоновки для действия компоновки.
  3. Реализуйте связанные функции обратного вызова, необходимые для реагирования на взаимодействия пользователя с пользовательским интерфейсом создания сообщения. Эти функции не являются самим действием создания сообщения (которое только вызывает появление пользовательского интерфейса создания сообщения); скорее, это отдельные функции, которые управляют тем, что происходит при выборе различных элементов пользовательского интерфейса создания сообщения. Например, карточка пользовательского интерфейса, содержащая кнопку, обычно имеет связанную функцию обратного вызова, которая выполняется, когда пользователь нажимает эту кнопку. Функция обратного вызова для виджетов, которые обновляют содержимое черновика сообщения, должна возвращать объект UpdateDraftActionResponse .

Составить функцию триггера

Пользовательский интерфейс создания сообщений надстройки создается так же, как и пользовательский интерфейс сообщений надстройки — с использованием сервиса Apps Script Card для создания карточек и заполнения их виджетами .

Вам необходимо реализовать gmail.composeTrigger.selectActions[].runFunction , которую вы определяете в своем манифесте. Функция триггера компоновки должна возвращать либо один объект Card , либо массив объектов Card , которые составляют пользовательский интерфейс компоновки для этого действия. Эти функции очень похожи на функции контекстного триггера и должны создавать карточки таким же образом.

Составьте объекты событий триггера

При выборе действия компоновки выполняется соответствующая функция триггера компоновки и передается функции объект события в качестве параметра. Объект события может переносить информацию о контексте надстройки и черновике, который компонуется, в функцию триггера.

Подробнее о том, как организована информация в объекте события, см. в разделе Структура объекта события. Информация, содержащаяся в объекте события, частично контролируется значением поля манифеста gmail.composeTrigger.draftAccess :

  • Если поле манифеста gmail.composeTrigger.draftAccess имеет NONE или не включено, объект события содержит только минимальную информацию.

  • Если gmail.composeTrigger.draftAccess имеет значение METADATA , объект события, переданный функции триггера создания сообщения, заполняется списками получателей создаваемого электронного письма.

Вставка контента в активные черновики

Обычно пользовательский интерфейс для создания дополнений Google Workspace предоставляет пользователю параметры и элементы управления, которые помогают составить сообщение. В таких случаях использования после того, как пользователь сделал выбор в пользовательском интерфейсе, дополнение интерпретирует выбор и обновляет текущий рабочий черновик электронной почты соответствующим образом.

Чтобы упростить обновление текущего черновика электронного письма, сервис «Карта» был расширен следующими классами:

  • ContentType — перечисление, определяющее, следует ли добавлять изменяемый HTML, неизменяемый HTML (который пользователи Gmail не могут редактировать) или простой текстовый контент.
  • UpdateDraftActionResponse — представляет ответ на действие, обновляющее текущий черновик электронного письма.
  • UpdateDraftActionResponseBuilder — конструктор объектов UpdateDraftActionResponse .
  • UpdateDraftBodyAction — представляет действие, которое обновляет тело текущего черновика электронного письма.
  • UpdateDraftBodyType — перечисление, определяющее, как изменяется тело.
  • UpdateDraftSubjectAction — представляет действие, которое обновляет поле темы текущего черновика электронного письма.
  • UpdateDraftToRecipientsAction — представляет действие, которое обновляет получателей текущего черновика электронного письма.
  • UpdateDraftCcRecipientsAction — представляет действие, которое обновляет получателей копии текущего черновика электронного письма.
  • UpdateDraftBccRecipientsAction — представляет действие, которое обновляет получателей скрытой копии текущего черновика электронного письма.

Обычно пользовательский интерфейс дополнения включает виджет «Сохранить» или «Вставить», который пользователь может щелкнуть, чтобы указать, что он закончил делать выбор в пользовательском интерфейсе и хочет, чтобы его выбор был добавлен в создаваемое им электронное письмо. Чтобы добавить эту интерактивность , виджет должен иметь связанный объект Action , который инструктирует дополнение запустить определенную функцию обратного вызова при щелчке по виджету. Вы должны реализовать эти функции обратного вызова. Каждая функция обратного вызова должна возвращать построенный объект UpdateDraftActionResponse , который подробно описывает изменения, которые необходимо внести в текущий черновик электронного письма.

Пример 1

В следующем фрагменте кода показано, как создать пользовательский интерфейс для создания сообщения, который обновляет тему, а также получателей в полях «Кому», «Копия» и «Скрытая копия» текущего черновика электронного письма.

    /**
     * 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;
    }

Пример 2

В следующем фрагменте кода показано, как создать пользовательский интерфейс для создания сообщений, который вставляет изображения в текущий черновик электронного письма.

    /**
     * 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;
    }