Input pilihan

Widget SelectionInput menyediakan sekumpulan item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol akses, atau menu dropdown. Anda dapat menggunakan widget ini untuk mengumpulkan data yang telah ditentukan dan distandardisasi 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 sesuai perubahan, yaitu Actions yang berjalan 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.

Contoh

Bagian ini memberikan contoh kartu yang menggunakan widget SelectionInput. Contoh tersebut menggunakan berbagai jenis input bagian:

Contoh 1: kotak centang

Berikut ini adalah dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional dan/atau pribadi dengan widget SelectionInput yang menggunakan kotak centang:

Contoh 2: tombol pilihan

Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan tombol pilihan:

Contoh 3: tombol

Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan tombol:

Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan menu dropdown:

Contoh 5: menu multi-pilihan

Berikut adalah dialog yang meminta pengguna untuk memilih kontak dari menu multi-pilihan:

Sumber data tambahan untuk menu multi-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 dalam organisasi Google Workspace yang sama.
  • Ruang chat: Pengguna yang memasukkan item di menu multi-pilihan hanya dapat melihat dan memilih ruang tempatnya 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 berasal dari Google Workspace secara dinamis.

Kode berikut menunjukkan menu multi-pilihan pengguna Google Workspace. Untuk mengisi pengguna, input pemilihan akan 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 menjadikan ruang saat ini sebagai pilihan default di 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 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 pengguna. 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 menampilkan satu kontak secara default dan menjalankan fungsi getContacts untuk mengambil dan 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 mulai diketik pengguna di menu multi-pilihan. Misalnya, jika pengguna mulai mengetik Atl untuk menu yang mengisi 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, Anda harus membuat 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 mewakili interaksi pengguna dengan menu.
  • Identifikasi bahwa nilai invokedFunction peristiwa interaksi cocok dengan fungsi dari kolom externalDataSource.
  • 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 di ketik pengguna di menu.

Kode berikut melengkapi otomatis item dari resource data eksternal. Menggunakan contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan waktu 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
            },
          ]
        }
      }
    }
  };
}

Representasi dan kolom JSON

Representasi JSON
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}
Kolom
name

string

Nama yang mengidentifikasi input pemilihan dalam peristiwa input formulir.

Untuk mengetahui detail tentang cara menggunakan input formulir, lihat Menerima data formulir.

label

string

Teks yang muncul di atas kolom input pilihan di antarmuka pengguna.

Tentukan teks yang membantu pengguna memasukkan informasi yang dibutuhkan aplikasi Anda. Misalnya, jika pengguna memilih urgensi tiket kerja dari menu drop-down, labelnya mungkin "Urgensi" atau "Pilih urgensi".

type

enum (SelectionType)

Jenis item yang ditampilkan kepada pengguna di widget SelectionInput. Jenis pilihan mendukung berbagai jenis interaksi. Misalnya, pengguna dapat memilih satu atau beberapa kotak centang, tetapi mereka hanya dapat memilih satu nilai dari menu dropdown.

items[]

object (SelectionItem)

Array item yang dapat dipilih. Misalnya, array tombol pilihan atau kotak centang. Mendukung hingga 100 item.

onChangeAction

object (Action)

Jika ditentukan, formulir akan dikirimkan saat pilihan berubah. Jika tidak ditentukan, Anda harus menentukan tombol terpisah yang mengirimkan formulir.

Untuk mengetahui detail tentang cara menggunakan input formulir, lihat Menerima data formulir.

multiSelectMaxSelectedItems

integer

Untuk menu multi-pilihan, jumlah item maksimum yang dapat dipilih pengguna. Nilai minimum adalah 1 item. Jika tidak ditentukan, ditetapkan secara default ke 3 item.

multiSelectMinQueryLength

integer

Untuk menu multi-pilihan, jumlah karakter teks yang dimasukkan pengguna sebelum kueri aplikasi Chat akan dilengkapi otomatis dan menampilkan item yang disarankan dalam menu.

