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 Anda, misalnya dengan mengklik tombol atau mengirimkan informasi.

Aplikasi Chat dapat menggunakan antarmuka Chat berikut untuk membuat kartu interaktif:

  • Pesan yang berisi satu atau beberapa kartu.
  • Halaman beranda, yang merupakan kartu yang muncul dari tab Beranda dalam pesan 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 diterima untuk memproses dan meresponsnya. Untuk mengetahui detailnya, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.

Gunakan Card Builder untuk mendesain dan melihat pratinjau pesan serta antarmuka pengguna untuk aplikasi Chat:

Buka Card Builder

Prasyarat

Aplikasi Google Chat yang dikonfigurasi untuk menerima dan merespons interaksi pengguna. Untuk membuat aplikasi Chat interaktif, selesaikan salah satu panduan memulai berikut berdasarkan arsitektur aplikasi yang ingin Anda gunakan:

Menambahkan tombol

Widget ButtonList menampilkan sekumpulan tombol. Tombol dapat 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 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 gaya Desain Material

Berikut ini menampilkan kumpulan tombol dalam berbagai gaya tombol Desain Material.

Untuk menerapkan gaya Desain Material, jangan sertakan atribut 'color'.

Menambahkan tombol dengan warna kustom dan tombol yang dinonaktifkan

Anda dapat mencegah pengguna mengklik tombol dengan menyetel "disabled": "true".

Berikut ini 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 ini menampilkan kartu yang terdiri dari widget ButtonList dengan dua widget ikon 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 tombol ikon atau teks untuk menjalankan fungsi sendEmail.

Menyesuaikan tombol untuk bagian yang dapat diciutkan

Sesuaikan tombol kontrol yang menciutkan dan meluaskan bagian dalam kartu. Pilih dari berbagai ikon atau gambar untuk merepresentasikan konten bagian secara visual, sehingga memudahkan pengguna untuk memahami dan berinteraksi dengan informasi.

Menambahkan Menu Tambahan

Overflow menu dapat digunakan di kartu Chat untuk menawarkan opsi dan tindakan tambahan. Dengan begitu, Anda dapat menyertakan lebih banyak opsi tanpa mengacaukan antarmuka kartu, sehingga memastikan desain yang rapi dan teratur.

Menambahkan daftar Chip

Widget ChipList menyediakan cara yang serbaguna dan menarik secara visual untuk menampilkan informasi. Gunakan daftar chip untuk merepresentasikan tag, kategori, atau data relevan lainnya, sehingga memudahkan 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 input pengguna, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.

Mengumpulkan teks

Widget TextInput menyediakan kolom tempat pengguna dapat memasukkan teks. Widget ini mendukung saran, yang membantu pengguna memasukkan data yang seragam, dan tindakan saat terjadi perubahan, yang merupakan Actions yang berjalan saat terjadi perubahan di kolom input teks, seperti pengguna 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.

Berikut adalah kartu yang terdiri dari widget TextInput:

Mengumpulkan tanggal atau waktu

Widget DateTimePicker memungkinkan pengguna memasukkan tanggal, waktu, atau tanggal dan waktu. Atau, pengguna dapat menggunakan alat pilih 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 widget DateTimePicker yang berbeda:

Mengizinkan pengguna memilih item

Widget SelectionInput menyediakan serangkaian item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol akses, atau menu drop-down. Anda dapat menggunakan widget ini untuk mengumpulkan data yang 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 yang seragam, dan tindakan saat perubahan, yang merupakan Actions yang berjalan saat terjadi perubahan di kolom input pilihan, 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 Memproses informasi yang diinput oleh pengguna.

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

Menambahkan kotak centang

Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah kontak bersifat profesional, pribadi, atau keduanya, dengan widget SelectionInput yang menggunakan kotak centang:

Menambahkan tombol pilihan

Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan tombol pilihan:

Menambahkan tombol

Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah kontak bersifat profesional, pribadi, atau keduanya dengan widget SelectionInput yang menggunakan tombol:

Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan menu drop-down:

Mengisi menu drop-down secara dinamis

Tersedia untuk aplikasi Google Chat.

