Tindakan add-on memberikan perilaku interaktif ke 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 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 pengendali widget yang
sesuai yang menentukan jenis interaksi yang memicu
callback Action.
Konfigurasi widget dengan Action
menggunakan proses umum ini:
- Buat objek
Action, dengan menentukan fungsi callback yang harus dieksekusi bersama dengan parameter yang diperlukan. - Panggil fungsi pengendali widget yang sesuai
pada widget menggunakan objek
Action. - Terapkan fungsi callback untuk menerapkan perilaku yang diperlukan.
Fungsi handler widget
Untuk menautkan widget ke Action tertentu
atau perilaku lainnya, Anda menggunakan fungsi
handler widget. Fungsi pengendali menentukan jenis interaksi
(misalnya, mengklik widget atau mengedit kolom teks) yang memicu
perilaku tindakan. Fungsi handler 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 |
DatePickerDateTimePickerSelectionInputSwitchTextInput
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 |
CardActionImageImageButtonDecoratedTextTextButton
|
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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Khusus Gmail. Menetapkan
Action
yang membuat draf email, lalu menampilkan draf tersebut kepada pengguna di
jendela tulis UI Gmail. Anda dapat membuat draf sebagai pesan baru atau
balasan ke pesan yang terbuka di Gmail. Saat memanggil fungsi callback pembuatan draf, pengendali akan meneruskan objek peristiwa ke fungsi callback.
Lihat
Menyusun pesan draf
untuk mengetahui detail selengkapnya. |
setOnClickOpenLinkAction() |
Pengguna mengklik widget |
CardActionImageImageButtonDecoratedTextTextButton
|
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 |
CardActionImageImageButtonDecoratedTextTextButton
|
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 add-on:
| Tindakan dicoba | Fungsi callback harus menampilkan |
|---|---|
| Menavigasi antar-kartu | 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:
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 di 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.