นอกจากอินเทอร์เฟซแบบการ์ดเมื่อผู้ใช้อ่านข้อความ Gmail แล้ว ส่วนเสริม Google Workspace ที่ขยายความสามารถของ Gmail ยังอาจแสดงอินเทอร์เฟซอื่นเมื่อผู้ใช้เขียนข้อความใหม่หรือตอบกลับข้อความที่มีอยู่ ซึ่งจะช่วยให้ส่วนเสริมของ Google Workspace ทำงานเขียนอีเมลให้ผู้ใช้ได้โดยอัตโนมัติ
การเข้าถึง UI การเขียนของส่วนเสริม
คุณดู UI ของส่วนประกอบของส่วนเสริมได้ 2 วิธี วิธีแรกคือการเริ่มเขียนฉบับร่างใหม่หรือตอบกลับขณะที่ส่วนเสริมเปิดอยู่ วิธีที่สองคือการเริ่มส่วนเสริมขณะเขียนฉบับร่าง
ไม่ว่าจะด้วยกรณีใด การดำเนินการดังกล่าวจะทำให้ส่วนเสริมเรียกใช้ฟังก์ชันคอมโพสิททริกเกอร์ที่เกี่ยวข้องซึ่งกำหนดไว้ในไฟล์ Manifest ของส่วนเสริม ฟังก์ชันทริกเกอร์การเขียนจะสร้าง UI การเขียนสําหรับการดําเนินการเขียนนั้น จากนั้น Gmail จะแสดงต่อผู้ใช้
การสร้างส่วนเสริมการเขียน
คุณเพิ่มฟังก์ชันการเขียนลงในส่วนเสริมได้โดยทำตามขั้นตอนทั่วไปต่อไปนี้
- เพิ่มช่อง
gmail.composeTrigger
ลงในไฟล์ Manifest ของโปรเจ็กต์สคริปต์ส่วนเสริม และอัปเดตขอบเขตของไฟล์ Manifest ให้รวมขอบเขตที่จำเป็นสำหรับการดำเนินการเขียน - ใช้ฟังก์ชันทริกเกอร์การคอมโพสที่สร้าง UI การคอมโพสเมื่อทริกเกอร์เริ่มทํางาน ฟังก์ชันทริกเกอร์การเขียนจะแสดงผลออบเจ็กต์
Card
รายการเดียวหรืออาร์เรย์ออบเจ็กต์Card
ที่ประกอบกันเป็น UI การเขียนสําหรับการดําเนินการเขียน - ใช้ฟังก์ชัน 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; }