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

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

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

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

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

• อินเทอร์เฟซหน้าแรก: หากไฟล์ Manifest ของส่วนเสริมมีทริกเกอร์ EDITOR_NAME.homepageTrigger สำหรับเอดิเตอร์ที่ผู้ใช้เปิดส่วนเสริม ส่วนเสริมจะสร้างและแสดงการ์ดหน้าแรกสำหรับ เอดิเตอร์นั้นโดยเฉพาะ หากไฟล์ 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. หากใช้ REST API ให้ใช้drive.fileโฟลว์การให้สิทธิ์ขอบเขต และ EDITOR_NAME.onFileScopeGrantedTrigger ฟังก์ชันทริกเกอร์เพื่อแสดงอินเทอร์เฟซที่เจาะจงสำหรับไฟล์ที่เปิด ดูข้อมูลเพิ่มเติมได้ที่อินเทอร์เฟซ REST API
5. หากกําหนดค่าการแสดงตัวอย่างลิงก์จากบริการของบุคคลที่สาม ให้ใช้ https://www.googleapis.com/auth/workspace.linkpreviewโฟลว์การให้สิทธิ์ขอบเขตและ ฟังก์ชัน linkPreviewTriggers ดูข้อมูลเพิ่มเติมได้ที่ อินเทอร์เฟซการแสดงตัวอย่างลิงก์
6. ใช้ฟังก์ชันเรียกกลับที่เชื่อมโยงที่จำเป็นเพื่อตอบสนองต่อการโต้ตอบ UI ของผู้ใช้ เช่น การคลิกปุ่ม

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

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

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

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

แสดงหน้าแรกทั่วไป

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

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

 "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_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"
     },
  }
}

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงส่วน addons ของไฟล์ Manifest ของส่วนเสริม Google Workspace ส่วนเสริมนี้ใช้ REST API ดังนั้น 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 เป็นแอปโฮสต์ที่ใช้งานของส่วนเสริม ออบเจ็กต์เหตุการณ์จะมีฟิลด์ออบเจ็กต์เหตุการณ์ของ Docs, Sheets หรือ Slides ที่มีข้อมูลไคลเอ็นต์

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

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

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