การขยาย UI การเขียนด้วยการดำเนินการเขียน

นอกเหนือจากการให้บริการอินเทอร์เฟซแบบการ์ดเมื่อผู้ใช้กำลังอ่าน Gmail ข้อความ, ส่วนเสริมของ Google Workspace ที่ขยายได้ สามารถให้อินเทอร์เฟซอีกแบบหนึ่งเมื่อผู้ใช้เขียนข้อความใหม่หรือ โดยตอบกลับความคิดเห็นที่มีอยู่ วิธีนี้ช่วยให้ส่วนเสริมของ Google Workspace ทำงานในการเขียนอีเมลให้ผู้ใช้ได้โดยอัตโนมัติ

การเข้าถึง UI การเขียนของส่วนเสริม

วิธีดู UI การเขียนของส่วนเสริมมี 2 วิธี วิธีแรกคือการเริ่ม เขียนฉบับร่างใหม่หรือตอบกลับขณะที่เปิดส่วนเสริมอยู่แล้ว องค์ประกอบที่ 2 วิธีก็คือการเริ่มใช้ส่วนเสริมขณะเขียนร่างจดหมาย

ไม่ว่าในกรณีใดจะทำให้ส่วนเสริมประมวลผลการกำหนดค่าที่สอดคล้องกัน ฟังก์ชันทริกเกอร์การเขียน ที่กำหนดไว้ในส่วนเสริม ไฟล์ Manifest ฟังก์ชันทริกเกอร์การเขียนจะสร้าง UI การเขียนสำหรับการเขียนนั้น ซึ่ง Gmail จะแสดงต่อผู้ใช้

การสร้างส่วนเสริมสำหรับการเขียน

คุณเพิ่มฟังก์ชันการเขียนลงในส่วนเสริมได้โดยทำตามขั้นตอนทั่วไปต่อไปนี้

1. เพิ่ม gmail.composeTrigger ลงในโปรเจ็กต์สคริปต์ของส่วนเสริม ไฟล์ Manifest และอัปเดตไฟล์ Manifest ขอบเขตที่จะรวม เฉพาะจุดที่จำเป็นสำหรับการเขียน
2. ใช้ฟังก์ชันทริกเกอร์การเขียนที่สร้าง UI การเขียนเมื่อ ทริกเกอร์เริ่มทำงาน เขียนฟังก์ชันทริกเกอร์จะแสดง Card ของออบเจ็กต์หรืออาร์เรย์ของ Card ออบเจ็กต์ที่ประกอบกันขึ้น UI การเขียนสำหรับการดำเนินการเขียน
3. ใช้ฟังก์ชัน Callback ที่เกี่ยวข้องซึ่งจําเป็นต่อการตอบสนองต่อ เขียนการโต้ตอบกับ UI ฟังก์ชันเหล่านี้ไม่ใช่ตัวดำเนินการเขียน (ซึ่งจะทำให้ UI การเขียนปรากฏขึ้นเท่านั้น) แต่สิ่งเหล่านี้คือ แต่ละฟังก์ชัน ซึ่งควบคุมสิ่งที่เกิดขึ้นเมื่อองค์ประกอบต่างๆ ของ เลือก UI การเขียนแล้ว เช่น การ์ด UI ที่มีปุ่ม มักจะมีฟังก์ชัน Callback ที่เกี่ยวข้องซึ่งจะทำงานเมื่อผู้ใช้คลิก ปุ่มนั้น ฟังก์ชัน Callback สำหรับวิดเจ็ตที่อัปเดตข้อความร่าง เนื้อหาควรส่งคืน UpdateDraftActionResponse ออบเจ็กต์

เขียนฟังก์ชันทริกเกอร์

UI การเขียนของส่วนเสริมสร้างขึ้นในลักษณะเดียวกับข้อความของส่วนเสริม UI โดยใช้บริการการ์ด Apps Script เพื่อสร้าง การ์ดและกรอก วิดเจ็ต

คุณต้องใช้ gmail.composeTrigger.selectActions[].runFunction ที่คุณกำหนดในไฟล์ Manifest ฟังก์ชันทริกเกอร์การเขียนต้องส่งคืน ออบเจ็กต์ Card รายการเดียวหรือ อาร์เรย์ของออบเจ็กต์ Card ที่ประกอบขึ้นเป็น UI การเขียนสำหรับการทำงานนั้น ฟังก์ชันเหล่านี้คล้ายกันมาก เป็นฟังก์ชันทริกเกอร์ตามบริบท และควรสร้างการ์ดด้วยวิธีเดิม

เขียนออบเจ็กต์เหตุการณ์ทริกเกอร์

