Tindakan add-on

Tindakan add-on memberikan perilaku interaktif pada widget. Dengan membuat tindakan, Anda menentukan apa yang terjadi saat pengguna memilih atau memperbarui widget.

Dalam sebagian besar kasus, Anda dapat menentukan tindakan add-on menggunakan objek Action yang disediakan oleh layanan Kartu Google Apps Script. Setiap Action dikaitkan dengan fungsi callback saat Anda membuatnya. Anda menerapkan fungsi callback untuk melakukan langkah-langkah yang dipilih saat pengguna berinteraksi dengan widget. Anda juga harus menautkan Action ke widget menggunakan fungsi handler widget yang sesuai yang menentukan jenis interaksi yang memicu callback Action.

Konfigurasi widget dengan Action menggunakan proses ini:

  1. Buat objek Action, dengan menentukan fungsi callback yang harus dijalankan beserta parameter yang diperlukan.
  2. Panggil fungsi pengendali widget yang sesuai pada widget menggunakan objek Action.
  3. Terapkan fungsi callback untuk menerapkan perilaku yang diperlukan.

Jangan salah mengira objek Action dengan objek CardAction. Objek CardAction adalah item menu header kartu, sedangkan objek Action menentukan respons terhadap interaksi pengguna dengan UI.

Fungsi handler widget

Untuk menautkan widget ke Action atau perilaku lainnya, gunakan fungsi pengendali widget. Fungsi pengendali menentukan jenis interaksi (misalnya, mengklik widget atau mengedit kolom teks) yang memicu perilaku tindakan. Fungsi pengendali juga menentukan langkah-langkah yang dilakukan UI, jika ada, setelah tindakan selesai.

Tabel berikut mencantumkan berbagai jenis handler untuk widget dan widget yang digunakan dengannya:

Fungsi handler Memicu tindakan Widget yang berlaku Deskripsi
setOnChangeAction Nilai widget berubah DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		Menetapkan Action yang menjalankan fungsi Apps Script saat widget kehilangan fokus, seperti saat pengguna memasukkan teks dalam input dan menekan Enter. Handler secara otomatis meneruskan objek peristiwa ke fungsi yang dipanggilnya. Anda dapat menyisipkan informasi parameter tambahan dalam objek peristiwa ini jika dipilih.
setOnClickAction Pengguna mengklik widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Menetapkan Action yang menjalankan fungsi Apps Script saat pengguna mengklik widget. Handler secara otomatis meneruskan objek peristiwa ke fungsi yang dipanggilnya. Anda dapat menyisipkan informasi parameter opsional dalam objek peristiwa ini.
setComposeAction Pengguna mengklik widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Khusus Gmail. Menetapkan Action yang membuat draf email, lalu menampilkan draf tersebut kepada pengguna di jendela penulisan UI Gmail. Anda dapat membuat draf sebagai pesan baru atau balasan ke pesan yang terbuka di Gmail. Saat handler memanggil fungsi callback pembuatan draf, handler akan meneruskan objek peristiwa ke fungsi callback. Lihat Menyusun pesan draf untuk mengetahui detail selengkapnya.
setOnClickOpenLinkAction Pengguna mengklik widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Menetapkan Action untuk membuka URL saat pengguna mengklik widget. Gunakan handler ini saat Anda harus membuat URL atau tindakan lain harus dilakukan sebelum link dibuka; jika tidak, biasanya lebih mudah menggunakan setOpenLink. Anda hanya dapat membuka URL di jendela baru. Saat ditutup, Anda dapat menyebabkan UI memuat ulang add-on.
setOpenLink Pengguna mengklik widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Membuka URL secara langsung saat pengguna mengklik widget. Gunakan handler ini saat Anda mengetahui URL dan hanya perlu membukanya; jika tidak, gunakan setOnClickOpenLinkAction. Anda dapat membuka URL di jendela baru atau di overlay. Jika ditutup, Anda dapat menyebabkan UI memuat ulang add-on.
setSuggestionsAction Pengguna memasukkan teks ke dalam input TextInput Menetapkan Action yang menjalankan fungsi Apps Script saat pengguna memasukkan teks ke dalam widget input teks. Handler secara otomatis meneruskan objek peristiwa ke fungsi yang dipanggilnya. Lihat Saran pelengkapan otomatis untuk input teks untuk mengetahui detail selengkapnya.

Fungsi callback

Fungsi callback dijalankan saat Action dipicu. Karena fungsi callback adalah fungsi Apps Script, Anda dapat membuatnya melakukan hampir semua hal yang dapat dilakukan oleh fungsi skrip lainnya.

Fungsi callback terkadang menampilkan objek respons tertentu. Jenis respons ini menunjukkan operasi tambahan yang perlu terjadi setelah callback selesai dieksekusi, seperti menampilkan kartu baru atau menyajikan saran pelengkapan otomatis. Jika fungsi callback Anda harus menampilkan objek respons tertentu, Anda menggunakan class builder di layanan Kartu untuk membuat objek tersebut.

Tabel berikut menunjukkan kapan fungsi callback Anda harus menampilkan objek respons tertentu untuk tindakan tertentu. Semua tindakan ini tidak bergantung pada aplikasi host tertentu yang diperluas oleh add-on:

Tindakan dicoba Fungsi callback harus menampilkan
Menavigasi ActionResponse
Menampilkan Notification ActionResponse
Membuka link menggunakan setOnClickOpenLinkAction ActionResponse
Menampilkan saran pelengkapan otomatis SuggestionResponse
Menggunakan tindakan universal UniversalActionResponse
Tindakan lainnya Nothing

Tindakan untuk aplikasi host Google Workspace

Selain tindakan ini, setiap aplikasi host memiliki serangkaian tindakan sendiri yang hanya dapat dilakukan di host tersebut. Untuk mengetahui detailnya, lihat panduan berikut:

Saat menggunakan class pembuat respons, panggil metode build untuk menghasilkan objek respons. Jika tidak dilakukan, akan muncul error.

Tindakan universal ditentukan dalam manifes project dan tidak memerlukan objek Action, tetapi fungsi callback-nya harus menampilkan UniversalActionResponse.

Objek peristiwa tindakan

Saat add-on Anda memicu Action, UI akan otomatis membuat objek peristiwa JSON dan meneruskannya sebagai argumen ke fungsi callback Action. Objek peristiwa ini berisi informasi tentang konteks sisi klien pengguna saat ini, seperti nilai saat ini dari semua widget interaktif dalam kartu yang ditampilkan.

Objek peristiwa tindakan memiliki struktur JSON tertentu yang mengatur informasi yang dikandungnya. Struktur yang sama digunakan saat pemicu halaman beranda diaktifkan untuk membuat halaman beranda, atau saat pemicu kontekstual diaktifkan untuk memperbarui tampilan add-on.

Lihat Objek peristiwa untuk penjelasan lengkap tentang struktur objek peristiwa.

Add-on Gmail menggunakan versi sederhana dari struktur objek peristiwa ini, yang kini tidak digunakan lagi. Untuk kompatibilitas mundur, semua kolom objek peristiwa add-on Gmail asli masih ada dalam struktur objek peristiwa baru (lihat struktur objek peristiwa). Namun, informasi yang sama direproduksi dalam substruktur objek commonEventObject dan peristiwa Gmail. Jika Anda mengupgrade add-on Gmail menjadi add-on Google Workspace, sesuaikan kode Anda untuk menggunakan kolom objek peristiwa yang diperbarui. Pada akhirnya, kolom objek acara Gmail asli akan dihapus.