Membangun antarmuka Google Drive

Add-on Google Workspace dapat menyediakan antarmuka yang disesuaikan saat pengguna membuka Drive. Dengan begitu, Anda dapat memberikan informasi tambahan yang relevan kepada pengguna, mengotomatiskan tugas, dan menghubungkan sistem pihak ketiga ke Drive.

Mengakses UI add-on Google Workspace

Anda dapat membuka add-on di Drive jika ikonnya muncul di kolom ikon di sisi kanan antarmuka pengguna Drive. Add-on dapat menentukan antarmuka halaman beranda, antarmuka pemilihan item, atau keduanya:

  • Jika pengguna mengklik ikon add-on saat berada di Drive, add-on akan menjalankan fungsi drive.homepageTrigger yang sesuai (jika ada). Fungsi ini membuat dan menampilkan kartu beranda ke Drive untuk ditampilkan. Jika tidak ada fungsi drive.homepageTrigger yang ditentukan, kartu halaman beranda generik akan ditampilkan.
  • Jika pengguna memilih satu atau beberapa item di Drive, lalu mengklik ikon add-on, atau memilih item saat add-on terbuka, add-on akan mengeksekusi fungsi kontekstual drive.onItemsSelectedTrigger yang sesuai (jika ada). Fungsi ini membangun antarmuka "item dipilih" kontekstual add-on di Drive dan menampilkannya kembali ke Drive.

Membangun antarmuka Drive add-on

Buat antarmuka yang memperluas Drive dengan mengikuti langkah-langkah umum berikut:

  1. Tentukan apakah Anda ingin add-on memiliki halaman beranda khusus Drive. Tentukan juga apakah Anda ingin menyediakan antarmuka kontekstual saat pengguna memilih item Drive.
  2. Tambahkan kolom addOns.common dan addOns.drive yang sesuai ke manifes project skrip add-on, termasuk cakupan Drive yang diperlukan.
  3. Jika Anda menyediakan halaman beranda khusus Drive, terapkan fungsi drive.homepageTrigger untuk membuat antarmuka ini. Anda juga dapat memilih untuk menggunakan antarmuka common.homepageTrigger untuk beberapa host Google Workspace.
  4. Jika Anda menyediakan antarmuka pemilihan item kontekstual Drive, Anda harus menerapkan fungsi pemicu kontekstual drive.onItemsSelectedTrigger untuk membuat antarmuka ini. Lihat Antarmuka kontekstual Drive untuk item yang dipilih untuk mengetahui detailnya.
  5. Terapkan fungsi callback terkait yang diperlukan untuk merespons interaksi UI pengguna, seperti klik tombol.

Halaman beranda Drive

Drive mendukung tampilan halaman beranda add-on. Untuk menampilkan halaman beranda umum add-on Anda di Drive, pastikan ada kolom addOns.drive di manifes add-on.

Atau, tambahkan drive.homepageTrigger ke manifes add-on untuk menyediakan halaman beranda khusus Drive.

Dalam kedua kasus tersebut, berikan nama fungsi pemicu halaman beranda di proyek skrip add-on Anda. Fungsi ini otomatis dipanggil untuk membuat halaman beranda Drive saat diperlukan. Terapkan fungsi ini untuk membuat dan menampilkan satu Card atau array objek Card yang membentuk halaman beranda. Fungsi pemicu halaman beranda meneruskan objek peristiwa sebagai parameter yang berisi beberapa informasi umum seperti platform klien. Gunakan data objek acara untuk membuat halaman beranda.

Antarmuka kontekstual Drive untuk item yang dipilih

Drive mengandalkan pemicu kontekstual untuk menentukan antarmuka (jika ada) yang akan ditampilkan saat pengguna memilih satu atau beberapa item Drive. Saat pemicu diaktifkan, pemicu akan menjalankan fungsi pemicu kontekstual yang ditentukan oleh kolom drive.onItemsSelectedTrigger.runFunction dalam manifes add-on.

Untuk membuat antarmuka pemilihan item kontekstual untuk Drive, Anda harus melakukan hal berikut:

  1. Pastikan manifes add-on menyertakan https://www.googleapis.com/auth/drive.addons.metadata.readonly scope.

  2. Pastikan manifes menyertakan bagian drive.onItemsSelectedTrigger.

  3. Terapkan fungsi yang dinamai di kolom drive.onItemsSelectedTrigger. Fungsi ini menerima objek peristiwa sebagai argumen dan harus menampilkan satu objek Card atau array objek Card.

  4. Seperti kartu lainnya, terapkan 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 diterapkan yang berjalan saat tombol diklik.

Objek peristiwa

Objek peristiwa dibuat dan diteruskan ke fungsi pemicu drive.homepageTrigger atau drive.onItemsSelectedTrigger saat fungsi tersebut dipanggil. Fungsi pemicu menggunakan informasi dalam objek peristiwa ini untuk menentukan cara membuat kartu add-on atau mengontrol perilaku add-on.

Struktur lengkap objek peristiwa dijelaskan dalam Objek peristiwa. Jika Drive adalah aplikasi host add-on yang bertindak, objek peristiwa kontekstual menyertakan kolom objek peristiwa Drive yang membawa informasi klien khusus Drive.

Objek peristiwa Drive kontekstual untuk pemicu pemilihan item mencakup informasi tentang item yang telah dipilih pengguna saat pemicu diaktifkan. Saat pengguna memilih lebih dari satu item di Drive, salah satu item dianggap sebagai item yang paling diminati; item ini disebut sebagai item kursor aktif.

Jika perilaku add-on dimaksudkan untuk diterapkan ke beberapa item yang dipilih, gunakan informasi yang diberikan dalam array drive.selectedItems dalam objek peristiwa untuk mengidentifikasi semuanya.

Jika perilaku add-on hanya boleh diterapkan ke satu item yang dipilih, gunakan informasi yang diberikan di kolom drive.activeCursorItem objek peristiwa untuk mengidentifikasi item dari seluruh pilihan. Jangan mencoba menyimpulkan item mana yang akan digunakan dari array drive.selectedItems.

Contoh berikut menunjukkan objek peristiwa Drive yang diteruskan ke fungsi drive.onItemsSelectedTrigger:

{
  "commonEventObject": { ... },
  "drive": {
    "activeCursorItem":{
      "addonHasFileScopePermission": true,
      "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
      "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
      "mimeType":"application/pdf",
      "title":"How to get started with Drive"
    },
    "selectedItems": [
      {
        "addonHasFileScopePermission": true,
        "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
        "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
        "mimeType":"application/pdf",
        "title":"How to get started with Drive"
      },
      ...
    ]
  },
  ...
}