ขยาย UI ของข้อความ

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

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

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

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

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

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

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

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

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

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

{
  ...
  "addOns": {

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

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

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

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

// 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}