การสร้างอินเทอร์เฟซ Google Editor

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

การเข้าถึง UI ของส่วนเสริม

คุณสามารถเปิดส่วนเสริมของ Google Workspace ได้ในเครื่องมือแก้ไข หากไอคอนปรากฏในแท็บด่วนของ Google Workspace เข้าถึงแผงด้านข้างทางด้านขวาของผู้ใช้เอกสาร ชีต และสไลด์ อินเทอร์เฟซ

ส่วนเสริมของ Google Workspace สามารถแสดงอินเทอร์เฟซต่อไปนี้

• อินเทอร์เฟซหน้าแรก: หากไฟล์ Manifest ของส่วนเสริม รวมทริกเกอร์ EDITOR_NAME.homepageTrigger สำหรับ Editor ที่ผู้ใช้เปิดส่วนเสริม ส่วนเสริมจะสร้างและส่งคืน การ์ดหน้าแรกสำหรับ บรรณาธิการนั้น หากไฟล์ Manifest ของส่วนเสริมไม่มีองค์ประกอบ EDITOR_NAME.homepageTrigger สำหรับเครื่องมือแก้ไขที่ผู้ใช้เปิด การ์ดหน้าแรกทั่วไปจะแสดงแทน

• อินเทอร์เฟซ REST API: ในกรณีที่ส่วนเสริมใช้ REST API คุณสามารถรวมทริกเกอร์ที่ขอสิทธิ์เข้าถึงเอกสารสำหรับไฟล์แต่ละรายการ โดยใช้ขอบเขต drive.file เมื่อได้รับแล้ว ระบบจะเรียกทริกเกอร์อื่น EDITOR_NAME.onFileScopeGrantedTrigger ประมวลผลและ จะแสดงอินเทอร์เฟซสำหรับไฟล์นั้นโดยเฉพาะ

• อินเทอร์เฟซตัวอย่างลิงก์: หากส่วนเสริม ผสานรวมกับบริการของบุคคลที่สาม คุณจะสามารถสร้างการ์ดที่แสดงตัวอย่าง เนื้อหาจาก URL ของบริการ

การสร้างอินเทอร์เฟซสำหรับส่วนเสริมเครื่องมือแก้ไข

สร้างอินเทอร์เฟซส่วนเสริมของเครื่องมือแก้ไขสำหรับเครื่องมือแก้ไขโดยทำตามขั้นตอนต่อไปนี้

1. เพิ่ม addOns.common addOns.docs addOns.sheets และ addOns.slides ลงในโปรเจ็กต์สคริปต์ส่วนเสริมไฟล์ Manifest ของส่วนเสริม
2. เพิ่มขอบเขตเครื่องมือแก้ไขที่จำเป็นลงใน ไฟล์ Manifest ของโปรเจ็กต์สคริปต์
3. หากคุณระบุหน้าแรกสำหรับบรรณาธิการโดยเฉพาะ ติดตั้งใช้งาน EDITOR_NAME.homepageTrigger ในการสร้างอินเทอร์เฟซ หากไม่ ให้ใช้ common.homepageTrigger เพื่อสร้างหน้าแรกทั่วไปสำหรับแอปของโฮสต์
4. หากคุณใช้ API ของ REST ให้ใช้ขั้นตอนการให้สิทธิ์ขอบเขต drive.file และ EDITOR_NAME.onFileScopeGrantedTrigger ทริกเกอร์ฟังก์ชันเพื่อแสดงอินเทอร์เฟซเฉพาะสำหรับไฟล์ที่เปิดอยู่ สำหรับข้อมูลเพิ่มเติม โปรดดูข้อมูลเพิ่มเติมที่อินเทอร์เฟซ REST API
5. หากคุณกำลังกำหนดค่าตัวอย่างลิงก์จากบริการของบุคคลที่สาม ให้ใช้ ขั้นตอนการให้สิทธิ์ขอบเขต https://www.googleapis.com/auth/workspace.linkpreview และ linkPreviewTriggers สำหรับข้อมูลเพิ่มเติม โปรดดู ลิงก์อินเทอร์เฟซตัวอย่าง
6. ใช้ฟังก์ชัน Callback ที่เกี่ยวข้องซึ่งจำเป็นต่อการตอบสนองคำสั่งของผู้ใช้ การโต้ตอบกับ UI เช่น การคลิกปุ่ม