Jika tidak ditentukan, nilai defaultnya adalah 0 karakter untuk sumber data statis dan 3 karakter untuk sumber data eksternal.

Kolom gabungan multi_select_data_source. Khusus aplikasi Chat. Untuk menu multi-pilihan, sumber data yang mengisi item pilihan. multi_select_data_source hanya dapat berupa salah satu dari berikut:
externalDataSource

object (Action)

Sumber data eksternal, seperti basis data relasional.

platformDataSource

object (PlatformDataSource)

Sumber data dari Google Workspace.

SelectionType

Enum
CHECK_BOX Sekumpulan kotak centang. Pengguna dapat memilih satu atau beberapa kotak centang.
RADIO_BUTTON Sekumpulan tombol pilihan. Pengguna dapat memilih satu tombol pilihan.
SWITCH Seperangkat tombol akses. Pengguna dapat mengaktifkan satu atau beberapa tombol.
DROPDOWN Menu dropdown. Pengguna dapat memilih satu item dari menu.
MULTI_SELECT

Didukung oleh aplikasi Chat, tetapi tidak didukung oleh Add-on Google Workspace.

Menu multi-pilihan untuk data statis atau dinamis. Dari panel menu, pengguna memilih satu atau beberapa item. Pengguna juga dapat memasukkan nilai untuk mengisi data dinamis. Misalnya, pengguna dapat mulai mengetik nama ruang Google Chat dan widget akan otomatis menyarankan ruang tersebut.

Untuk mengisi item untuk menu multi-pilihan, Anda dapat menggunakan salah satu jenis sumber data berikut:

  • Data statis: Item ditetapkan sebagai objek SelectionItem di widget. Hingga 100 item.
  • Data Google Workspace: Item diisi menggunakan data dari Google Workspace, seperti pengguna Google Workspace atau ruang Google Chat.
  • Data eksternal: Item diisi dari sumber data eksternal di luar Google Workspace.

Untuk contoh cara menerapkan menu multi-pilihan, lihat halaman widget SelectionInput .

SelectionItem

Representasi JSON
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
Kolom
text

string

Teks yang mengidentifikasi atau menjelaskan item kepada pengguna.

value

string

Nilai yang terkait dengan item ini. Klien harus menggunakannya sebagai nilai input formulir.

Untuk mengetahui detail tentang cara menggunakan input formulir, lihat Menerima data formulir.

selected

boolean

Apakah item dipilih secara default. Jika input pilihan hanya menerima satu nilai (seperti untuk tombol pilihan atau menu dropdown), tetapkan kolom ini untuk satu item saja.

startIconUri

string

Untuk menu multi-pilihan, URL untuk ikon yang ditampilkan di samping kolom text item. Mendukung file PNG dan JPEG. Harus berupa URL HTTPS. Misalnya, https://developers.google.com/chat/images/quickstart-app-avatar.png.

bottomText

string

Untuk menu multi-pilihan, deskripsi teks atau label yang ditampilkan di bawah kolom text item.

Tindakan

Tindakan yang menjelaskan perilaku saat formulir dikirimkan. Misalnya, Anda dapat memanggil skrip Apps Script untuk menangani formulir. Jika tindakan tersebut dipicu, nilai formulir akan dikirim ke server.

Representasi JSON
{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction)
}
Kolom
function

string

Fungsi kustom yang akan dipanggil saat elemen penampung diklik atau diaktifkan sebaliknya.

Untuk contoh penggunaan, lihat Membuat kartu interaktif.

parameters[]

object (ActionParameter)

Daftar parameter tindakan.

loadIndicator

enum (LoadIndicator)

Menentukan indikator pemuatan yang ditampilkan tindakan saat melakukan panggilan ke tindakan.

persistValues

boolean

Menunjukkan apakah nilai formulir tetap ada setelah tindakan. Nilai defaultnya adalah false.

