Halaman ini menjelaskan cara menambahkan widget dan elemen UI ke pesan dialog atau kartu sehingga pengguna dapat berinteraksi dengan aplikasi Google Chat Anda, seperti dengan mengklik tombol atau mengirimkan informasi.
Gunakan Card Builder untuk mendesain dan melihat pratinjau pesan kartu JSON untuk aplikasi Chat:
Buka Pembuat KartuPrasyarat
Menambahkan tombol
Widget ButtonList
menampilkan serangkaian tombol. Tombol bisa menampilkan teks, ikon, atau teks dan ikon. Setiap
Button
mendukung
tindakan OnClick
yang terjadi saat pengguna mengklik tombol. Contoh:
- Buka hyperlink dengan
OpenLink
, untuk memberikan informasi tambahan kepada pengguna. - Jalankan
action
yang menjalankan fungsi kustom, 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 akan membuka dokumentasi developer Google Chat di tab baru. Tombol lainnya menjalankan fungsi kustom yang disebut goToView()
dan meneruskan parameter viewType="BIRD EYE VIEW"
.
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 warna latar
belakang tombol. Tombol lainnya dinonaktifkan dengan kolom Disabled
, yang
mencegah pengguna mengklik tombol dan menjalankan fungsi.
Menambahkan tombol dengan ikon
Berikut adalah kartu yang terdiri dari widget ButtonList
dengan dua ikon widget Button
. Satu tombol menggunakan kolom
knownIcon
untuk menampilkan ikon email bawaan Google Chat. Tombol lainnya menggunakan kolom iconUrl
untuk menampilkan widget ikon kustom.
Menambahkan tombol dengan ikon dan teks
Berikut ini 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 tombol
teks untuk menjalankan fungsi sendEmail
.
Menambahkan elemen UI yang dapat dipilih
Widget SelectionInput
menyediakan sekumpulan item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol akses,
atau menu drop-down. Anda dapat menggunakan widget ini untuk mengumpulkan data yang telah ditentukan dan distandarisasi dari pengguna. Untuk mengumpulkan data yang tidak ditentukan
dari pengguna, gunakan widget TextInput
.
Widget SelectionInput
mendukung saran, yang membantu pengguna memasukkan data
seragam, dan tindakan atas perubahan, yaitu
Actions
yang dijalankan saat perubahan terjadi di kolom input pemilihan, seperti pengguna
memilih atau membatalkan pilihan item.
Aplikasi Chat dapat menerima dan memproses nilai item yang dipilih. Untuk mengetahui detail tentang cara menggunakan input formulir, lihat Menerima data formulir.
Bagian ini memberikan contoh kartu yang menggunakan widget SelectionInput
.
Contoh tersebut menggunakan berbagai jenis input bagian:
Menambahkan kotak centang
Berikut adalah dialog yang meminta pengguna untuk menentukan apakah
kontak adalah profesional, pribadi, atau keduanya, dengan widget SelectionInput
yang
menggunakan kotak centang:
Menambahkan tombol pilihan
Berikut adalah dialog yang meminta pengguna untuk menentukan apakah
kontak bersifat profesional atau pribadi dengan widget SelectionInput
yang menggunakan
tombol pilihan:
Menambahkan tombol
Berikut adalah dialog yang meminta pengguna untuk menentukan apakah
kontak adalah profesional, pribadi, atau keduanya dengan widget SelectionInput
yang
menggunakan tombol akses:
Menambahkan menu drop-down
Berikut adalah dialog yang meminta pengguna untuk menentukan apakah
kontak bersifat profesional atau pribadi dengan widget SelectionInput
yang menggunakan
menu drop-down:
Menambahkan menu multi-pilihan
Berikut adalah dialog yang meminta pengguna untuk memilih kontak dari menu multi-pilihan:
Menggunakan sumber data untuk menu dengan banyak pilihan
Bagian berikut menjelaskan cara menggunakan menu multi-pilihan untuk mengisi data dari sumber dinamis, seperti aplikasi Google Workspace atau sumber data eksternal.
Sumber data dari Google Workspace
Anda dapat mengisi item untuk menu multi-pilihan dari sumber data berikut di Google Workspace:
- Pengguna Google Workspace: Anda hanya dapat mengisi pengguna di dalam organisasi Google Workspace yang sama.
- Ruang chat: Pengguna yang memasukkan item di menu multi-pilihan hanya dapat melihat dan memilih ruang tempat mereka berada dalam organisasi Google Workspace mereka.
Untuk menggunakan sumber data Google Workspace, tentukan kolom
platformDataSource
. Tidak seperti jenis input pemilihan lainnya, Anda menghilangkan
objek SectionItem
, karena item pemilihan ini bersumber secara dinamis dari
Google Workspace.
Kode berikut menampilkan menu multi-pilihan pengguna Google Workspace.
Untuk mengisi pengguna, input pemilihan 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 ruang Chat. Untuk mengisi ruang, input pemilihan menentukan
kolom hostAppDataSource
. Menu multi-pilihan juga menetapkan
defaultToCurrentSpace
ke true
, yang membuat ruang saat ini menjadi pilihan
default dalam menu:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Sumber data di luar Google Workspace
Menu multi-pilihan juga dapat mengisi item dari sumber data pihak ketiga atau eksternal. Misalnya, Anda dapat menggunakan menu beberapa 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 tersebut.
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 pengguna yang baru saja ditelusuri. Untuk mengisi item yang disarankan dari sumber data eksternal, tentukan
objek
SelectionItem
.
Kode berikut menunjukkan menu multi-pilihan item dari
kumpulan kontak eksternal untuk pengguna. Menu ini 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 otomatis melengkapi item yang mulai
diketik pengguna di menu multi-pilihan. Misalnya, jika pengguna mulai mengetik Atl
untuk menu yang mengisi kota-kota di Amerika Serikat, aplikasi Chat Anda dapat menyarankan Atlanta
secara otomatis sebelum pengguna selesai mengetik. Anda dapat melengkapi otomatis hingga 100 item.
Untuk melengkapi item secara otomatis, buat fungsi yang mengkueri sumber data eksternal dan menampilkan item setiap kali pengguna mengetik di menu multi-pilihan. Fungsi ini harus melakukan hal berikut:
- Meneruskan objek peristiwa yang merepresentasikan interaksi pengguna dengan menu.
- Identifikasi bahwa nilai
invokedFunction
peristiwa interaksi cocok dengan fungsi dari kolomexternalDataSource
. - Jika fungsi cocok, tampilkan item yang disarankan dari sumber data eksternal. Untuk menyarankan item berdasarkan jenis pengguna, dapatkan nilai untuk
kunci
autocomplete_widget_query
. Nilai ini mewakili apa yang diketik pengguna di menu.
Kode berikut akan melengkapi item secara otomatis dari resource data eksternal. Menggunakan contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan kapan fungsi getContacts
dipicu:
Apps Script
Node.js
Tambahkan kolom tempat pengguna dapat memasukkan teks
Widget TextInput
menyediakan kolom tempat pengguna dapat memasukkan teks. Widget
mendukung saran, yang membantu pengguna memasukkan data seragam, dan tindakan
atas perubahan, yaitu
Actions
yang berjalan saat terjadi perubahan di kolom input teks, seperti pengguna yang menambahkan atau
menghapus teks.
Jika Anda perlu mengumpulkan data abstrak atau tidak diketahui dari pengguna, gunakan widget TextInput
ini. Untuk mengumpulkan data yang ditentukan dari pengguna, gunakan
widget
SelectionInput
.
Untuk memproses teks yang dimasukkan pengguna, lihat Menerima data formulir.
Berikut adalah kartu yang terdiri dari widget TextInput
:
Memungkinkan pengguna memilih tanggal dan waktu
Widget DateTimePicker
memungkinkan pengguna memasukkan tanggal, waktu, atau tanggal dan waktu. Atau, pengguna dapat menggunakan pemilih untuk memilih tanggal dan waktu. Jika pengguna memasukkan
tanggal atau waktu yang tidak valid, alat pilih akan menampilkan error yang meminta pengguna untuk memasukkan
informasi dengan benar.
Untuk memproses nilai tanggal dan waktu yang dimasukkan pengguna, lihat bagian Menerima data formulir.
Berikut adalah kartu yang terdiri dari tiga jenis widget
DateTimePicker
yang berbeda:
Memvalidasi data yang dimasukkan ke kartu
Halaman ini menjelaskan cara memvalidasi data yang dimasukkan ke action
dan widget kartu.
Misalnya, Anda dapat memvalidasi bahwa kolom input teks berisi teks yang dimasukkan oleh
pengguna, atau bahwa kolom tersebut berisi sejumlah karakter tertentu.
Menyetel widget yang diperlukan untuk tindakan
Sebagai bagian dari action
kartu,
tambahkan nama widget yang diperlukan tindakan ke daftar requiredWidgets
-nya.
Jika widget yang tercantum di sini tidak memiliki nilai saat tindakan ini dipanggil, pengiriman tindakan formulir akan dibatalkan.
Jika "all_widgets_are_required": "true"
ditetapkan untuk suatu tindakan, maka semua widget di kartu diperlukan oleh tindakan ini.
Tetapkan tindakan all_widgets_are_required
dalam 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
}
]
}
}
]
}
]
}
Menetapkan 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"
}
}
]
}
]
}
Tetapkan 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
}
]
}
}
]
}
]
}
Menetapkan validasi untuk widget input teks
Dalam kolom validasi widget textInput
, widget ini dapat menentukan batas karakter dan jenis input untuk
widget input teks ini.
Menyetel 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
}
}
}
]
}
]
}
Menyetel 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 atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang menyatakan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi atau kartu Chat memberikan hasil yang tidak diharapkan. Misalnya, pesan kartu mungkin tidak 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 mendapatkan bantuan dalam melihat, men-debug, dan memperbaiki error, lihat Memecahkan masalah dan memperbaiki error Google Chat.