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

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

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

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

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

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

การสร้างส่วนเสริมการเขียน

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

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

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

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

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

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

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

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

  • หากช่องไฟล์ Manifest gmail.composeTrigger.draftAccess คือ 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 การเขียนส่วนเสริมจะมี 'บันทึก' หรือ 'แทรก&#39 วิดเจ็ตที่ผู้ใช้สามารถคลิกเพื่อระบุว่าทําการเลือกใน UI และต้องการเพิ่มตัวเลือกลงในอีเมลที่กําลังเขียนอยู่ หากต้องการเพิ่มการโต้ตอบนี้ วิดเจ็ตควรมีออบเจ็กต์ 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

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