การสร้างอินเทอร์เฟซ 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"
          },
          ...
        }