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

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

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

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

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

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

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

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

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

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

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

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

  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];
  }