Tindakan add-on

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Tindakan add-on memberikan perilaku interaktif untuk widget. Dengan membuat tindakan, Anda menentukan apa yang terjadi saat pengguna memilih atau memperbarui 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 melakukan 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 ini:

  1. Buat objek Action, dengan menentukan fungsi callback yang harus dijalankan bersama dengan parameter yang diperlukan.
  2. Panggil fungsi pengendali widget yang sesuai di widget menggunakan objek Action.
  3. 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) memicu perilaku tindakan. Fungsi pengendali juga menentukan langkah yang diambil UI, jika ada, setelah tindakan selesai.

Tabel berikut mencantumkan berbagai jenis pengendali untuk widget dan widget yang digunakan:

Fungsi pengendali Tindakan pemicu Widget yang berlaku Deskripsi
setOnChangeAction() Nilai widget berubah DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
Menetapkan Action yang mengeksekusi 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 dipanggil. Anda dapat memasukkan informasi parameter tambahan dalam objek peristiwa ini jika diinginkan.
setOnClickAction() Pengguna mengklik widget CardAction
Image
ImageButton
DecoratedText
TextButton
Menetapkan Action yang menjalankan fungsi Apps Script saat pengguna mengklik widget. Pengendali secara otomatis meneruskan objek peristiwa ke fungsi yang dipanggil. 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 menyajikan draf tersebut kepada pengguna di jendela tulis UI Gmail. Anda dapat mem-build draf sebagai pesan baru atau balasan untuk pesan terbuka di Gmail. Saat memanggil fungsi callback pembuatan draf, pengendali akan meneruskan objek peristiwa ke fungsi callback. Lihat Pesan draf Compose untuk detail selengkapnya.
setOnClickOpenLinkAction() Pengguna mengklik widget CardAction
Image
ImageButton
DecoratedText
TextButton
Menetapkan Action untuk membuka URL saat pengguna mengklik widget. Gunakan pengendali ini saat Anda harus membuat URL atau tindakan lain harus dilakukan sebelum link terbuka; jika tidak, biasanya akan lebih mudah untuk 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
Langsung membuka URL saat pengguna mengklik widget. Gunakan pengendali ini jika Anda mengetahui URL tersebut dan hanya perlu membukanya; jika tidak, gunakan setOnClickOpenLinkAction(). Anda dapat membuka URL di jendela baru atau di overlay. Saat 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 dipanggil. Lihat Saran pelengkapan otomatis untuk input teks untuk detail selengkapnya.

Fungsi callback

Fungsi callback dieksekusi saat Action terpicu. Karena fungsi callback adalah fungsi Apps Script, Anda dapat meminta mereka untuk melakukan hampir semua fungsi skrip lainnya.

Fungsi callback terkadang menampilkan objek respons tertentu. Jenis respons ini menunjukkan operasi tambahan yang perlu terjadi setelah callback selesai mengeksekusi, seperti menampilkan kartu baru atau menampilkan saran pelengkapan otomatis. Jika fungsi callback Anda harus menampilkan objek respons tertentu, gunakan 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 akan ditampilkan
Menjelajahi antarkartu ActionResponse
Menampilkan Notification ActionResponse
Membuka link menggunakan setOnClickOpenLinkAction() ActionResponse
Menampilkan saran pelengkapan otomatis SuggestionResponse
Menggunakan tindakan universal UniversalActionResponse
Tindakan lainnya Tidak ada

Selain tindakan tersebut, setiap aplikasi host memiliki kumpulan tindakannya 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 saat ini dari pengguna, seperti nilai saat ini dari semua widget interaktif dalam 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 penjelasan lengkap tentang struktur objek peristiwa.