使用撰寫動作擴充撰寫 UI

除了在讀取 Gmail 使用者時，提供卡片式介面 訊息，Google Workspace 外掛程式可擴充 Gmail 使用者可以在撰寫新訊息時提供其他介面 回覆現有留言。如此一來，Google Workspace 外掛程式就能自動為使用者撰寫電子郵件。

存取外掛程式 Compose UI

有兩種方法可以查看外掛程式的 Compose UI。第一種是開始 開啟外掛程式時，撰寫新的草稿或回覆。第二個 可讓您在撰寫草稿時啟動外掛程式

無論哪一種情況，外掛程式都會執行對應的 Compose 觸發條件函式，如外掛程式所定義 資訊清單。 Compose 觸發條件函式會為該 Compose 建構 Compose UI 動作，Gmail 隨後就會向使用者顯示。

建立「撰寫」外掛程式

如要在外掛程式中新增撰寫功能，請按照下列步驟操作：

1. 新增 gmail.composeTrigger 欄位加入外掛程式指令碼專案 資訊清單 並更新資訊清單 要包含的範圍 也就是撰寫動作所需的 Pod
2. 實作 Compose 觸發條件函式，在 觸發。Compose 觸發條件函式會傳回 Card 物件或 Card 物件構成 撰寫動作的 Compose UI。
3. 實作回應使用者的回呼函式所需的相關回呼函式 撰寫 UI 互動。這些函式本身並非撰寫動作 (只會影響 Compose UI 顯示)。這些是 個別函式，用於規範 已選取 Compose UI。例如：含有按鈕的 UI 資訊卡 通常有一個相關聯的回呼函式，會在使用者點擊時執行 該按鈕。更新草稿訊息的小工具回呼函式 應該傳回 UpdateDraftActionResponse敬上 物件。

Compose 觸發條件函式

外掛程式的 Compose UI 建構方式與外掛程式訊息的建構方式相同 UI：使用 Apps Script 資訊卡服務建構 資訊卡，然後填入 小工具。

您必須將 gmail.composeTrigger.selectActions[].runFunction敬上 您在資訊清單中定義的屬性Compose 觸發條件函式必須傳回 單一 Card 物件 Card 物件的陣列 ，當中包含該動作的 Compose UI。這些函式非常相似 關聯觸發條件函式 應該以相同方式建構資訊卡

警告： 基於安全考量，外掛程式 無法無端變更 Google Workspace 或第三方 檔案存取權限舉例來說，外掛程式無法發送靜音通知 將電子郵件收件者新增到可查看 Dropbox 檔案的一組帳戶。 而是必須告知使用者權限即將變更。 未告知使用者這類變更的外掛程式就無法通過 附加內容評論。

Compose 觸發條件事件物件

選取撰寫動作後，系統會執行相應的撰寫觸發條件 函式並傳送事件物件給函式 做為參數事件物件可以包含外掛程式背景的相關資訊 草稿則要寫成觸發函式

請參閱「事件物件結構」一文 ，瞭解資訊如何在事件物件中排列。這些資訊 事件物件所包含的完全是由 gmail.composeTrigger.draftAccess敬上 資訊清單欄位：

• 如果 gmail.composeTrigger.draftAccess 資訊清單欄位為 NONE 或未包含，則事件物件僅 只提供最基本的資訊

• 如果gmail.composeTrigger.draftAccess 設為 METADATA，則傳遞至 Compose 觸發函式的事件物件 填入電子郵件撰寫的收件者清單。

，瞭解如何調查及移除這項存取權。

注意： 如要使用 METADATA 草稿存取權，外掛程式資訊清單必須包含 https://www.googleapis.com/auth/gmail.addons.current.message.metadata Gmail 範圍。

正在將內容插入使用中的草稿

一般來說，Google Workspace 外掛程式撰寫 UI 會提供 以及可協助撰寫訊息的使用者選項和控制項以這些用途來說 使用者在 UI 中選擇了選項後，這個外掛程式會解讀 並據此更新目前的有效電子郵件草稿。

如要更輕鬆地更新目前的電子郵件草稿，資訊卡服務 已透過下列類別擴充：

• ContentType： 列舉，用於定義是否要新增可變動的 HTML、不可變動的 HTML (Gmail 或純文字內容，使用者無法編輯。
• UpdateDraftActionResponse - 代表 某動作的回覆，更新目前的電子郵件草稿。
• UpdateDraftActionResponseBuilder：A UpdateDraftActionResponse。 如需儲存大量結構化物件 建議使用 Cloud Bigtable
• UpdateDraftBodyAction - 代表 一項動作，可用於更新目前電子郵件草稿的內文。
• UpdateDraftBodyType： 列舉定義主體的變更方式。
• UpdateDraftSubjectAction - 代表 一項動作，可用於更新目前電子郵件草稿的主旨欄位。
• UpdateDraftToRecipientsAction - 代表 一項動作，將目前電子郵件草稿的收件者更新為收件者。
• UpdateDraftCcRecipientsAction - 代表 一項動作，更新目前電子郵件草稿的副本收件者。
• UpdateDraftBccRecipientsAction - 代表 一項動作，更新目前電子郵件草稿的密件副本收件者。

一般來說，外掛程式撰寫 UI 會包含「儲存」或「插入」使用者可透過其 可以點選表示他們已在使用者介面中完成選擇 讓他們撰寫電子郵件。如何新增 interactivity：小工具 相關聯的 Action 物件 指示外掛程式在小工具 點擊。您必須實作這些回呼函式。每個回呼函式都應該 為 UpdateDraftActionResponse敬上 物件，用於詳細說明對目前電子郵件草稿所做的變更。

範例 1

下列程式碼片段說明如何建構撰寫 UI 來更新電子郵件草稿的主旨，以及「收件者」、「副本」和「密件副本」收件者。

    /**
     * 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 UI 。

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