หน้าแรกของเครื่องมือแก้ไข

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

ฟังก์ชันทริกเกอร์หน้าแรกถูกส่งผ่านออบเจ็กต์เหตุการณ์ เป็นพารามิเตอร์ที่มีข้อมูล เช่น แพลตฟอร์มของลูกค้า คุณสามารถ ใช้ข้อมูลออบเจ็กต์เหตุการณ์เพื่อปรับแต่งการสร้างหน้าแรก

คุณสามารถนำเสนอหน้าแรกทั่วไปหรือหน้าแรกเฉพาะสำหรับ Editor ได้ ผู้ใช้เปิดส่วนเสริมของคุณขึ้นมา

แสดงหน้าแรกที่ใช้ร่วมกัน

หากต้องการแสดงหน้าแรกที่ใช้บ่อยของส่วนเสริมในเครื่องมือแก้ไข ให้ใส่ ช่องเครื่องมือแก้ไข เช่น addOns.docs addOns.sheets หรือ addOns.slides ในไฟล์ Manifest ของส่วนเสริม

ตัวอย่างต่อไปนี้แสดงส่วน addons ของส่วนเสริม Google Workspace ไฟล์ Manifest ส่วนเสริมนี้ขยายให้เอกสาร ชีต และสไลด์ และแสดง หน้าแรกในแอปโฮสต์แต่ละแอป

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

แสดงหน้าแรกของ Editor โดยเฉพาะ

หากต้องการนำเสนอหน้าแรกสำหรับ Editor โดยเฉพาะ ให้เพิ่ม EDITOR_NAME.homepageTrigger ลงในส่วนเสริม ไฟล์ Manifest

ตัวอย่างต่อไปนี้แสดงส่วน addons ของไฟล์ Manifest ของส่วนเสริม Google Workspace ส่วนเสริมจะเปิดใช้สำหรับเอกสาร ชีต และสไลด์ โดยแสดงกลุ่มเป้าหมายทั่วไป หน้าแรกในเอกสารและสไลด์ และหน้าแรกที่ไม่ซ้ำกันในชีต การติดต่อกลับ ฟังก์ชัน onSheetsHomepage จะสร้างการ์ดหน้าแรกสำหรับชีตโดยเฉพาะ

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

อินเทอร์เฟซ API ของ REST

หากส่วนเสริมใช้ REST API เช่น Google Sheets API ให้ทำดังนี้ คุณสามารถใช้ฟังก์ชัน onFileScopeGrantedTrigger เพื่อแสดงอินเทอร์เฟซใหม่ เฉพาะไฟล์ที่เปิดในแอปโฮสต์ของ Editor

คุณต้องใส่ขั้นตอนการให้สิทธิ์ขอบเขต drive.file เพื่อใช้ onFileScopeGrantedTrigger หากต้องการทราบวิธีขอdrive.file โปรดดูขอบเขตที่หัวข้อขอสิทธิ์เข้าถึงไฟล์สำหรับเอกสารปัจจุบัน

เมื่อผู้ใช้ให้สิทธิ์ขอบเขต drive.file ค่า EDITOR_NAME.onFileScopeGrantedTrigger.runFunction ไฟไหม้ เมื่อทริกเกอร์เริ่มทำงาน ทริกเกอร์จะเรียกใช้ฟังก์ชันทริกเกอร์ตามบริบท ที่ระบุโดยช่อง EDITOR_NAME.onFileScopeGrantedTrigger.runFunction ใน ไฟล์ Manifest ของส่วนเสริม

