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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

Создание надстройки для создания композиций

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

  1. Добавьте поле gmail.composeTrigger в манифест проекта сценария надстройки и обновите области манифеста, включив в них те, которые необходимы для действий по составлению.
  2. Реализуйте функцию триггера компоновки, которая создает пользовательский интерфейс компоновки при срабатывании триггера. Триггерные функции Compose возвращают либо один объект 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 предоставляет пользовательские параметры и элементы управления, помогающие составить сообщение. В этих случаях использования после того, как пользователь сделал выбор в пользовательском интерфейсе, надстройка интерпретирует выбор и соответствующим образом обновляет текущий рабочий черновик электронной почты.

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

  • 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;
    }