使用 Compose 操作扩展 Compose 界面

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

在用户阅读 Gmail 邮件时,除了提供基于卡片的界面, Google Workspace 扩展 Gmail 的插件还可以在用户撰写新邮件或回复现有邮件时提供其他界面。这样, Google Workspace插件就可以自动执行用户撰写电子邮件的任务。

访问插件撰写界面

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

无论是哪种情况,都会导致插件执行相应的组合触发器函数(在插件清单中定义)。撰写触发器函数会为该撰写操作构建组合界面,然后 Gmail 会向用户显示该界面。

构建 Compose 插件

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

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

Compose 触发器函数

插件的 Compose 界面的构建方式与插件的消息界面相同,即使用 Apps 脚本卡片服务构建卡片并使用微件填充卡片。

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

Compose 触发器事件对象

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

如需详细了解如何在事件对象中排列信息,请参阅事件对象结构。事件对象中包含的信息由 gmail.composeTrigger.draftAccess 清单字段的值部分控制:

将内容插入有效草稿

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

为了更轻松地更新当前的电子邮件草稿,Card 服务新增了以下类:

通常,插件式撰写界面包含一个“保存”或“插入”微件,用户可以点击该微件来表明已完成在界面中进行选择,并希望将所做选择添加到正在撰写的电子邮件中。如需添加此互动性,微件应具有关联的 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;
    }