使用 Compose 操作扩展 Compose 界面

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

访问插件 Compose 界面

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

无论是哪种情况，都会导致插件执行插件清单中定义的相应Compose 触发器函数。Compose 触发器函数会为该 Compose 操作构建 Compose 界面，然后 Gmail 会将该界面显示给用户。

构建 Compose 插件

您可以按照以下一般步骤为插件添加撰写功能：

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

组合触发器函数

构建插件的消息撰写界面的方式与构建插件的消息界面相同，即使用 Apps Script 卡片服务构建卡片并用微件填充这些卡片。

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

组合触发器事件对象

选择 Compose 操作后，系统会执行相应的 Compose 触发器函数，并将 event 对象作为参数传递给该函数。事件对象可以携带有关插件上下文以及传递给触发器函数的草稿的信息。

如需详细了解事件对象中信息的排列方式，请参阅事件对象结构。事件对象中包含的信息部分受 gmail.composeTrigger.draftAccess 清单字段的值控制：

将内容插入到有效的草稿中

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

为了更轻松地更新当前的草稿电子邮件，卡片服务已扩展为包含以下类：

通常，插件撰写界面包含“保存”或“插入”微件，用户可以点击该微件，表示他们已在界面中完成选择，并希望将其选择添加到正在撰写的电子邮件中。如需添加此互动，该 widget 应具有关联的 Action 对象，该对象会指示插件在用户点击 widget 时运行特定的回调函数。您必须实现这些回调函数。每个回调函数都应返回一个构建的 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;     }