หน้าแรก

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

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

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

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

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

  • เมื่อเปิดส่วนเสริมในโฮสต์เป็นครั้งแรก (หลังจากให้สิทธิ์)
  • เมื่อผู้ใช้เปลี่ยนจากบริบทตามบริบทเป็นบริบทที่ไม่ใช่บริบท ขณะที่ส่วนเสริมเปิดอยู่ เช่น จากการ แก้ไขกิจกรรมในปฏิทินไปยังปฏิทิน หลัก
  • เมื่อผู้ใช้คลิกปุ่มย้อนกลับหลายครั้งพอที่จะแสดงการ์ดทุกๆ การ์ดอื่น ออกจากกองภายใน
  • เมื่อการโต้ตอบ 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 ของส่วนเสริมอาจมี การ์ดเพิ่มเติมที่ไม่ใช่บริบทและไม่ใช่หน้าแรก เช่น หน้าแรกอาจมีปุ่ม ที่เปิดการ์ด "การตั้งค่า" เพื่อปรับการตั้งค่าส่วนเสริม (โดยปกติแล้วการตั้งค่าดังกล่าวจะไม่ขึ้นอยู่กับบริบท)

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