หากต้องการสร้างอินเทอร์เฟซ API ของ REST สำหรับผู้แก้ไขรายใดรายหนึ่ง ให้ทำตามขั้นตอนด้านล่าง แทนที่ EDITOR_NAME ด้วยแอปโฮสต์ Editor ที่คุณเลือก เช่น sheets.onFileScopeGrantedTrigger

1. รวม EDITOR_NAME.onFileScopeGrantedTrigger ในส่วนเครื่องมือแก้ไขที่เหมาะสมของไฟล์ Manifest ตัวอย่างเช่น หากคุณ ต้องการสร้างอินเทอร์เฟซนี้ใน Google ชีต ให้เพิ่มทริกเกอร์ลงใน ส่วน"sheets"
2. ใช้ฟังก์ชันที่มีชื่อใน EDITOR_NAME.onFileScopeGrantedTrigger ฟังก์ชันนี้ยอมรับออบเจ็กต์เหตุการณ์เป็นอาร์กิวเมนต์และต้องแสดงค่าเพียงรายการเดียว Card หรืออาร์เรย์ของออบเจ็กต์ Card
3. เช่นเดียวกับการ์ดอื่นๆ คุณต้องใช้ฟังก์ชัน Callback ที่ใช้เพื่อจัดเตรียม การโต้ตอบกับวิดเจ็ตสำหรับอินเทอร์เฟซ เช่น หากคุณใส่ปุ่ม ในอินเทอร์เฟซ ควรมีการดำเนินการแนบอยู่ และฟังก์ชัน Callback ที่ติดตั้งใช้งานซึ่งทำงานเมื่อปุ่ม ที่มีการคลิก

ตัวอย่างต่อไปนี้แสดงส่วน addons ของไฟล์ Manifest ของส่วนเสริม Google Workspace ส่วนเสริมใช้ API ของ REST เพื่อให้มีการรวม onFileScopeGrantedTrigger สำหรับ Google ชีต เมื่อผู้ใช้ให้สิทธิ์ขอบเขต drive.file ฟังก์ชัน Callback onFileScopeGrantedSheets จะสร้างอินเทอร์เฟซเฉพาะไฟล์

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

ลิงก์อินเทอร์เฟซตัวอย่างสำหรับบริการของบุคคลที่สาม

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

สำหรับขั้นตอนในการเปิดตัวอย่างลิงก์ โปรดดูที่ แสดงตัวอย่างลิงก์ด้วยชิปอัจฉริยะ

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

ออบเจ็กต์เหตุการณ์สร้างขึ้นและส่งผ่านเพื่อทริกเกอร์ฟังก์ชัน เช่น EDITOR_NAME.homepageTrigger หรือ EDITOR_NAME.onFileScopeGrantedTrigger ฟังก์ชันทริกเกอร์ใช้ข้อมูลใน เพื่อกำหนดวิธีสร้างการ์ดส่วนเสริมหรือควบคุม ของส่วนเสริม

โครงสร้างที่สมบูรณ์ของออบเจ็กต์เหตุการณ์มีอธิบายอยู่ในออบเจ็กต์เหตุการณ์

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

หากส่วนเสริมไม่มีการให้สิทธิ์ขอบเขต drive.file สำหรับผู้ใช้ปัจจุบัน หรือเอกสาร ออบเจ็กต์เหตุการณ์จะมีเฉพาะ docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission หรือ slides.addonHasFileScopePermission หากส่วนเสริมมี ออบเจ็กต์เหตุการณ์จะมีช่องออบเจ็กต์เหตุการณ์ของ Editor ทั้งหมด

ตัวอย่างต่อไปนี้แสดงออบเจ็กต์เหตุการณ์ของ Editor ที่ส่งไปยัง sheets.onFileScopeGrantedTrigger ในส่วนนี้ ส่วนเสริมจะมีส่วน drive.file การให้สิทธิ์ขอบเขตสำหรับเอกสารปัจจุบัน:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }