การสร้างอินเทอร์เฟซ 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 ของบริการได้

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

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

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. ใช้ฟังก์ชัน Callback ที่เชื่อมโยงกันซึ่งจําเป็นต่อการตอบสนองต่อการโต้ตอบ 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 โดยเฉพาะ

หากต้องการแสดงหน้าแรกสำหรับ 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"
     },
  }
}

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

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

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

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

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

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

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

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