Membuat antarmuka Google Editor

Dengan Add-on Google Workspace, Anda dapat menyediakan antarmuka yang disesuaikan di dalam Editor, termasuk Google Dokumen, Spreadsheet, dan Slide. Hal ini memungkinkan Anda memberi pengguna informasi yang relevan, mengotomatiskan tugas, dan menghubungkan sistem pihak ketiga ke Editor.

Mengakses UI add-on

Anda dapat membuka Add-on Google Workspace di Editor jika ikonnya muncul di setelan cepat Google Workspace akses panel samping di sisi kanan pengguna Dokumen, Spreadsheet, dan Slide antarmuka.

Add-on Google Workspace dapat menyajikan antarmuka berikut:

  • Antarmuka halaman beranda: Jika manifes add-on menyertakan pemicu EDITOR_NAME.homepageTrigger untuk Editor tempat pengguna membuka add-on, add-on membangun dan mengembalikan kartu halaman beranda khusus untuk Editor tersebut. Jika manifes add-on tidak menyertakan EDITOR_NAME.homepageTrigger untuk Editor yang dibuka pengguna kartu tersebut, sebuah kartu halaman beranda umum akan ditampilkan.

  • Antarmuka REST API: Jika add-on menggunakan REST API, Anda dapat menyertakan pemicu yang meminta akses per file ke dokumen menggunakan cakupan drive.file. Setelah diberikan, pemicu lain yang disebut EDITOR_NAME.onFileScopeGrantedTrigger dieksekusi dan menampilkan antarmuka khusus untuk file tersebut.

  • Antarmuka pratinjau link: Jika add-on Anda terintegrasi dengan layanan pihak ketiga, Anda dapat membuat kartu yang melihat pratinjau konten dari URL layanan Anda.

Membangun antarmuka untuk Add-on Editor

Buat antarmuka Add-on Editor untuk Editor dengan mengikuti langkah-langkah berikut:

  1. Tambahkan atribut addOns.common, addOns.docs, addOns.sheets, dan addOns.slides ke project skrip add-on manifes.
  2. Tambahkan Cakupan Editor yang diperlukan ke manifes project skrip Anda.
  3. Jika Anda menyediakan halaman beranda khusus Editor, menerapkan EDITOR_NAME.homepageTrigger fungsi untuk membangun antarmuka. Jika tidak, gunakan common.homepageTrigger untuk membangun beranda umum untuk aplikasi {i>host<i} Anda.
  4. Jika Anda menggunakan REST API, terapkan alur otorisasi cakupan drive.file dan EDITOR_NAME.onFileScopeGrantedTrigger {i>trigger<i} untuk menampilkan antarmuka khusus untuk file yang terbuka. Untuk selengkapnya lihat informasi antarmuka REST API.
  5. Jika Anda mengonfigurasi pratinjau link dari layanan pihak ketiga, terapkan alur otorisasi cakupan https://www.googleapis.com/auth/workspace.linkpreview dan linkPreviewTriggers fungsi tersebut. Untuk informasi selengkapnya, lihat Antarmuka pratinjau link.
  6. Implementasikan fungsi callback terkait yang diperlukan untuk merespons permintaan pengguna Interaksi UI, seperti klik tombol.

Halaman beranda editor

Anda harus menyediakan fungsi pemicu halaman beranda dalam project skrip add-on Anda yang membangun dan menampilkan satu Card atau array objek Card yang membentuk halaman beranda add-on.

objek peristiwa diteruskan ke fungsi pemicu halaman beranda sebagai parameter yang berisi informasi seperti platform klien. Anda dapat menggunakan data objek peristiwa untuk menyesuaikan konstruksi halaman beranda.

Anda dapat menyajikan halaman beranda umum atau halaman beranda yang khusus untuk Editor pengguna membuka add-on Anda.

Menampilkan halaman beranda umum

Untuk menampilkan halaman beranda umum add-on di Editor, sertakan halaman beranda Kolom editor, seperti addOns.docs, addOns.sheets, atau addOns.slides, dalam manifes add-on.

Contoh berikut menunjukkan bagian addons pada Add-on Google Workspace manifes. Add-on ini memperluas Dokumen, Spreadsheet, dan Slide, serta menunjukkan di setiap aplikasi host.

 "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": {}
  }
}

Menampilkan halaman beranda khusus Editor

Untuk menyajikan halaman beranda khusus bagi Editor, tambahkan EDITOR_NAME.homepageTrigger ke add-on manifes.

