Halaman ini menjelaskan cara menambahkan widget dan elemen UI ke kartu agar pengguna dapat berinteraksi dengan aplikasi Google Chat, seperti dengan mengeklik tombol atau mengirimkan informasi.
Aplikasi Chat dapat menggunakan antarmuka Chat berikut untuk membuat kartu interaktif:
- Pesan yang berisi satu atau lebih kartu.
- Halaman beranda, yaitu kartu yang muncul dari tab Beranda secara langsung dengan aplikasi Chat.
- Dialog, yang merupakan kartu yang terbuka di jendela baru dari pesan dan halaman beranda.
Saat pengguna berinteraksi dengan kartu, aplikasi Chat dapat menggunakan data yang yang mereka terima untuk memproses dan merespons sesuai dengan itu. Untuk mengetahui detailnya, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.
Gunakan Card Builder untuk mendesain dan melihat pratinjau pesan dan antarmuka pengguna untuk aplikasi Chat:
Membuka Card BuilderPrasyarat
Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif, selesaikan salah satu panduan memulai berikut berdasarkan pada arsitektur aplikasi yang ingin Anda gunakan:
- Layanan HTTP dengan Google Cloud Functions
- Skrip Google Apps
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
Menambahkan tombol
Tujuan
Widget ButtonList
menampilkan satu set tombol. Tombol dapat menampilkan teks,
ikon, atau teks dan ikon. Masing-masing
Button
mendukung
Tindakan OnClick
yang terjadi ketika pengguna mengeklik tombol. Contoh:
- Buka hyperlink dengan
OpenLink, untuk memberikan informasi tambahan kepada pengguna. - Jalankan
actionyang menjalankan fungsi khusus, seperti memanggil API.
Untuk aksesibilitas, tombol mendukung teks alternatif.
Menambahkan tombol yang menjalankan fungsi kustom
Berikut adalah kartu yang terdiri dari widget ButtonList dengan dua tombol.
Satu tombol untuk membuka dokumentasi developer Google Chat di tab baru. Tujuan
tombol lain menjalankan fungsi khusus yang disebut goToView() dan meneruskan
Parameter viewType="BIRD EYE VIEW".
Menambahkan tombol dengan gaya Desain Material
Berikut ini menampilkan kumpulan tombol dalam tombol Desain Material yang berbeda gaya.
Untuk menerapkan gaya Desain Material, jangan sertakan 'warna' .
Menambahkan tombol dengan warna khusus dan tombol yang dinonaktifkan
Anda dapat mencegah pengguna mengklik tombol dengan menyetel "disabled": "true".
Kode berikut menampilkan kartu yang terdiri dari widget ButtonList dengan dua
tombol. Satu tombol menggunakan
Kolom Color
untuk menyesuaikan latar belakang tombol
{i>color<i}. Tombol lainnya dinonaktifkan dengan kolom Disabled, yang
mencegah pengguna mengklik tombol dan menjalankan fungsi.
Menambahkan tombol dengan ikon
Kode berikut menampilkan kartu yang terdiri dari widget ButtonList dengan dua ikon
Widget Button. Satu tombol menggunakan
knownIcon
untuk menampilkan ikon email bawaan Google Chat. Tombol lainnya menggunakan atribut
Kolom iconUrl untuk menampilkan
widget ikon kustom.
Menambahkan tombol dengan ikon dan teks
Kode berikut menampilkan kartu yang terdiri dari widget ButtonList yang meminta
pengguna untuk mengirim email. Tombol pertama menampilkan ikon email dan
tombol kedua menampilkan teks. Pengguna dapat mengklik ikon atau teks
untuk menjalankan fungsi sendEmail.
Menyesuaikan tombol untuk bagian yang dapat diciutkan
Sesuaikan tombol kontrol yang menciutkan dan meluaskan bagian dalam . Pilih dari beragam ikon atau gambar untuk mewakili secara visual konten rubrik, sehingga memudahkan pengguna untuk memahami dan berinteraksi dengan informasi.
Menambahkan Menu Luapan
Tujuan
Overflow menu
dapat digunakan di kartu Chat untuk menawarkan opsi dan tindakan tambahan. Memungkinkan
Anda menyertakan lebih banyak opsi tanpa mengacaukan antarmuka kartu, memastikan
desain yang rapi dan teratur.
Menambahkan daftar Chip
ChipList
menyediakan cara yang serbaguna dan menarik secara visual untuk menampilkan informasi.
Gunakan daftar chip untuk merepresentasikan tag, kategori, atau data relevan lainnya, sehingga
bagi pengguna untuk menavigasi dan berinteraksi dengan konten Anda.
Mengumpulkan informasi dari pengguna
Bagian ini menjelaskan cara menambahkan widget yang mengumpulkan informasi, seperti teks atau pilihan.
Untuk mempelajari cara memproses apa yang dimasukkan pengguna, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.
Kumpulkan teks
Widget TextInput
menyediakan kolom tempat pengguna dapat memasukkan teks. Tujuan
widget mendukung saran, yang membantu pengguna memasukkan data yang seragam, dan dapat berubah
tambahan, yaitu
Actions
yang berjalan ketika terjadi perubahan di isian {i>input <i}teks, seperti pengguna menambahkan atau
menghapus teks.
Jika Anda perlu mengumpulkan data abstrak atau yang tidak diketahui dari pengguna, gunakan data ini
Widget TextInput. Untuk mengumpulkan data yang ditentukan dari pengguna, gunakan
SelectionInput
widget ini.
Berikut adalah kartu yang terdiri dari widget TextInput:
Mengumpulkan tanggal atau waktu
Tujuan
Widget DateTimePicker
memungkinkan pengguna memasukkan tanggal, waktu, atau tanggal dan
waktu tertentu. Atau, pengguna dapat menggunakan pemilih untuk memilih tanggal dan waktu. Jika pengguna memasukkan
tanggal atau waktu yang tidak valid, pemilih akan menampilkan error yang meminta pengguna untuk memasukkan
informasi dengan benar.
Berikut ini menampilkan kartu yang terdiri dari tiga jenis informasi
Widget DateTimePicker:
Mengizinkan pengguna memilih item
Widget SelectionInput
menyediakan seperangkat item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol,
atau menu {i>drop-down.<i} Anda dapat menggunakan widget ini
untuk mengumpulkan data yang telah
didefinisikan dan distandarisasi dari pengguna. Untuk mengumpulkan data yang tidak terdefinisi
dari pengguna, gunakan widget TextInput.
Widget SelectionInput mendukung saran, yang membantu pengguna memasukkan kolom
data, dan tindakan on-change, yaitu
Actions
yang berjalan saat terjadi perubahan dalam bidang input pilihan, seperti pengguna
memilih atau membatalkan
pilihan suatu item.
Aplikasi Chat dapat menerima dan memproses nilai item yang dipilih. Untuk mengetahui detail tentang cara menggunakan input formulir, lihat Memproses informasi yang dimasukkan oleh pengguna.
Bagian ini memberikan contoh kartu yang menggunakan widget SelectionInput.
Contoh tersebut menggunakan jenis input bagian yang berbeda:
Tambahkan kotak centang
Kode berikut menampilkan kartu yang meminta pengguna menentukan apakah
kontak bersifat profesional, pribadi, atau keduanya, dengan widget SelectionInput yang
menggunakan kotak centang:
Menambahkan tombol pilihan
Kode berikut menampilkan kartu yang meminta pengguna menentukan apakah
kontak profesional atau pribadi dengan widget SelectionInput yang menggunakan
tombol pilihan:
Menambahkan tombol
Kode berikut menampilkan kartu yang meminta pengguna menentukan apakah
kontak bersifat profesional, pribadi, atau keduanya dengan widget SelectionInput yang
menggunakan {i>switch<i}:
Menambahkan menu drop-down
Kode berikut menampilkan kartu yang meminta pengguna menentukan apakah
kontak profesional atau pribadi dengan widget SelectionInput yang menggunakan
menu {i>drop-down<i}:
Menambahkan menu pilihan banyak
Berikut adalah kartu yang meminta pengguna memilih kontak dari menu pilihan ganda:
Anda dapat mengisi item untuk menu multi-pilihan dari data berikut sumber di Google Workspace:
- Pengguna Google Workspace: Anda hanya dapat mengisi pengguna dalam organisasi Google Workspace yang sama.
- Ruang chat: Pengguna memasukkan item di kotak multi-pilihan hanya dapat melihat dan memilih ruang tempat mereka berada di dalamnya pengaturan Google Workspace Anda.
Untuk menggunakan sumber data Google Workspace, Anda menentukan
platformDataSource
kolom tersebut. Tidak seperti jenis {i>input <i}pilihan lain, Anda menghilangkan
SectionItem
karena item pilihan ini bersumber secara dinamis dari
Gemini untuk Google Workspace.
Kode berikut menunjukkan menu pilihan beberapa pengguna Google Workspace.
Untuk mengisi pengguna, input pilihan menetapkan commonDataSource ke USER:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Kode berikut menunjukkan menu multi-pilihan Chat
spasi. Untuk mengisi ruang, input pilihan menentukan
Kolom hostAppDataSource. Menu {i>multiselect<i}
juga menetapkan
defaultToCurrentSpace menjadi true, yang menjadikan ruang saat ini sebagai default
pilihan di menu:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Menu multi-pilihan juga dapat mengisi item dari data pihak ketiga atau eksternal sumber. Misalnya, Anda dapat menggunakan menu multi-pilihan untuk membantu pengguna memilih dari daftar prospek penjualan dari sistem pengelolaan hubungan pelanggan (CRM).
Untuk menggunakan sumber data eksternal, gunakan kolom externalDataSource untuk
menentukan fungsi yang menampilkan item dari sumber data.
Untuk mengurangi permintaan ke sumber data eksternal, Anda dapat menyertakan
item yang disarankan yang muncul di menu multi-pilihan sebelum pengguna mengetik
menu. Misalnya, Anda dapat mengisi kontak yang baru-baru ini ditelusuri untuk
. Untuk mengisi item yang disarankan dari sumber data eksternal, tentukan
SelectionItem
objek terstruktur dalam jumlah besar.
Kode berikut menampilkan menu item dengan beberapa pilihan dari
sekumpulan kontak eksternal untuk pengguna. Menu menampilkan satu kontak secara default
dan menjalankan fungsi getContacts untuk mengambil serta mengisi item dari
sumber data eksternal:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 2,
"externalDataSource": {
"function": "getContacts"
},
"items": [
{
"text": "Contact 3",
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"bottomText": "Contact three description",
"selected": false
}
]
}
}
Untuk sumber data eksternal, Anda juga dapat melengkapi otomatis item yang dimulai pengguna
mengetik di menu
pilihan banyak. Misalnya, jika pengguna mulai mengetik Atl untuk
yang memenuhi berbagai kota di Amerika Serikat,
Aplikasi Chat dapat menyarankan otomatis Atlanta sebelum pengguna
selesai mengetik. Anda dapat melengkapi otomatis hingga 100 item.
Untuk melengkapi item secara otomatis, Anda membuat fungsi yang mengkueri data eksternal mendapatkan sumber dan menampilkan item setiap kali pengguna mengetik di menu pilihan banyak. Tujuan harus melakukan hal berikut:
- Meneruskan objek peristiwa yang merepresentasikan interaksi pengguna dengan menu.
- Identifikasi bahwa
invokedFunctioncocok dengan fungsi dari kolomexternalDataSource. - Jika fungsi cocok, tampilkan item yang disarankan dari data eksternal
sumber. Untuk menyarankan item berdasarkan apa yang diketik pengguna, dapatkan nilai untuk
Tombol
autocomplete_widget_query. Nilai ini mewakili apa yang diketik pengguna pada menu.
Kode berikut melengkapi otomatis item dari resource data eksternal. Menggunakan
contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan
saat fungsi getContacts dipicu:
Apps Script
Node.js
Memvalidasi data yang dimasukkan ke kartu
Halaman ini menjelaskan cara memvalidasi data yang dimasukkan ke action kartu
dan widget.
Misalnya, Anda dapat memvalidasi bahwa {i>field<i} {i>input <i}teks memiliki teks yang dimasukkan oleh
pengguna, atau yang berisi
sejumlah karakter tertentu.
Menyetel widget yang diperlukan untuk tindakan
Sebagai bagian dari action kartu,
menambahkan nama widget yang diperlukan tindakan ke daftar requiredWidgets-nya.
Jika widget yang tercantum di sini tidak memiliki nilai saat tindakan ini dipanggil, maka pengiriman tindakan formulir akan dibatalkan.
Jika "all_widgets_are_required": "true" ditetapkan untuk suatu tindakan, maka semua widget
pada kartu diperlukan oleh tindakan ini.
Tetapkan tindakan all_widgets_are_required di multi-pilihan
JSON
{
"sections": [
{
"header": "Select contacts",
"widgets": [
{
"selectionInput": {
"type": "MULTI_SELECT",
"label": "Selected contacts",
"name": "contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"value": "contact-1",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 1",
"bottomText": "Contact one description",
"selected": false
},
{
"value": "contact-2",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 2",
"bottomText": "Contact two description",
"selected": false
},
{
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 3",
"bottomText": "Contact three description",
"selected": false
},
{
"value": "contact-4",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 4",
"bottomText": "Contact four description",
"selected": false
},
{
"value": "contact-5",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 5",
"bottomText": "Contact five description",
"selected": false
}
]
}
}
]
}
]
}
Menyetel tindakan all_widgets_are_required di dateTimePicker
JSON
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "A datetime picker widget with both date and time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_and_time",
"label": "meeting",
"type": "DATE_AND_TIME"
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just date:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_only",
"label": "Choose a date",
"type": "DATE_ONLY",
"onChangeAction":{
"all_widgets_are_required": true
}
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_time_only",
"label": "Select a time",
"type": "TIME_ONLY"
}
}
]
}
]
}
Setel tindakan all_widgets_are_required di menu drop-down
JSON
{
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"selectionInput": {
"name": "location",
"label": "Select Color",
"type": "DROPDOWN",
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"text": "Red",
"value": "red",
"selected": false
},
{
"text": "Green",
"value": "green",
"selected": false
},
{
"text": "White",
"value": "white",
"selected": false
},
{
"text": "Blue",
"value": "blue",
"selected": false
},
{
"text": "Black",
"value": "black",
"selected": false
}
]
}
}
]
}
]
}
Menyetel validasi untuk widget input teks
Di textInput
tambahan, {i>widget<i}, dapat menentukan
batas karakter dan jenis {i>input <i}untuk
widget input teks ini.
Menetapkan batas karakter untuk widget input teks
JSON
{
"sections": [
{
"header": "Tell us about yourself",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "favoriteColor",
"label": "Favorite color",
"type": "SINGLE_LINE",
"validation": {"character_limit":15},
"onChangeAction":{
"all_widgets_are_required": true
}
}
}
]
}
]
}
Menetapkan jenis input untuk widget input teks
JSON
{
"sections": [
{
"header": "Validate text inputs by input types",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "mailing_address",
"label": "Please enter a valid email address",
"type": "SINGLE_LINE",
"validation": {
"input_type": "EMAIL"
},
"onChangeAction": {
"all_widgets_are_required": true
}
}
},
{
"textInput": {
"name": "validate_integer",
"label": "Please enter a number",
"type": "SINGLE_LINE",
"validation": {
"input_type": "INTEGER"
}
}
},
{
"textInput": {
"name": "validate_float",
"label": "Please enter a number with a decimal",
"type": "SINGLE_LINE",
"validation": {
"input_type": "FLOAT"
}
}
}
]
}
]
}
Memecahkan masalah
Saat aplikasi Google Chat atau kartu menampilkan error, Antarmuka Chat menampilkan pesan yang bertuliskan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi Chat atau memberikan hasil yang tidak diharapkan; misalnya, pesan kartu mungkin tidak akan muncul.
Meskipun pesan error mungkin tidak ditampilkan di UI Chat, pesan error deskriptif dan data log tersedia untuk membantu Anda memperbaiki error saat logging error untuk aplikasi Chat diaktifkan. Untuk bantuan melihat, men-debug, dan memperbaiki error, melihat Memecahkan masalah dan memperbaiki error Google Chat.