使用 Compose 操作扩展 Compose 界面

除了在用户阅读 Gmail 邮件时提供基于卡片的界面 邮件、扩展 Gmail 的 Google Workspace 插件 可以在用户撰写新消息或 回复现有会话这样,Google Workspace 插件就可以自动为用户撰写电子邮件。

访问插件 Compose 界面

您可以通过两种方式查看插件的撰写界面。第一种方法是 在该插件打开的情况下撰写新草稿或回复。第二个 可以在写草稿时启动插件

无论哪种情况,该插件都会执行相应的 编写触发器函数,在插件中定义 清单。 Compose 触发器函数用于为该 Compose 构建 Compose 界面 Gmail 随后会向用户显示该操作。

构建 Compose 插件

您可以按照以下常规步骤向插件添加 Compose 功能:

  1. 添加 gmail.composeTrigger 添加到插件脚本项目中 清单 然后更新清单 要包含的范围 组合操作所需的组件
  2. 实现一个 Compose 触发器函数,该函数会在 触发器触发。Compose 触发器函数会返回单个 Card 对象或 Card 对象, 撰写操作的 Compose 界面。
  3. 实现对用户的 响应所需的关联回调函数 编写界面交互。这些函数本身并不是 Compose 操作 (这只会使系统显示 Compose 界面);这些是 单独的函数,分别控制 写邮件界面例如,包含按钮的界面卡片 通常具有关联的回调函数,该函数会在用户点击 该按钮。用于更新草稿消息的微件的回调函数 内容应该返回 UpdateDraftActionResponse 对象。

Compose 触发器函数

插件的撰写界面的构建方式与插件消息的构建方式相同 界面 - 使用 Apps 脚本卡片服务构建 卡片,然后在卡片中 widgets

您必须实现 gmail.composeTrigger.selectActions[].runFunction 所有属性Compose 触发器函数必须返回 单个 Card 对象或 Card 对象的数组 构成该操作的 Compose 界面这些函数与 上下文触发器函数 也应以同样的方式制作卡片

Compose 触发器事件对象

选择撰写操作后,系统会执行相应的撰写触发器 函数,并向该函数传递一个事件对象 作为参数传递。该事件对象可以包含有关插件上下文的信息 并且草稿将添加到触发器函数中。

请参阅事件对象结构 了解有关如何在事件对象中排列信息的详情。信息 事件对象中包含的事件,部分地受事件对象的 gmail.composeTrigger.draftAccess 清单字段:

正在将内容插入到有效草稿中

Google Workspace 插件的撰写界面通常会提供 帮助撰写消息的用户选项和控件。对于这些使用场景 当用户在界面中做出选择后,插件就会解读这些选择 并相应更新当前有效的电子邮件草稿。

为了更轻松地更新当前的电子邮件草稿,卡片服务 已扩展下列类:

插件撰写界面通常包含“Save”或“Insert”创建微件 可以点击该图标来表明用户在界面中已选好产品,并希望 添加到他们所撰写电子邮件的选项添加此 interactivity 时,该 widget 应该具有 一个关联的 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 界面 复制到当前的电子邮件草稿中。

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