การขยาย UI ข้อความ

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

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

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

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

การสร้างส่วนเสริมข้อความ

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

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

ทริกเกอร์ตามบริบท

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

ระบบจะกำหนดทริกเกอร์ตามบริบทในไฟล์ Manifest ของโปรเจ็กต์ส่วนเสริม คําจํากัดความทริกเกอร์จะบอก Gmail ว่าให้เรียกใช้ฟังก์ชันทริกเกอร์ใดภายใต้เงื่อนไขใด ตัวอย่างเช่น ข้อมูลโค้ดนี้กำหนดทริกเกอร์แบบไม่มีเงื่อนไขซึ่งเรียกใช้ฟังก์ชันทริกเกอร์ onGmailMessageOpen() เมื่อเปิดข้อความ

{   ...   "addOns": {      "common": {       ...     },     "gmail": {       "contextualTriggers": [         {           "unconditional": {},           "onTriggerFunction": "onGmailMessageOpen"         }       ],       ...     },     ...   }   ... }

ฟังก์ชันทริกเกอร์ตามบริบท

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

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

  // Activate temporary Gmail scopes, in this case to allow   // the add-on to read message metadata and content.   var accessToken = e.gmail.accessToken;   GmailApp.setCurrentMessageAccessToken(accessToken);    // Read message metadata and content. This requires the Gmail scope   // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.   var messageId = e.gmail.messageId;   var message = GmailApp.getMessageById(messageId);   var subject = message.getSubject();   var sender = message.getFrom();   var body = message.getPlainBody();   var messageDate = message.getDate();    // Setting the access token with a gmail.addons.current.message.readonly   // scope also allows read access to the other messages in the thread.   var thread = message.getThread();   var threadMessages = thread.getMessages();    // Using this link can avoid the need to copy message or thread content   var threadLink = thread.getPermalink(); 

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

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

  function onGmailMessageOpen(e) {     // Activate temporary Gmail scopes, in this case to allow     // message metadata to be read.     var accessToken = e.gmail.accessToken;     GmailApp.setCurrentMessageAccessToken(accessToken);      var messageId = e.gmail.messageId;     var message = GmailApp.getMessageById(messageId);     var subject = message.getSubject();     var sender = message.getFrom();      // Create a card with a single card section and two widgets.     // Be sure to execute build() to finalize the card construction.     var exampleCard = CardService.newCardBuilder()         .setHeader(CardService.newCardHeader()             .setTitle('Example card'))         .addSection(CardService.newCardSection()             .addWidget(CardService.newKeyValue()                 .setTopLabel('Subject')                 .setContent(subject))             .addWidget(CardService.newKeyValue()                 .setTopLabel('From')                 .setContent(sender)))         .build();   // Don't forget to build the Card!     return [exampleCard];   }