Anda dapat mengisi item secara dinamis untuk menu drop-down dari sumber data di Google Workspace atau dari sumber data eksternal. Untuk menggunakan sumber data dinamis, tentukan kolom dataSourceConfigs, yang merupakan array objek DataSourceConfig. Setiap DataSourceConfig dapat berisi platformDataSource atau remoteDataSource. Saat ini, hanya satu DataSourceConfig yang didukung.

Mengisi item dari Google Workspace

Untuk mengisi item dari sumber data Google Workspace, seperti pengguna Google Workspace, Anda menentukan kolom platformDataSource dalam DataSourceConfig. Tidak seperti penggunaan items statis, Anda menghilangkan objek SelectionItem, karena item pilihan ini bersumber secara dinamis dari Google Workspace.

Kode berikut menampilkan menu drop-down yang mengisi pengguna Google Workspace:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}
Mengisi item dari sumber data eksternal

Untuk mengisi item dari sumber data pihak ketiga atau eksternal, seperti sistem pengelolaan hubungan pelanggan (CRM), Anda menggunakan kolom remoteDataSource dalam DataSourceConfig untuk menentukan fungsi yang menampilkan item dari sumber data.

Kode berikut menampilkan menu drop-down yang mengisi item dari kumpulan kontak eksternal dengan menjalankan fungsi getCrmLeads:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Untuk mengurangi permintaan ke sumber data dinamis, Anda dapat menyertakan item yang disarankan yang muncul di menu drop-down sebelum pengguna mengetik. Anda juga dapat mengonfigurasi drop-down untuk melengkapi item secara otomatis berdasarkan apa yang diketik pengguna dengan menetapkan minCharactersTrigger dalam DataSourceConfig. Saat pengguna mengetik setidaknya jumlah karakter yang ditentukan dalam minCharactersTrigger, fungsi yang ditentukan dalam remoteDataSource akan dipicu. Objek peristiwa yang diteruskan ke fungsi Anda menyertakan input pengguna dalam kunci autocomplete_widget_query.

Menambahkan menu pilihan ganda

Berikut ini menampilkan kartu yang meminta pengguna memilih kontak dari menu pilihan ganda:

Anda dapat mengisi item untuk menu pilihan ganda 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 pilihan ganda hanya dapat melihat dan memilih ruang yang mereka ikuti dalam organisasi Google Workspace mereka.

Untuk menggunakan sumber data Google Workspace, tentukan kolom platformDataSource. Tidak seperti jenis input pilihan lainnya, Anda menghilangkan objek SelectionItem, karena item pilihan ini bersumber secara dinamis dari Google Workspace.

Kode berikut menampilkan menu multi-pilihan 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 menampilkan menu multipilih ruang Chat. Untuk mengisi ruang, input pilihan menentukan kolom hostAppDataSource. Menu pilihan ganda juga menetapkan defaultToCurrentSpace ke true, yang menjadikan ruang saat ini sebagai pilihan default dalam menu:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Menu multi-pilih juga dapat mengisi item dari sumber data pihak ketiga atau eksternal. Misalnya, Anda dapat menggunakan menu multi-pilihan untuk membantu pengguna memilih dari daftar lead 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 pilihan ganda sebelum pengguna mengetik di 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.

Contoh kode berikut menunjukkan menu multi-pilihan yang mengkueri dan mengisi item dari sumber data eksternal:

Node.js

node/chat/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: FUNCTION_URL },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Ganti FUNCTION_URL dengan endpoint HTTP yang mengkueri sumber data eksternal.

Python

python/chat/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': FUNCTION_URL },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_suggested_contact("3")]
}

Ganti FUNCTION_URL dengan endpoint HTTP yang mengkueri sumber data eksternal.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

Ganti FUNCTION_URL dengan endpoint HTTP yang mengkueri sumber data eksternal.

Apps Script

Contoh ini mengirimkan pesan kartu dengan menampilkan JSON kartu. Anda juga dapat menggunakan layanan kartu Apps Script.

apps-script/chat/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "queryContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Mengisi item yang disarankan dari sumber data dinamis

Untuk sumber data eksternal, Anda juga dapat melengkapi otomatis dan menyarankan item yang mulai diketik pengguna di menu pilihan ganda atau menu drop-down. Misalnya, jika pengguna mulai mengetik Atl untuk menu yang menampilkan kota di Amerika Serikat, aplikasi Chat Anda dapat otomatis menyarankan Atlanta sebelum pengguna selesai mengetik. Anda dapat menyarankan hingga 100 item.

