Menambahkan elemen UI interaktif ke kartu

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 Builder

Prasyarat

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:

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 action yang 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}:

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 invokedFunction cocok dengan fungsi dari kolom externalDataSource.
  • 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

apps-script/selection-input/on-widget-update.gs
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

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.