Sebagian besar add-on, selain menampilkan data, mengharuskan pengguna untuk memasukkan informasi. Saat membuat add-on berbasis kartu, Anda dapat menggunakan widget interaktif seperti tombol, item menu toolbar, atau kotak centang untuk meminta data yang diperlukan add-on kepada pengguna atau menyediakan kontrol interaksi lainnya.
Menambahkan tindakan ke widget
Pada umumnya, Anda membuat widget menjadi interaktif dengan menautkannya ke tindakan tertentu dan menerapkan perilaku yang diperlukan dalam fungsi callback. Lihat tindakan add-on untuk mengetahui detailnya.
Pada umumnya, Anda dapat mengikuti prosedur umum ini untuk mengonfigurasi widget guna mengambil tindakan tertentu saat dipilih atau diupdate:
- Buat objek
Action
, yang menentukan fungsi callback yang harus dijalankan, beserta parameter yang diperlukan. - Tautkan widget ke
Action
dengan memanggil fungsi pengendali widget yang sesuai. - Implementasikan fungsi callback untuk menerapkan perilaku yang diperlukan.
Contoh
Contoh berikut menetapkan tombol yang menampilkan notifikasi pengguna
setelah diklik. Klik memicu fungsi callback notifyUser()
dengan argumen yang menentukan teks notifikasi. Menampilkan
ActionResponse
build akan menghasilkan notifikasi yang ditampilkan.
/**
* Build a simple card with a button that sends a notification.
* @return {Card}
*/
function buildSimpleCard() {
var buttonAction = CardService.newAction()
.setFunctionName('notifyUser')
.setParameters({'notifyText': 'Button clicked!'});
var button = CardService.newTextButton()
.setText('Notify')
.setOnClickAction(buttonAction);
// ...continue creating widgets, then create a Card object
// to add them to. Return the built Card object.
}
/**
* Callback function for a button action. Constructs a
* notification action response and returns it.
* @param {Object} e the action event object
* @return {ActionResponse}
*/
function notifyUser(e) {
var parameters = e.parameters;
var notificationText = parameters['notifyText'];
return CardService.newActionResponseBuilder()
.setNotification(CardService.newNotification())
.setText(notificationText)
.build(); // Don't forget to build the response!
}
Merancang interaksi yang efektif
Saat mendesain kartu interaktif, ingatlah hal berikut:
Widget interaktif biasanya memerlukan setidaknya satu metode pengendali untuk menentukan perilakunya.
Gunakan fungsi pengendali widget
setOpenLink()
jika Anda memiliki URL dan hanya ingin membukanya di tab. Dengan demikian, Anda tidak perlu menentukan objekAction
dan fungsi callback. Jika Anda perlu membuat URL terlebih dahulu, atau melakukan langkah tambahan lainnya sebelum membuka URL, tentukanAction
dan gunakansetOnClickOpenLinkAction()
.Saat menggunakan fungsi pengendali widget
setOpenLink()
atausetOnClickOpenLinkAction()
, Anda perlu menyediakan objekOpenLink
untuk menentukan URL yang akan dibuka. Anda juga dapat menggunakan objek ini untuk menentukan perilaku pembukaan dan penutupan menggunakan enumOpenAs
danOnClose
.Beberapa widget dapat menggunakan objek
Action
yang sama. Namun, Anda perlu menentukan objekAction
yang berbeda jika ingin memberikan parameter yang berbeda pada fungsi callback.Buat fungsi callback Anda tetap sederhana. Agar add-on tetap responsif, Layanan kartu membatasi fungsi callback hingga maksimum 30 detik waktu eksekusi. Jika eksekusi memerlukan waktu lebih lama dari itu, UI add-on Anda mungkin tidak memperbarui tampilan kartunya dengan benar sebagai respons terhadap
Action
.Jika status data pada backend pihak ketiga berubah karena interaksi pengguna dengan UI add-on Anda, sebaiknya add-on menetapkan bit 'status diubah' ke
true
sehingga cache sisi klien yang ada akan dihapus. Lihat deskripsi metodeActionResponseBuilder.setStateChanged()
untuk detail tambahan.