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

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

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

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

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

Создание дополнения для Compose

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

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

Создать функцию запуска

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

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

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

Создавайте объекты событий-триггеров

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

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

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

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

Примечание: Для использования черновика доступа METADATA необходимо, чтобы манифест дополнения включал область действия Gmail https://www.googleapis.com/auth/gmail.addons.current.message.metadata .

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

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

Для упрощения обновления текущего черновика электронного письма, сервис Card был расширен следующими классами:

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

Как правило, пользовательский интерфейс дополнения для создания письма включает виджет «Сохранить» или «Вставить», на который пользователь может нажать, чтобы указать, что он закончил выбор элементов в интерфейсе и хочет, чтобы его выбор был добавлен в создаваемое письмо. Для добавления этой интерактивности виджет должен иметь связанный объект 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;
    }