หน้าแรก

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

หน้าแรกช่วยให้คุณแสดงเนื้อหาที่ไม่ขึ้นกับบริบทได้ ซึ่งคล้ายกับแอป Google ใน แผงด้านข้างสำหรับการเข้าถึงด่วน (Google Keep, Google ปฏิทิน และ Google Tasks) นอกจากนี้ หน้าแรกยังเป็นจุดเริ่มต้นเมื่อผู้ใช้เปิดส่วนเสริมเป็นครั้งแรก และมีประโยชน์ในการสอนผู้ใช้ใหม่ให้ทราบวิธีโต้ตอบกับส่วนเสริม

กำหนดหน้าแรกสำหรับส่วนเสริมโดยระบุใน ไฟล์ Manifest ของโปรเจ็กต์และใช้ฟังก์ชัน homepageTrigger อย่างน้อย 1 ฟังก์ชัน (ดูการกำหนดค่าหน้าแรก)

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

ระบบจะแสดงหน้าแรกของส่วนเสริมในกรณีต่อไปนี้

  • เมื่อเปิดส่วนเสริมในโฮสต์เป็นครั้งแรก (หลังจากให้สิทธิ์)
  • เมื่อผู้ใช้เปลี่ยนจากบริบทที่ขึ้นกับบริบทเป็นบริบทที่ไม่ขึ้นกับบริบทขณะที่ส่วนเสริมเปิดอยู่ เช่น จากการแก้ไขกิจกรรมในปฏิทินไปเป็นปฏิทินหลัก
  • เมื่อผู้ใช้คลิกปุ่มย้อนกลับหลายครั้งจนการ์ดอื่นๆ ทั้งหมด หลุดออกจากสแต็กภายใน
  • เมื่อการโต้ตอบกับ UI ในการ์ดที่ไม่ขึ้นกับบริบททำให้เกิดการเรียก Navigation.popToRoot

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

การกำหนดค่าหน้าแรก

ส่วนเสริมของ Google Workspace ใช้ฟิลด์ addOns.common.homepageTrigger เพื่อ กำหนดค่าเนื้อหาส่วนเสริมหน้าแรกเริ่มต้น (ที่ไม่ขึ้นกับบริบท) สำหรับแอปพลิเคชันโฮสต์ใน ไฟล์ Manifest ของส่วนเสริม

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction: ชื่อฟังก์ชัน Google Apps Script ที่เฟรมเวิร์กส่วนเสริมของ Google Workspace เรียกใช้เพื่อแสดงการ์ดส่วนเสริมหน้าแรก ฟังก์ชันนี้คือ ฟังก์ชันทริกเกอร์หน้าแรก ฟังก์ชันนี้ต้องสร้าง และแสดงผลอาร์เรย์ของ Card ออบเจ็กต์ที่ประกอบขึ้นเป็น UI ของหน้าแรก หากแสดงผลการ์ดมากกว่า 1 รายการ แอปพลิเคชันโฮสต์จะแสดงส่วนหัวของการ์ดในรายการที่ผู้ใช้เลือกได้ (ดู การแสดงผลการ์ดหลายรายการ)

  • enabled: ระบุว่าควรเปิดใช้การ์ดหน้าแรกสำหรับขอบเขตนี้หรือไม่ ฟิลด์นี้ไม่บังคับและมีค่าเริ่มต้นเป็น true การตั้งค่าเป็น false จะทำให้การ์ดหน้าแรกถูกปิดใช้สำหรับโฮสต์ทั้งหมด (เว้นแต่จะมีการลบล้างสำหรับโฮสต์นั้นๆ โปรดดูการกำหนดค่าเฉพาะโฮสต์)

โฮสต์จะใช้หน้าแรกทั่วไปได้ก็ต่อเมื่อทั้ง addOns.common.homepageTrigger และทรัพยากรระดับบนสุดของโฮสต์ อยู่ในไฟล์ Manifest ของส่วนเสริม ตัวอย่างเช่น หาก addOns.gmailไม่อยู่ในไฟล์ Manifest ระบบจะปิดใช้ส่วนเสริม สำหรับ Gmail และจะไม่แสดงหน้าแรกหรือฟังก์ชันอื่นๆ ใน โฮสต์นั้น

นอกจากการกำหนดค่าทั่วไปแล้ว การลบล้างต่อโฮสต์ที่มีโครงสร้างเหมือนกันยังใช้ได้ในการกำหนดค่าของแอปพลิเคชันโฮสต์แต่ละรายการที่ addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger และทริกเกอร์อื่นๆ ที่เฉพาะเจาะจงโฮสต์

ตัวอย่างต่อไปนี้แสดงไฟล์ Manifest ที่กำหนดทริกเกอร์หน้าแรกทั่วไป แต่มีการลบล้างด้วยฟังก์ชันที่กำหนดเองสำหรับปฏิทินและไดรฟ์ และปิดใช้สำหรับ Gmail ในการกำหนดค่านี้ ฟังก์ชัน buildHomePage ทั่วไปจะไม่ทำงานเนื่องจากมีการลบล้างหรือปิดใช้โฮสต์

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

ข้อมูลต่อไปนี้จากไฟล์ Manifest เทียบเท่ากับตัวอย่างก่อนหน้า แม้ว่าจะมีการละเว้น homepageTrigger เริ่มต้นและการกำหนดค่า Gmail ก็ตาม

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

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

แผนภาพแสดงขั้นตอนการดำเนินการฟังก์ชันทริกเกอร์หน้าแรกของส่วนเสริม

ออบเจ็กต์เหตุการณ์หน้าแรก

เมื่อมีการเรียกใช้ ฟังก์ชันทริกเกอร์หน้าแรก (runFunction) ที่อธิบายไว้ก่อนหน้านี้ จะได้รับ ออบเจ็กต์เหตุการณ์ ที่มีข้อมูลจากบริบทการเรียกใช้

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

ดูรายละเอียดเพิ่มเติมได้ที่ออบเจ็กต์เหตุการณ์

การ์ดอื่นๆ ที่ไม่ขึ้นกับบริบท

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

การ์ดที่ไม่ขึ้นกับบริบทจะสร้างขึ้นเหมือนกับการ์ดอื่นๆ ความแตกต่างเพียงอย่างเดียวคือการดำเนินการหรือเหตุการณ์ใดที่สร้างและแสดงการ์ด ดูรายละเอียดเกี่ยวกับวิธีสร้างการเปลี่ยนผ่านระหว่างการ์ดได้ที่ วิธีการนำทาง