Contoh berikut menunjukkan bagian addons dari manifes Add-on Google Workspace. Add-on diaktifkan untuk Dokumen, Spreadsheet, dan Slide. Ini menampilkan penyampaian halaman beranda di Dokumen dan Slide, serta halaman beranda unik di Spreadsheet. Callback fungsi onSheetsHomepage membuat kartu halaman beranda khusus Spreadsheet.

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

Antarmuka REST API

Jika add-on Anda menggunakan REST API, seperti Google Sheets API, Anda dapat menggunakan fungsi onFileScopeGrantedTrigger untuk menampilkan antarmuka baru khusus untuk file yang dibuka di aplikasi {i>host<i} Editor.

Anda harus menyertakan alur otorisasi cakupan drive.file untuk menggunakan fungsi onFileScopeGrantedTrigger. Untuk mempelajari cara meminta drive.file cakupan, lihat Meminta akses file untuk dokumen saat ini.

Saat pengguna memberikan cakupan drive.file, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction kebakaran. Saat diaktifkan, pemicu akan menjalankan fungsi pemicu kontekstual yang ditentukan oleh kolom EDITOR_NAME.onFileScopeGrantedTrigger.runFunction di kolom manifes add-on.

Untuk membuat antarmuka REST API bagi salah satu Editor, ikuti langkah-langkah di bawah ini. Ganti EDITOR_NAME dengan aplikasi host Editor yang Anda pilih gunakan, misalnya, sheets.onFileScopeGrantedTrigger.

  1. Sertakan EDITOR_NAME.onFileScopeGrantedTrigger di bagian Editor yang sesuai dalam manifes Anda. Misalnya, jika Anda ingin membuat antarmuka ini di Google Sheets, tambahkan pemicu ke bagian "sheets".
  2. Mengimplementasikan fungsi yang dinamai dalam EDITOR_NAME.onFileScopeGrantedTrigger bagian. Fungsi ini menerima objek peristiwa sebagai argumen dan harus menampilkan satu Card atau array objek Card.
  3. Seperti kartu lainnya, Anda harus mengimplementasikan fungsi callback yang digunakan untuk menyediakan interaktivitas widget untuk antarmuka. Misalnya, jika Anda menyertakan tombol di antarmuka, antarmuka harus memiliki Action yang dilampirkan dan fungsi callback yang diimplementasikan yang berjalan saat tombol diklik.

Contoh berikut menunjukkan bagian addons dari manifes Add-on Google Workspace. Add-on menggunakan REST API, sehingga onFileScopeGrantedTrigger disertakan untuk dan rencana project dengan Google Spreadsheet. Saat pengguna memberikan cakupan drive.file, fungsi callback onFileScopeGrantedSheets membangun antarmuka khusus file.

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

Untuk mengaktifkan pratinjau link untuk layanan pihak ketiga, Anda harus mengonfigurasi link menampilkan pratinjau dalam manifes add-on dan membuat fungsi yang menampilkan pratinjau . Untuk layanan yang memerlukan otorisasi pengguna, fungsi Anda juga harus memanggil dalam alur otorisasi.

Untuk langkah-langkah mengaktifkan pratinjau link, lihat Melihat pratinjau link dengan smart chip.

Objek peristiwa

Objek peristiwa dibuat dan diteruskan untuk memicu fungsi, seperti EDITOR_NAME.homepageTrigger atau EDITOR_NAME.onFileScopeGrantedTrigger. Fungsi pemicu menggunakan informasi dalam peristiwa untuk menentukan cara membuat kartu tambahan atau mengontrol perilaku add-on.

Struktur lengkap objek peristiwa dijelaskan dalam Objek peristiwa.

Jika Editor menjadi aplikasi host yang bertindak pada add-on, objek peristiwa akan menyertakan Dokumen, Spreadsheet, atau Slide kolom objek peristiwa yang membawa informasi klien.

Jika add-on tidak memiliki otorisasi cakupan drive.file untuk pengguna saat ini atau dokumen, objek peristiwa hanya berisi docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission, atau Kolom slides.addonHasFileScopePermission. Jika add-on memiliki otorisasi, objek peristiwa berisi semua kolom objek peristiwa Editor.

Contoh berikut menunjukkan objek peristiwa Editor yang diteruskan ke Fungsi sheets.onFileScopeGrantedTrigger. Di sini, add-on ini memiliki Otorisasi cakupan drive.file untuk dokumen saat ini:

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