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

ส่วนเสริมของ Google Workspace ช่วยให้คุณสามารถสร้างอินเทอร์เฟซที่กำหนดเองภายใน โปรแกรมแก้ไข ซึ่งรวมถึง Google เอกสาร, Google ชีต และ 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 ส่วนเสริมจะเปิดใช้สำหรับ เอกสาร ชีต และสไลด์ โดยจะแสดงหน้าแรกทั่วไปในเอกสารและสไลด์ และหน้าแรกที่ไม่ซ้ำกันในชีต ฟังก์ชัน Callback 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 ในส่วนของเอดิเตอร์ที่เหมาะสมในไฟล์ Manifest เช่น หากต้องการสร้างอินเทอร์เฟซนี้ใน Google ชีต ให้เพิ่มทริกเกอร์ลงในส่วน "sheets"
2. ใช้ฟังก์ชันที่ระบุชื่อไว้ในส่วน EDITOR_NAME.onFileScopeGrantedTrigger ฟังก์ชันนี้ รับออบเจ็กต์ เหตุการณ์ เป็นอาร์กิวเมนต์ และต้องแสดงผลออบเจ็กต์ Card รายการเดียวหรืออาร์เรย์ของออบเจ็กต์ Card
3. เช่นเดียวกับการ์ดอื่นๆ คุณต้องใช้ฟังก์ชันเรียกกลับที่ใช้เพื่อมอบ การโต้ตอบของวิดเจ็ตสำหรับอินเทอร์เฟซ เช่น หากคุณใส่ปุ่ม ในอินเทอร์เฟซ ปุ่มนั้นควรมีAction ที่แนบมา และฟังก์ชัน Callback ที่ใช้งาน ซึ่งจะทํางานเมื่อมีการคลิกปุ่ม

ตัวอย่างต่อไปนี้แสดงส่วน addons ของไฟล์ Manifest ของส่วนเสริม Google Workspace ส่วนเสริมใช้ REST API ดังนั้นจึงมี onFileScopeGrantedTrigger สำหรับ Google ชีต เมื่อผู้ใช้ให้สิทธิ์drive.fileขอบเขต ฟังก์ชัน การเรียกกลับ 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 ฟังก์ชันทริกเกอร์ใช้ข้อมูลในออบเจ็กต์เหตุการณ์เพื่อกำหนดวิธี สร้างการ์ดส่วนเสริมหรือควบคุมลักษณะการทำงานของส่วนเสริม

โครงสร้างทั้งหมดของออบเจ็กต์เหตุการณ์อธิบายไว้ในออบเจ็กต์ เหตุการณ์

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

หากส่วนเสริมไม่มีขอบเขต 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"
  },
  ...
}