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

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

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

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

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

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

  • อินเทอร์เฟซ 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 โดยเฉพาะ ให้ใช้ฟังก์ชัน 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 ของผู้ใช้ เช่น การคลิกปุ่ม

หน้าแรกของ Editor

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

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

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

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

หากต้องการแสดงหน้าแรกที่พบบ่อยของส่วนเสริมในเครื่องมือแก้ไข ให้ใส่ช่อง Editor ที่เหมาะสม เช่น 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_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

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

ตัวอย่างต่อไปนี้แสดงส่วน 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"
          },
          ...
        }