Tindakan add-on memberikan perilaku interaktif untuk widget. Dengan membuat tindakan, Anda menentukan apa yang terjadi saat pengguna memilih atau mengupdate widget.
Pada umumnya, Anda dapat menentukan tindakan add-on menggunakan
objek Action
yang disediakan oleh layanan Kartu Apps Script.
Setiap Action dikaitkan dengan fungsi callback saat Anda membuatnya. Anda menerapkan fungsi callback untuk mengambil langkah-langkah yang diinginkan saat pengguna berinteraksi dengan widget. Anda juga harus
menautkan Action ke widget
menggunakan fungsi pengendali widget yang sesuai yang
menentukan jenis interaksi yang memicu
callback Action.
Konfigurasikan widget dengan Action
menggunakan proses umum berikut:
- Buat objek
Action, dengan menentukan fungsi callback yang harus dijalankan bersama dengan parameter yang diperlukan. - Panggil fungsi pengendali widget
yang sesuai pada widget menggunakan objek
Action. - Implementasikan fungsi callback untuk menerapkan perilaku yang diperlukan.
Fungsi pengendali widget
Untuk menautkan widget ke Action tertentu atau perilaku lainnya, gunakan fungsi pengendali widget. Fungsi pengendali menentukan jenis interaksi (misalnya, mengklik widget atau mengedit kolom teks) akan memicu perilaku tindakan. Fungsi pengendali juga menentukan langkah-langkah yang diambil UI, jika ada, setelah tindakan selesai.
Tabel berikut mencantumkan berbagai jenis pengendali untuk widget dan widget yang digunakan dengannya:
| Fungsi pengendali | Memicu tindakan | Widget yang sesuai | Deskripsi |
|---|---|---|---|
setOnChangeAction() |
Nilai widget berubah |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Menetapkan Action
yang menjalankan fungsi Apps Script saat widget kehilangan fokus, seperti
saat pengguna memasukkan teks dalam input dan menekan Enter. Pengendali
secara otomatis meneruskan
objek peristiwa ke fungsi yang dipanggilnya.
Anda dapat memasukkan informasi parameter tambahan dalam objek peristiwa ini jika diinginkan. |
setOnClickAction() |
Pengguna mengklik widget tersebut. |
CardActionImageImageButtonDecoratedTextTextButton
|
Menetapkan Action
yang menjalankan fungsi Apps Script saat pengguna mengklik widget. Pengendali
secara otomatis meneruskan
objek peristiwa ke fungsi yang dipanggilnya.
Anda dapat memasukkan informasi parameter opsional dalam objek peristiwa ini. |
setComposeAction() |
Pengguna mengklik widget tersebut. |
CardActionImageImageButtonDecoratedTextTextButton
|
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 untuk pesan yang terbuka di Gmail. Saat pengendali memanggil fungsi callback pembuatan draf, pengendali akan meneruskan objek peristiwa ke fungsi callback.
Lihat
Menulis draf pesan
untuk detail selengkapnya. |
setOnClickOpenLinkAction() |
Pengguna mengklik widget tersebut. |
CardActionImageImageButtonDecoratedTextTextButton
|
Menetapkan Action
untuk membuka URL saat pengguna mengklik widget. Gunakan pengendali ini jika Anda harus membuat URL atau tindakan lainnya harus dilakukan sebelum link dibuka; jika tidak, biasanya setOpenLink() akan lebih mudah digunakan.
Anda hanya dapat membuka URL di jendela baru. Jika ditutup, Anda dapat membuat
UI memuat ulang add-on. |
setOpenLink() |
Pengguna mengklik widget tersebut. |
CardActionImageImageButtonDecoratedTextTextButton
|
Langsung membuka URL saat pengguna mengklik widget. Gunakan pengendali ini jika Anda mengetahui URL-nya 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 input |
TextInput
|
Menetapkan Action
yang menjalankan fungsi Apps Script saat pengguna memasukkan teks ke dalam
widget input teks. Pengendali secara otomatis meneruskan objek peristiwa ke fungsi yang dipanggilnya.
Lihat Saran pelengkapan otomatis untuk input teks guna mengetahui detail selengkapnya. |
Fungsi callback
Fungsi callback dijalankan saat Action
terpicu. Karena fungsi callback adalah fungsi Apps Script, Anda dapat meminta fungsi tersebut
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 memberikan saran pelengkapan otomatis. Ketika fungsi callback harus menampilkan objek respons tertentu, gunakan class builder dalam layanan Card untuk membuat objek tersebut.
Tabel berikut menunjukkan kapan fungsi callback Anda harus menampilkan objek respons spesifik untuk tindakan tertentu. Semua tindakan ini tidak bergantung pada aplikasi host tertentu yang diperluas add-on:
| Tindakan dicoba | Fungsi callback akan ditampilkan |
|---|---|
| Menavigasi antarkartu | ActionResponse |
Menampilkan Notification |
ActionResponse |
Membuka link menggunakan setOnClickOpenLinkAction() |
ActionResponse |
| Menampilkan saran pelengkapan otomatis | SuggestionResponse |
| Menggunakan tindakan universal | UniversalActionResponse |
| Tindakan lainnya | Nothing |
Selain tindakan ini, setiap aplikasi host memiliki serangkaian tindakannya sendiri yang hanya dapat dilakukan di host tersebut. Untuk mengetahui detailnya, lihat panduan berikut:
Objek peristiwa tindakan
Saat add-on 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 pada kartu yang ditampilkan.
Objek peristiwa tindakan memiliki struktur JSON spesifik yang mengatur informasi di dalamnya. 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 mengetahui penjelasan lengkap tentang struktur objek peristiwa.