หน้าแรกเป็นฟีเจอร์ส่วนเสริมใหม่ของ Google Workspace ที่ช่วยให้คุณกำหนดการ์ดที่ไม่ใช่บริบทได้อย่างน้อย 1 รายการ ระบบใช้การ์ดที่ไม่ใช่บริบทเพื่อแสดงอินเทอร์เฟซผู้ใช้เมื่อผู้ใช้อยู่นอกบริบทที่กำหนด เช่น เมื่อผู้ใช้กำลังดูกล่องจดหมาย Gmail แต่ยังไม่ได้เปิดข้อความหรือฉบับร่าง
หน้าแรกช่วยให้คุณแสดงเนื้อหาที่ไม่ใช่ตามบริบทได้ เช่นเดียวกับ แอป Google ใน แผงด้านข้างเพื่อการเข้าถึงด่วน (Keep, ปฏิทิน และ Tasks) หน้าแรกยังสามารถเป็นจุดเริ่มต้นเริ่มต้นเมื่อผู้ใช้เปิดส่วนเสริมของคุณเป็นครั้งแรก และมีประโยชน์ในการสอนผู้ใช้รายใหม่ให้รู้จักกับส่วนเสริมของคุณ
คุณกำหนดหน้าแรกของส่วนเสริมได้ด้วยการระบุหน้าแรกในไฟล์ Manifest ของโปรเจ็กต์และใช้ฟังก์ชัน homepageTrigger
อย่างน้อย 1 รายการ (ดูการกำหนดค่าหน้าแรก)
คุณมีหน้าแรกได้หลายหน้า โดยแต่ละหน้าแรกสำหรับแต่ละแอปพลิเคชันโฮสต์ที่ส่วนเสริมของคุณขยายออกไป คุณยังสามารถเลือกกำหนดหน้าแรกเริ่มต้นทั่วไปรายการเดียวที่ใช้ในโฮสต์ที่ไม่ได้ระบุหน้าแรกที่กำหนดเอง
หน้าแรกของส่วนเสริมจะแสดงขึ้นเมื่อตรงกับเงื่อนไขข้อใดข้อหนึ่งต่อไปนี้
- เมื่อเปิดส่วนเสริมในโฮสต์เป็นครั้งแรก (หลังการให้สิทธิ์)
- เมื่อผู้ใช้เปลี่ยนจากบริบทที่เป็นบริบทเป็นบริบทที่ไม่ใช่บริบทขณะส่วนเสริมเปิดอยู่ เช่น เปลี่ยนจากการแก้ไขกิจกรรมในปฏิทิน ไปยังปฏิทินหลัก
- เมื่อผู้ใช้คลิกปุ่มย้อนกลับมากพอเพื่อนำการ์ดอื่นๆ ออกจากสแต็กภายใน
- เมื่อการโต้ตอบของ UI ในการ์ดที่ไม่ใช่บริบทส่งผลให้เกิดการเรียกใช้
Navigation.popToRoot()
เราไม่ได้บังคับให้ออกแบบหน้าแรกแต่แนะนำอย่างยิ่ง หากคุณไม่ให้คำจำกัดความ ระบบจะใช้การ์ดทั่วไปที่มีชื่อส่วนเสริมของคุณทุกครั้งที่ผู้ใช้ไปยังหน้าแรก
การกำหนดค่าหน้าแรก
ส่วนเสริมของ Google Workspace จะใช้ช่อง addOns.common.homepageTrigger
เพื่อกำหนดค่าเนื้อหาส่วนเสริมหน้าแรก (ที่ไม่ใช่ตามบริบท) สำหรับแอปพลิเคชันโฮสต์ทั้งหมดในไฟล์ Manifest ของส่วนเสริม ดังนี้
{
// ...
"addOns": {
// ...
"common": {
// ...
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction
: ชื่อของฟังก์ชัน Apps Script ที่เฟรมเวิร์กส่วนเสริมของ Google Workspace เรียกใช้เพื่อแสดงผลการ์ดส่วนเสริมในหน้าแรก ฟังก์ชันนี้คือฟังก์ชันทริกเกอร์หน้าแรก ฟังก์ชันนี้ต้องสร้างและแสดงผลอาร์เรย์ของออบเจ็กต์Card
ที่ประกอบกันเป็น UI ของหน้าแรก หากมีการส่งคืนการ์ดมากกว่า 1 รายการ แอปพลิเคชันโฮสต์จะแสดงส่วนหัวของการ์ดในรายการที่ผู้ใช้สามารถเลือกได้ (โปรดดูการส่งคืนการ์ดหลายใบ)enabled
: ควรเปิดใช้การ์ดหน้าแรกสําหรับขอบเขตนี้หรือไม่ ช่องนี้เป็นแบบไม่บังคับและมีค่าเริ่มต้นเป็นtrue
การตั้งค่านี้เป็นfalse
จะทำให้การ์ดหน้าแรกถูกปิดใช้งานสำหรับโฮสต์ทั้งหมด (เว้นแต่จะมีการลบล้างสำหรับโฮสต์นั้น โปรดดูด้านล่าง)
นอกเหนือจากการกำหนดค่าทั่วไปแล้ว ยังมีการลบล้างต่อโฮสต์ที่มีโครงสร้างเหมือนกันทั้งหมดในการกำหนดค่าของแอปพลิเคชันโฮสต์แต่ละรายการที่ addOns.gmail.homepageTrigger
, addOns.calendar.homepageTrigger
ฯลฯ
{
...
"addOns": {
...
"common": {
// By default, call 'buildHomePage' to render homepage content
// in all hosts. Since calendar.homepageTrigger below overrides
// this in Calendar and Drive and the homepageTrigger is disabled
// for Gmail, this homepage function never executes.
"homepageTrigger": { "runFunction": "buildHomePage" }
},
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "buildCalendarHomepage" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "buildDriveHomepage" }
}
"gmail": {
// Disable homepage add-on content in Gmail.
"homepageTrigger": { "enabled": false }
},
...
}
}
โปรดทราบว่าข้อมูลนี้เหมือนกับข้อความที่ตัดตอนมาจากไฟล์ Manifest ต่อไปนี้
{
...
"addOns": {
...
"common": { /* ... */ }, // Omitted a default homepageTrigger specification.
"calendar": {
// Show customized homepage content for Calendar only.
"homepageTrigger": { "runFunction": "myCalendarFunction" }
},
"drive": {
// Show customized homepage content for Drive only.
"homepageTrigger": { "runFunction": "myDriveFunction" }
}
"gmail": { /* ... */ },
...
}
}
ไม่จำเป็นต้องระบุทั้ง homepageTrigger
หัวข้อ อย่างไรก็ตาม UI ที่แสดงสำหรับส่วนเสริมในผลิตภัณฑ์โฮสต์หนึ่งๆ จะขึ้นอยู่กับการมีช่องไฟล์ Manifest ที่เกี่ยวข้อง และมี homepageTrigger
ที่เชื่อมโยงหรือไม่ ตัวอย่างต่อไปนี้แสดงฟังก์ชันทริกเกอร์ของส่วนเสริมที่ดำเนินการ (หากมี) เพื่อสร้าง UI หน้าแรกสำหรับการกำหนดค่าไฟล์ Manifest แบบต่างๆ
ออบเจ็กต์เหตุการณ์ในหน้าแรก
เมื่อเรียกใช้ ฟังก์ชันทริกเกอร์หน้าแรก (runFunction
) ที่อธิบายไว้ข้างต้นจะส่งออบเจ็กต์เหตุการณ์ที่มีข้อมูลจากบริบทการเรียกใช้
ออบเจ็กต์เหตุการณ์ในหน้าแรกไม่มีวิดเจ็ตหรือข้อมูลตามบริบท ข้อมูลที่ส่งจะจำกัดลงในช่อง ออบเจ็กต์เหตุการณ์ทั่วไปต่อไปนี้
commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale
และcommonEventObject.userTimezone
(แต่ดูข้อมูลข้อจำกัดได้ที่การเข้าถึงภาษาและเขตเวลาของผู้ใช้)
ดูรายละเอียดเพิ่มเติมในออบเจ็กต์เหตุการณ์
การ์ดอื่นๆ ที่ไม่ใช่ตามบริบท
UI ของส่วนเสริมอาจมีการ์ดอื่นๆ ที่ไม่ตามบริบทซึ่งไม่ใช่หน้าแรก เช่น หน้าแรกอาจมีปุ่มที่เปิดการ์ด "การตั้งค่า" ที่ผู้ใช้สามารถปรับการตั้งค่าส่วนเสริมได้ (ในกรณีส่วนใหญ่ การตั้งค่าดังกล่าวจะไม่ขึ้นอยู่กับบริบทและอาจไม่ใช่ตามบริบท)
การ์ดที่ไม่ใช่บริบทสร้างขึ้นเหมือนกับการ์ดอื่นๆ ความแตกต่างเพียงอย่างเดียวคือการดำเนินการหรือเหตุการณ์จะสร้างและแสดงการ์ดนั้น ดูรายละเอียดเกี่ยวกับวิธีสร้างการเปลี่ยนระหว่างการ์ดได้ที่วิธีการไปยังส่วนต่างๆ