Untuk menampilkan item yang disarankan, fungsi yang mengkueri sumber data eksternal harus melakukan hal berikut:

  1. Menangani objek peristiwa, yang diterima aplikasi Chat saat pengguna mengetik di menu.
  2. Dari objek peristiwa, dapatkan nilai yang diketik pengguna, yang direpresentasikan dalam kolom event.commonEventObject.parameters["autocomplete_widget_query"].
  3. Buat kueri sumber data menggunakan nilai input pengguna untuk mendapatkan satu atau beberapa SelectionItems yang akan disarankan kepada pengguna.
  4. Tampilkan item yang disarankan dengan menampilkan tindakan RenderActions dengan objek modifyCard.

Contoh kode berikut menunjukkan cara aplikasi Chat menyarankan item secara dinamis di menu pilihan ganda pada kartu. Saat pengguna mengetik ke dalam menu, fungsi atau endpoint yang disediakan di kolom externalDataSource widget akan mengkueri sumber data eksternal, dan menyarankan item yang dapat dipilih pengguna:

Node.js

node/chat/selection-input/index.js
/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Ganti FUNCTION_URL dengan endpoint HTTP yang mengkueri sumber data eksternal.

Python

python/chat/selection-input/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Ganti FUNCTION_URL dengan endpoint HTTP yang mengkueri sumber data eksternal.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

Ganti FUNCTION_URL dengan endpoint HTTP yang mengkueri sumber data eksternal.

Apps Script

Contoh ini mengirimkan pesan kartu dengan menampilkan JSON kartu. Anda juga dapat menggunakan layanan kartu Apps Script.

apps-script/chat/selection-input/selection-input.gs
/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

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 memiliki teks yang dimasukkan oleh pengguna, atau berisi jumlah karakter tertentu.

Menetapkan 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 "allWidgetsAreRequired": true ditetapkan untuk suatu tindakan, semua widget dalam kartu akan diperlukan oleh tindakan ini.

Menetapkan tindakan allWidgetsAreRequired dalam multiseleksi

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "allWidgetsAreRequired": 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 allWidgetsAreRequired 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":{
              "allWidgetsAreRequired": 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 allWidgetsAreRequired di menu drop-down

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "allWidgetsAreRequired": 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

Di kolom validasi widget textInput, Anda dapat menentukan batas karakter dan jenis input 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": {"characterLimit": 15},
            "onChangeAction":{
              "allWidgetsAreRequired": 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": {
              "inputType": "EMAIL"
            },
            "onChangeAction": {
              "allWidgetsAreRequired": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "inputType": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "inputType": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

Memecahkan masalah

Saat aplikasi atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang bertuliskan "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 terduga; 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.

Aplikasi Chat yang bukan add-on: Mendesain kartu dan dialog interaktif

Dokumentasi berikut berlaku untuk aplikasi Chat yang bukan add-on Google Workspace. Untuk memigrasikan aplikasi Chat yang bukan add-on, lihat Mengonversi aplikasi Google Chat menjadi add-on Google Workspace.

Kode berikut menampilkan menu pilihan ganda item dari kumpulan kontak eksternal untuk pengguna di aplikasi Chat yang bukan add-on. Menu ini menampilkan satu kontak secara default dan menjalankan fungsi getContacts untuk mengambil dan mengisi item dari sumber data eksternal:

Node.js

node/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Python

python/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

Apps Script

apps-script/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Untuk melengkapi item secara otomatis di aplikasi Chat yang bukan add-on, buat fungsi yang mengkueri sumber data eksternal dan menampilkan item setiap kali pengguna mengetik di menu multipilih. Fungsi ini harus melakukan hal berikut:

  • Teruskan 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 apa yang diketik pengguna, dapatkan nilai untuk kunci autocomplete_widget_query. Nilai ini mewakili apa yang diketik pengguna di menu.

Kode berikut melengkapi item secara otomatis dari resource data eksternal. Dengan menggunakan contoh sebelumnya, aplikasi Chat yang bukan add-on akan menyarankan item berdasarkan kapan fungsi getContacts dipicu:

Node.js

node/selection-input/index.js
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Python

python/selection-input/main.py
def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

Apps Script

apps-script/selection-input/selection-input.gs
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}