หน้าแรก

หน้าแรกคือฟีเจอร์ใหม่ของส่วนเสริม 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) ที่อธิบายไว้ข้างต้นจะได้รับออบเจ็กต์เหตุการณ์ที่มีข้อมูลจากบริบทการเรียกใช้

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

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

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

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

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