使用 Compose 操作扩展 Compose 界面

除了在用户阅读 Gmail 邮件时提供卡片式界面之外,扩展 Gmail 的 Google Workspace 插件还可以在用户撰写新邮件或回复现有邮件时提供另一个界面。这样,Google Workspace 插件就可以为用户自动撰写电子邮件。

访问插件 Compose 界面

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

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

构建 Compose 插件

您可以按照以下常规步骤为插件添加撰写功能:

  1. gmail.composeTrigger 字段添加到插件脚本项目清单中,并更新清单作用域,使其包含 Compose 操作所需的作用域。
  2. 实现 Compose 触发器函数,用于在触发器触发时构建 Compose 界面。Compose 触发器函数会返回单个 Card 对象或 Card 对象数组,这些对象构成了 Compose 操作的 Compose 界面。
  3. 实现对用户的 Compose 界面交互做出响应所需的关联回调函数。这些函数不是 Compose 操作本身(只会导致 Compose 界面显示);而是各个函数,控制选择 Compose 界面的不同元素时发生的情况。例如,包含按钮的界面卡片通常具有在用户点击该按钮时执行的关联回调函数。用于更新草稿消息内容的 widget 的回调函数应返回 UpdateDraftActionResponse 对象。

Compose 触发器函数

插件的撰写界面的构建方式与插件的消息界面相同,都是使用 Apps 脚本的 Card 服务构建卡片,并使用 widget 进行填充。

您必须实现您在清单中定义的 gmail.composeTrigger.selectActions[].runFunction。Compose 触发器函数必须返回单个 Card 对象或 Card 对象数组,这些对象构成了相应操作的 Compose 界面。这些函数与上下文触发器函数非常相似,应以相同的方式构建卡片。

Compose 触发器事件对象

选择 Compose 操作后,它会执行相应的 Compose 触发器函数,并向该函数传递一个事件对象作为参数。事件对象可以将有关插件上下文和正在构成的草稿的信息传递给触发器函数。

如需详细了解事件对象中的信息排列方式,请参阅事件对象结构。事件对象中包含的信息在一定程度上受 gmail.composeTrigger.draftAccess 清单字段的值控制:

将内容插入有效草稿中

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

为了更轻松地更新当前的电子邮件草稿,我们对卡片服务进行了扩展,添加了以下类:

通常,插件撰写界面包括“保存”或“插入”widget,用户可以点击该 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;
    }