Tindakan add-on menyediakan perilaku interaktif untuk widget. Dengan membuat tindakan, Anda menentukan apa yang terjadi ketika pengguna memilih atau mengupdate {i>widget<i}.
Pada umumnya, Anda dapat menentukan tindakan add-on menggunakan
Action
objek yang disediakan oleh layanan Kartu Apps Script.
Setiap Action dikaitkan dengan
fungsi callback saat Anda membuatnya. Anda menerapkan fungsi callback
untuk mengambil langkah yang diinginkan saat pengguna berinteraksi dengan widget. Anda juga harus
tautkan Action ke widget
menggunakan fungsi pengendali widget yang sesuai dan
mendefinisikan jenis interaksi apa yang akan memicu
Callback Action.
Mengonfigurasi widget dengan Action
menggunakan proses umum ini:
- Buat objek
Action, menentukan fungsi callback yang harus dieksekusi bersama dengan parameter apa pun yang diperlukan. - Memanggil fungsi pengendali widget yang sesuai
di widget menggunakan
Action. - Implementasikan fungsi callback untuk menerapkan perilaku yang diperlukan.
Fungsi pengendali widget
Untuk menautkan widget ke Action tertentu
atau perilaku lainnya, Anda menggunakan widget
pengendali. 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 ini mencantumkan berbagai jenis pengendali untuk widget dan widget tersebut digunakan dengan:
| 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
seperti saat pengguna memasukkan teks dalam input dan menekan Enter. Tujuan
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. Tujuan
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. Menyetel
Action
yang membuat draf email, lalu menyajikannya kepada pengguna dalam
Jendela tulis UI Gmail. Anda dapat membuat draf sebagai pesan baru atau
membalas pesan yang terbuka di Gmail. Saat handler memanggil
fungsi callback pembangunan draf, fungsi ini akan meneruskan
objek peristiwa ke fungsi callback.
Lihat
Menulis draf pesan
untuk mengetahui detail selengkapnya. |
setOnClickOpenLinkAction() |
Pengguna mengklik widget tersebut. |
CardActionImageImageButtonDecoratedTextTextButton
|
Menetapkan Action
untuk membuka URL saat pengguna mengklik widget. Gunakan pengendali ini saat Anda
harus membuat URL atau tindakan lain harus dilakukan sebelum tautan
terbuka; jika tidak, biasanya akan lebih mudah untuk menggunakan setOpenLink().
Anda hanya dapat membuka URL di jendela baru. Jika ditutup, Anda dapat menyebabkan
UI untuk memuat ulang add-on. |
setOpenLink() |
Pengguna mengklik widget tersebut. |
CardActionImageImageButtonDecoratedTextTextButton
|
Langsung membuka URL saat pengguna mengklik widget. Gunakan ini
jika Anda mengetahui URL dan hanya perlu membukanya; jika tidak, gunakan
setOnClickOpenLinkAction().
Anda dapat membuka URL di jendela baru atau di overlay. Saat tutup, 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
widget input teks. Pengendali secara otomatis meneruskan sebuah
objek peristiwa ke fungsi yang dipanggilnya.
Lihat
Saran pelengkapan otomatis
untuk input teks guna mengetahui detail selengkapnya. |
Fungsi callback
Fungsi callback dijalankan saat Action
pemicu. Karena fungsi callback adalah fungsi Apps Script, Anda dapat memilikinya
melakukan hampir semua hal
yang dapat dilakukan oleh fungsi {i>script<i} lainnya.
Fungsi callback terkadang menampilkan objek respons tertentu. Ini menunjukkan operasi tambahan yang perlu dilakukan setelah callback selesai dieksekusi, seperti menampilkan kartu baru atau menampilkan saran pelengkapan otomatis. Saat fungsi callback Anda harus menampilkan Anda dapat menggunakan class builder di Layanan kartu untuk membangun objek tersebut.
Tabel berikut menunjukkan kapan fungsi callback Anda harus menampilkan spesifik untuk tindakan tertentu. Semua tindakan ini terlepas dari 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 {i>host<i} memiliki serangkaian tindakan yang hanya dapat dilakukan di {i>host<i} tersebut. Untuk mengetahui detailnya, lihat referensi berikut panduan:
Objek peristiwa tindakan
Saat add-on memicu Action,
UI secara otomatis membuat objek peristiwa JSON dan meneruskannya sebagai
argumen ke callback Action
fungsi tersebut. Objek peristiwa ini berisi informasi tentang aktivitas pengguna saat ini
konteks sisi klien, seperti nilai saat ini dari semua
widget pada kartu yang ditampilkan.
Objek peristiwa tindakan memiliki struktur JSON spesifik yang mengatur informasi yang dikandungnya. Struktur yang sama digunakan ketika sebuah pemicu halaman beranda diaktifkan untuk membuat beranda, atau ketika pemicu kontekstual diaktifkan untuk memperbarui tampilan add-on.
Lihat Objek peristiwa untuk mengetahui tentang struktur objek peristiwa.