Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat antarmuka Google Editor

Dengan Add-on Google Workspace, Anda dapat menyediakan antarmuka yang disesuaikan dalam Editor, termasuk Google Dokumen, Spreadsheet, dan Slide. Hal ini memungkinkan Anda 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 menyediakan antarmuka berikut:

Antarmuka halaman beranda: Jika manifes add-on menyertakan pemicu EDITOR_NAME.homepageTrigger untuk Editor, pengguna membuka add-on, add-on akan mem-build dan menampilkan kartu halaman beranda secara 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 dijalankan dan menampilkan antarmuka khusus untuk file tersebut.
Antarmuka pratinjau link: Jika add-on terintegrasi dengan layanan pihak ketiga, Anda dapat membuat kartu yang melihat pratinjau konten dari URL layanan.

Membuat antarmuka untuk Add-on Editor

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

Tambahkan kolom addOns.common, addOns.docs, addOns.sheets, dan addOns.slides yang sesuai ke manifes project skrip add-on.
Tambahkan cakupan Editor yang diperlukan ke manifes project skrip Anda.
Jika Anda menyediakan Halaman beranda khusus Editor, implementasikan fungsi EDITOR_NAME.homepageTrigger untuk mem-build antarmuka. Jika belum, gunakan antarmuka common.homepageTrigger untuk membuat halaman beranda umum bagi aplikasi host Anda.
Jika Anda menggunakan REST API, implementasikan alur otorisasi cakupan drive.file dan fungsi pemicu EDITOR_NAME.onFileScopeGrantedTrigger untuk menampilkan antarmuka khusus file yang terbuka. Untuk informasi selengkapnya, lihat antarmuka REST API.
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 Menautkan antarmuka pratinjau.
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 diberi objek peristiwa sebagai parameter yang berisi informasi seperti platform klien. Anda dapat menggunakan data objek peristiwa untuk menyesuaikan konstruksi 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 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 bagi Editor, tambahkan EDITOR_NAME.homepageTrigger ke manifes add-on.

Contoh berikut menunjukkan bagian addons dari manifes Add-on Google Workspace. Add-on diaktifkan untuk Dokumen, Spreadsheet, dan Slide. Ini menampilkan beranda umum di Dokumen dan Slide, dan 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 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 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.

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".
Implementasikan fungsi yang dinamai di bagian EDITOR_NAME.onFileScopeGrantedTrigger. Fungsi ini menerima objek peristiwa sebagai argumen dan harus menampilkan satu objek Card atau array objek Card.
Seperti kartu lainnya, Anda harus menerapkan fungsi callback yang digunakan untuk menyediakan interaktivitas widget untuk antarmuka. Misalnya, jika Anda menyertakan tombol dalam antarmuka, tombol tersebut harus memiliki Action terlampir dan fungsi callback yang diimplementasikan yang akan 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"
     }
   }

Antarmuka pratinjau link untuk layanan pihak ketiga

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 chip pintar.

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 yang bertindak dari add-on, objek peristiwa 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"
          },
          ...
        }