Membuat antarmuka Google Editor

Dengan Google Workspace Add-on, Anda dapat memberikan antarmuka yang disesuaikan 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 Google Workspace Add-on di Editor jika ikonnya muncul di Google Workspace panel samping akses cepat di sebelah kanan antarmuka pengguna Dokumen, Spreadsheet, dan Slide.

Google Workspace Add-on dapat menampilkan antarmuka halaman beranda, antarmuka khusus untuk penggunaan REST API setelah cakupan file yang tepat diberikan, atau keduanya.

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 yang dibuka pengguna, kartu halaman beranda umum akan ditampilkan.

Untuk mengetahui informasi selengkapnya, lihat Halaman beranda editor.

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 mengeksekusi dan menampilkan antarmuka khusus untuk file tersebut.

Untuk mengetahui informasinya, lihat antarmuka Display REST API.

Membuat antarmuka untuk Add-on Editor

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

  1. Tambahkan kolom addOns.common, addOns.docs, addOns.sheets, dan addOns.slides yang sesuai ke project skrip add-on manifes.
  2. Tambahkan cakupan Editor apa pun yang diperlukan ke manifes project skrip Anda.
  3. Jika Anda menyediakan halaman beranda khusus Editor, terapkan fungsi EDITOR_NAME.homepageTrigger untuk membuat antarmuka. Jika tidak, gunakan antarmuka common.homepageTrigger untuk mem-build halaman beranda umum untuk 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 Display.
  5. Implementasikan 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 mem-build dan menampilkan satu Card atau array objek Card yang membentuk halaman beranda add-on.

Fungsi pemicu halaman beranda meneruskan 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 khusus untuk Editor yang digunakan pengguna untuk membuka add-on.

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 Google Workspace Add-on. Add-on diaktifkan untuk 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 Google Workspace Add-on. Add-on diaktifkan untuk Dokumen, Spreadsheet, dan Slide. Halaman beranda 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"
     },
  }
}

Menampilkan 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 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 menjalankan fungsi pemicu kontekstual yang ditentukan oleh kolom EDITOR_NAME.onFileScopeGrantedTrigger.runFunction dalam manifes add-on.

Untuk membuat antarmuka REST API untuk 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 disebutkan 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 interaktivitas widget. Misalnya, jika Anda menyertakan tombol di antarmuka, tombol tersebut harus memiliki Action terlampir dan fungsi callback yang diimplementasikan yang berjalan saat tombol diklik.

Contoh berikut menunjukkan bagian addons dari manifes Google Workspace Add-on. Add-on menggunakan REST API, sehingga onFileScopeGrantedTrigger disertakan untuk Spreadsheet. Saat pengguna memberikan cakupan drive.file, fungsi callback onFileScopeGrantedSheets 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"
     }
   }

Objek peristiwa

Objek peristiwa dibuat dan diteruskan untuk memicu fungsi, 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 dalam Objek peristiwa.

Jika Editor adalah aplikasi host tindakan add-on, objek peristiwa akan mencakup 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 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"
          },
          ...
        }