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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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