เมื่อเลือกการดำเนินการเขียน การดำเนินการดังกล่าวจะเรียกใช้ทริกเกอร์การเขียนที่เกี่ยวข้อง และส่งฟังก์ชันไปยังออบเจ็กต์เหตุการณ์ เป็นพารามิเตอร์ ออบเจ็กต์เหตุการณ์มีข้อมูลเกี่ยวกับบริบทของส่วนเสริมได้ และแบบร่างที่กำลังเขียนลงในฟังก์ชันทริกเกอร์

ดูโครงสร้างออบเจ็กต์เหตุการณ์ เพื่อดูรายละเอียดการจัดเรียงข้อมูลในออบเจ็กต์เหตุการณ์ ข้อมูล ที่มีอยู่ในออบเจ็กต์เหตุการณ์ได้รับการควบคุมเพียงบางส่วนโดยค่าของแอตทริบิวต์ gmail.composeTrigger.draftAccess ฟิลด์ไฟล์ Manifest:

• หาก gmail.composeTrigger.draftAccess ฟิลด์ไฟล์ Manifest คือ NONE หรือไม่ได้รวมไว้ เนื่องจากออบเจ็กต์เหตุการณ์มีเพียง ข้อมูลเพียงเล็กน้อย

• หากเป็น gmail.composeTrigger.draftAccess ตั้งค่าเป็น METADATA ซึ่งเป็นออบเจ็กต์เหตุการณ์ที่ส่งไปยังฟังก์ชันทริกเกอร์การเขียน จะมีการเติมรายชื่อผู้รับอีเมลที่เขียน

การแทรกเนื้อหาลงในฉบับร่างที่ใช้งานอยู่

โดยปกติแล้ว UI การเขียนส่วนเสริมของ Google Workspace จะมี ตัวเลือกของผู้ใช้และการควบคุมที่ช่วยเขียนข้อความ สำหรับกรณีการใช้งานเหล่านี้ เมื่อผู้ใช้ทำการเลือกใน UI แล้ว ส่วนเสริมจะตีความสิ่งที่เลือก และอัปเดตร่างอีเมลที่ใช้งานอยู่ในปัจจุบันตามความเหมาะสม

เพื่อช่วยให้คุณอัปเดตอีเมลฉบับร่างปัจจุบันได้ง่ายขึ้น บริการบัตร ได้ขยายไปใช้กับชั้นเรียนต่อไปนี้

• ContentType - enum ที่กำหนดว่าจะเพิ่ม HTML ที่เปลี่ยนแปลงไม่ได้, HTML ที่เปลี่ยนแปลงไม่ได้ (ซึ่ง Gmail ผู้ใช้แก้ไขไม่ได้) หรือเนื้อหาข้อความธรรมดา
• UpdateDraftActionResponse - แสดง การตอบกลับการดำเนินการที่อัปเดตอีเมลฉบับร่างปัจจุบัน
• UpdateDraftActionResponseBuilder - เครื่องมือสร้างสำหรับ UpdateDraftActionResponse ออบเจ็กต์
• UpdateDraftBodyAction - แสดง การดำเนินการที่อัปเดตเนื้อหาของอีเมลฉบับร่างปัจจุบัน
• UpdateDraftBodyType - enum ที่กำหนดการเปลี่ยนแปลงของร่างกาย
• UpdateDraftSubjectAction - แสดง การดำเนินการที่อัปเดตช่องเรื่องของอีเมลฉบับร่างปัจจุบัน
• UpdateDraftToRecipientsAction - แสดง การดำเนินการที่อัปเดต "ถึงผู้รับอีเมลฉบับร่างปัจจุบัน"
• UpdateDraftCcRecipientsAction - แสดง การดำเนินการที่อัปเดตผู้รับสำเนาของอีเมลฉบับร่างปัจจุบัน
• UpdateDraftBccRecipientsAction - แสดง การดำเนินการที่อัปเดตผู้รับสำเนาลับของอีเมลฉบับร่างปัจจุบัน

โดยปกติแล้ว UI การเขียนของส่วนเสริมจะมีปุ่ม "บันทึก" หรือ "Insert" วิดเจ็ตที่ผู้ใช้ สามารถคลิกเพื่อระบุว่าพวกเขาทำการเลือกเสร็จแล้วใน UI และต้องการให้ ตัวเลือกเพื่อเพิ่มลงในอีเมลที่กำลังเขียน หากต้องการเพิ่มรายการนี้ interactivity ของวิดเจ็ต ออบเจ็กต์ Action ที่เชื่อมโยงซึ่ง สั่งให้ส่วนเสริมเรียกใช้ฟังก์ชัน Callback ที่เจาะจงเมื่อวิดเจ็ต คลิกแล้ว คุณต้องใช้ฟังก์ชัน Callback เหล่านี้ ฟังก์ชัน Callback แต่ละรายการควร ส่งคืนบิลด์ 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

ตัวอย่างข้อมูลโค้ดต่อไปนี้แสดงวิธีสร้าง 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;
    }