Jika true, nilai formulir akan tetap ada setelah tindakan dipicu. Untuk mengizinkan pengguna membuat perubahan saat tindakan sedang diproses, tetapkan LoadIndicator ke NONE. Untuk pesan kartu di aplikasi Chat, Anda juga harus menetapkan ResponseType tindakan ke UPDATE_MESSAGE dan menggunakan cardId yang sama dari kartu yang berisi tindakan tersebut.

Jika false, nilai formulir akan dihapus saat tindakan dipicu. Untuk mencegah pengguna membuat perubahan saat tindakan sedang diproses, tetapkan LoadIndicator ke SPINNER.

interaction

enum (Interaction)

Opsional. Diperlukan saat membuka dialog.

Apa yang harus dilakukan sebagai respons terhadap interaksi dengan pengguna, seperti pengguna yang mengklik tombol di pesan kartu.

Jika tidak ditentukan, aplikasi akan merespons dengan mengeksekusi action —seperti membuka link atau menjalankan fungsi—seperti biasa.

Dengan menentukan interaction, aplikasi dapat merespons dengan cara interaktif khusus. Misalnya, dengan menetapkan interaction ke OPEN_DIALOG, aplikasi dapat membuka dialog. Jika ditentukan, indikator pemuatan tidak ditampilkan.

Didukung oleh aplikasi Chat, tetapi tidak didukung oleh Add-on Google Workspace. Jika ditentukan untuk add-on, seluruh kartu akan dihapus dan tidak ada yang ditampilkan di klien.

ActionParameter

Daftar parameter string yang akan diberikan saat metode tindakan dipanggil. Misalnya, pertimbangkan tiga tombol tunda: tunda sekarang, tunda satu hari, atau tunda minggu depan. Anda dapat menggunakan action method = snooze(), yang meneruskan jenis penundaan dan waktu tunda dalam daftar parameter string.

Untuk mempelajari lebih lanjut, lihat CommonEventObject.

Representasi JSON
{
  "key": string,
  "value": string
}
Kolom
key

string

Nama parameter untuk skrip tindakan.

value

string

Nilai parameter.

LoadIndicator

Menentukan indikator pemuatan yang ditampilkan tindakan saat melakukan panggilan ke tindakan.

Enum
SPINNER Menampilkan indikator lingkaran berputar untuk menunjukkan bahwa konten sedang dimuat.
NONE Tidak ada yang ditampilkan.

Interaksi

Opsional. Diperlukan saat membuka dialog.

Apa yang harus dilakukan sebagai respons terhadap interaksi dengan pengguna, seperti pengguna yang mengklik tombol di pesan kartu.

Jika tidak ditentukan, aplikasi akan merespons dengan mengeksekusi action —seperti membuka link atau menjalankan fungsi—seperti biasa.

Dengan menentukan interaction, aplikasi dapat merespons dengan cara interaktif khusus. Misalnya, dengan menetapkan interaction ke OPEN_DIALOG, aplikasi dapat membuka dialog.

Jika ditentukan, indikator pemuatan tidak ditampilkan.

Didukung oleh aplikasi Chat, tetapi tidak didukung oleh Add-on Google Workspace. Jika ditentukan untuk add-on, seluruh kartu akan dihapus dan tidak ada yang ditampilkan di klien.

Enum
INTERACTION_UNSPECIFIED Nilai default. action dijalankan seperti biasa.
OPEN_DIALOG

Membuka dialog, yakni antarmuka berbasis kartu dan berjendela yang digunakan aplikasi Chat untuk berinteraksi dengan pengguna.

Hanya didukung oleh aplikasi Chat sebagai respons terhadap klik tombol pada pesan kartu.

Tidak didukung oleh Add-on Google Workspace. Jika ditentukan untuk add-on, seluruh kartu akan dihapus dan tidak ada yang ditampilkan di klien.

Memecahkan masalah

Saat aplikasi atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang menyatakan "Terjadi error" 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, melakukan proses debug, dan memperbaiki error, lihat Memecahkan masalah dan memperbaiki error Google Chat.