หน้าแรก

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

หน้าแรกเป็นฟีเจอร์ใหม่ของส่วนเสริม 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 }
        },
        ...
      }
    }

โปรดทราบว่าการดําเนินการนี้เทียบเท่ากับข้อความที่ตัดตอนมาต่อไปนี้

    {
      ...
      "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) ที่อธิบายไว้ข้างต้นจะส่งผ่านออบเจ็กต์เหตุการณ์ซึ่งมีข้อมูลจากบริบทการเรียกใช้

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

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

การ์ดอื่นๆ ที่ไม่ใช่บริบท

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

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