Membuat antarmuka Google Editor

Dengan add-on Google Workspace, Anda dapat menyediakan antarmuka yang disesuaikan dalam Editor, termasuk Google Dokumen, Spreadsheet, dan Slide. Dengan begitu, Anda dapat memberikan informasi yang relevan kepada pengguna, 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 panel samping akses cepat Google Workspace di sisi kanan antarmuka pengguna Dokumen, Spreadsheet, dan Slide.

Add-on Google Workspace dapat menampilkan antarmuka berikut:

  • Antarmuka halaman beranda: Jika manifes add-on menyertakan pemicu EDITOR_NAME.homepageTrigger untuk Editor tempat pengguna membuka add-on, add-on akan mem-build dan menampilkan kartu halaman beranda khusus untuk Editor tersebut. Jika manifes add-on tidak menyertakan EDITOR_NAME.homepageTrigger untuk Editor tempat pengguna membukanya, 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 akan dieksekusi dan menampilkan antarmuka khusus untuk file.

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

Membuat antarmuka untuk add-on Editor

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

  1. Tambahkan kolom addOns.common, addOns.docs, addOns.sheets, dan addOns.slides yang sesuai ke manifes project skrip add-on.
  2. Tambahkan Cakupan editor yang diperlukan ke manifes project skrip Anda.
  3. Jika Anda menyediakan halaman beranda khusus Editor, implementasikan fungsi EDITOR_NAME.homepageTrigger untuk mem-build antarmuka. Jika tidak, gunakan antarmuka common.homepageTrigger untuk membuat halaman beranda umum bagi aplikasi host Anda.
  4. Jika Anda menggunakan REST API, terapkan alur otorisasi cakupan drive.file dan fungsi pemicu EDITOR_NAME.onFileScopeGrantedTrigger untuk menampilkan antarmuka khusus untuk file yang terbuka. Untuk informasi selengkapnya, lihat 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 fungsi linkPreviewTriggers. Untuk mengetahui informasi selengkapnya, lihat Antarmuka pratinjau link.
  6. Terapkan fungsi callback terkait yang diperlukan untuk merespons interaksi UI pengguna, seperti klik tombol.

Halaman beranda editor

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

Fungsi pemicu halaman beranda menerima objek peristiwa sebagai parameter yang berisi informasi seperti platform klien. Anda dapat menggunakan data objek peristiwa untuk menyesuaikan pembuatan halaman beranda.

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

Menampilkan halaman beranda umum

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

Contoh berikut menunjukkan bagian addons dari manifes add-on Google Workspace. Add-on ini memperluas Dokumen, Spreadsheet, dan Slide, serta menampilkan halaman beranda umum 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 menampilkan halaman beranda khusus Editor, tambahkan EDITOR_NAME.homepageTrigger ke manifes add-on.

Contoh berikut menunjukkan bagian addons dari manifes add-on Google Workspace. Add-on ini diaktifkan untuk Dokumen, Spreadsheet, dan Slide. Halaman ini menampilkan halaman beranda umum di Dokumen dan Slide, serta halaman beranda unik di Spreadsheet. Fungsi callback 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 terbuka di aplikasi host Editor.

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

Saat pengguna memberikan cakupan drive.file, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction akan diaktifkan. Saat diaktifkan, pemicu akan mengeksekusi fungsi pemicu kontekstual yang ditentukan oleh kolom EDITOR_NAME.onFileScopeGrantedTrigger.runFunction dalam 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 untuk digunakan, 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 Spreadsheet, tambahkan pemicu ke bagian "sheets".
  2. Implementasikan fungsi yang diberi nama di bagian EDITOR_NAME.onFileScopeGrantedTrigger. Fungsi ini menerima objek peristiwa sebagai argumen dan harus menampilkan satu objek Card atau array objek Card.
  3. Seperti kartu lainnya, Anda harus mengimplementasikan fungsi callback yang digunakan untuk menyediakan interaksi widget untuk antarmuka. Misalnya, jika Anda menyertakan tombol di antarmuka, tombol tersebut harus memiliki Action yang terpasang dan fungsi callback yang diterapkan yang berjalan saat tombol diklik.

Contoh berikut menunjukkan bagian addons dari manifes add-on Google Workspace. Add-on ini menggunakan REST API, sehingga onFileScopeGrantedTrigger disertakan untuk Google Spreadsheet. Saat pengguna memberikan cakupan drive.file, fungsi callback onFileScopeGrantedSheets akan membuat 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 pratinjau link dalam manifes add-on dan membuat fungsi yang menampilkan kartu pratinjau. Untuk layanan yang memerlukan otorisasi pengguna, fungsi Anda juga harus memanggil alur otorisasi.

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

Objek peristiwa

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

Struktur lengkap objek peristiwa dijelaskan di Objek peristiwa.

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

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

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

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