Dane wejściowe do wyboru

Widżet SelectionInput zawiera zestaw elementów, które można wybrać, takich jak pola wyboru, przyciski, przełączniki i menu. Możesz używać tego widżetu do zbierania zdefiniowanych i ustandaryzowanych danych o użytkownikach. Aby zbierać niezdefiniowane dane od użytkowników, użyj widżetu TextInput.

Widżet SelectionInput obsługuje sugestie, które ułatwiają użytkownikom wprowadzanie jednolitych danych oraz działania związane ze zmianą, czyli Actions uruchamiane, gdy zachodzi zmiana w polu do wprowadzania wyboru (np. użytkownik wybiera lub odznacza element).

Aplikacje do obsługi czatu mogą odbierać i przetwarzać wartość wybranych elementów. Więcej informacji o pracy z danymi wejściowymi do formularzy znajdziesz w artykule Odbieranie danych z formularzy.

Przykłady

Ta sekcja zawiera przykłady kart korzystających z widżetu SelectionInput. W przykładach użyto różnych typów danych wejściowych sekcji:

Przykład 1: pola wyboru

Poniżej widać okno z prośbą o podanie przez użytkownika, czy kontakt jest zawodowy czy osobisty, za pomocą widżetu SelectionInput z polami wyboru:

Przykład 2: przyciski opcji

Poniżej widać okno z prośbą o podanie przez użytkownika, czy kontakt ma charakter zawodowy, czy osobisty, za pomocą widżetu SelectionInput korzystającego z przycisków:

Przykład 3: przełączniki

Poniżej wyświetla się okno z prośbą o podanie przez użytkownika, czy kontakt jest zawodowy, czy osobisty, za pomocą widżetu SelectionInput, który korzysta z przełączników:

Poniżej widać okno z prośbą o podanie przez użytkownika, czy kontakt ma charakter zawodowy czy osobisty, za pomocą widżetu SelectionInput, który korzysta z menu:

Przykład 5: menu wielokrotnego wyboru

Poniżej widać okno z prośbą o wybranie kontaktów z menu wielokrotnego wyboru:

Dodatkowe źródła danych dla menu wyboru wielokrotnego

Z tej sekcji dowiesz się, jak używać menu wielokrotnego wyboru do wypełniania danych ze źródeł dynamicznych, takich jak aplikacja Google Workspace czy zewnętrzne źródło danych.

Źródła danych z Google Workspace

Elementy w przypadku menu wielokrotnego wyboru możesz wypełniać z tych źródeł danych w Google Workspace:

  • Użytkownicy Google Workspace: możesz zapełniać dane tylko użytkownikami z tej samej organizacji Google Workspace.
  • Pokoje czatu: użytkownik klikający elementy w menu wielokrotnego wyboru może tylko wyświetlać i wybierać pokoje, które należą do swojej organizacji Google Workspace.

Aby używać źródeł danych Google Workspace, musisz określić pole platformDataSource. W przeciwieństwie do innych typów danych wejściowych wyboru pomijasz obiekty SectionItem, ponieważ te elementy wyboru są pobierane dynamicznie z Google Workspace.

Poniższy kod przedstawia menu wielokrotnego wyboru użytkowników Google Workspace. Aby użytkownicy mogli być dodawani do listy, wartość w polu wyboru powoduje ustawienie commonDataSource na USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Poniższy kod przedstawia menu wielokrotnego wyboru pokoi czatu. Aby wypełniać spacje, wybrana wartość określa pole hostAppDataSource. Menu wyboru wielokrotnego ustawia też defaultToCurrentSpace na true, przez co bieżący pokój jest domyślnym wyborem w menu:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
Źródła danych spoza Google Workspace

Menu wielokrotnego wyboru mogą też zawierać elementy z zewnętrznego lub zewnętrznego źródła danych. Możesz na przykład użyć menu wielokrotnego wyboru, aby ułatwić użytkownikowi wybranie potencjalnych klientów z listy potencjalnych klientów z systemu zarządzania relacjami z klientami (CRM).

Jeśli chcesz użyć zewnętrznego źródła danych, użyj pola externalDataSource do określenia funkcji, która zwraca elementy ze źródła danych.

Aby ograniczyć liczbę żądań kierowanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu wielokrotnego wyboru, zanim użytkownicy zaczną w nim wpisywać tekst. Możesz na przykład uzupełnić ostatnio wyszukiwane kontakty danego użytkownika. Aby wypełniać sugerowane elementy z zewnętrznego źródła danych, określ obiekty SelectionItem.

Poniższy kod przedstawia menu wielokrotnego wyboru elementów z zewnętrznego zestawu kontaktów użytkownika. W menu domyślnie wyświetlany jest 1 kontakt oraz uruchamia się funkcja getContacts, która pozwala pobrać i wypełnić elementy z zewnętrznego źródła danych:

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
      }
    ]
  }
}

W przypadku zewnętrznych źródeł danych możesz też włączyć autouzupełnianie elementów, które użytkownicy zaczynają wpisywać w menu wyboru wielokrotnego. Jeśli na przykład użytkownik zacznie wpisywać Atl, aby wyświetlić menu z miastami w Stanach Zjednoczonych, aplikacja Google Chat może automatycznie zasugerować wartość Atlanta, zanim użytkownik skończy pisać. Możesz automatycznie uzupełnić maksymalnie 100 elementów.

Aby korzystać z autouzupełniania elementów, tworzysz funkcję, która wysyła zapytanie do zewnętrznego źródła danych i zwraca elementy za każdym razem, gdy użytkownik wpisuje zapytanie w menu wyboru wielokrotnego. Ta funkcja musi wykonywać te działania:

  • Przekaż obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
  • Sprawdź, czy wartość invokedFunction zdarzenia interakcji odpowiada funkcji z pola externalDataSource.
  • Gdy funkcje do siebie pasują, zwracaj sugerowane elementy z zewnętrznego źródła danych. Aby proponować elementy na podstawie typu użytkownika, pobierz wartość klucza autocomplete_widget_query. Ta wartość odzwierciedla to, co użytkownik wpisuje w menu.

Poniższy kod automatycznie uzupełnia elementy z zewnętrznego zasobu danych. W poprzednim przykładzie aplikacja do obsługi czatu sugeruje elementy na podstawie tego, kiedy zostanie wywołana funkcja getContacts:

Google 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
            },
          ]
        }
      }
    }
  };
}

Reprezentacja i pola w formacie JSON

Zapis 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.
}
Pola
name

string

Nazwa, która określa dane wejściowe wyboru w zdarzeniu wprowadzania danych.

Szczegółowe informacje o pracy z danymi wejściowymi do formularzy znajdziesz w artykule Odbieranie danych z formularzy.

label

string

Tekst wyświetlany w interfejsie nad polem do wprowadzania wyboru.

Wpisz tekst, który pomoże użytkownikowi wpisać informacje, których potrzebuje aplikacja. Jeśli na przykład użytkownicy wybierają z menu pilność zgłoszenia, etykieta może mieć wartość „Pilne” lub „Wybierz pilność”.

type

enum (SelectionType)

Typ elementów wyświetlanych użytkownikom w widżecie SelectionInput. Typy wybranych elementów obsługują różne typy interakcji. Na przykład użytkownicy mogą zaznaczyć jedno lub więcej pól wyboru, ale tylko jedną wartość w menu.

items[]

object (SelectionItem)

Tablica elementów do wyboru. Może to być na przykład tablica przycisków lub pól wyboru. Obsługuje do 100 elementów.

onChangeAction

object (Action)

Jeśli określisz wartość, formularz zostanie przesłany po zmianie wyboru. Jeśli go nie podasz, musisz określić osobny przycisk służący do przesyłania formularza.

Szczegółowe informacje o pracy z danymi wejściowymi do formularzy znajdziesz w artykule Odbieranie danych z formularzy.

multiSelectMaxSelectedItems

integer

W przypadku menu wielokrotnego wyboru jest to maksymalna liczba elementów, które użytkownik może wybrać. Minimalna wartość to 1 element. Jeśli wartość nie zostanie określona, przyjmuje się domyślnie 3 elementy.

multiSelectMinQueryLength

integer

W przypadku menu wyboru wielokrotnego liczba znaków tekstowych wpisywanych przez użytkownika przed wysłaniem zapytań do aplikacji Google Chat jest automatycznie uzupełniana i wyświetlana w menu jest sugerowane elementy.

Jeśli wartość nie zostanie określona, przyjmuje domyślnie wartość 0 znaków w przypadku statycznych źródeł danych i 3 znaki dla zewnętrznych źródeł danych.

Pole sumy multi_select_data_source. Tylko komunikatory. W przypadku menu wielokrotnego wyboru źródło danych wypełnia elementy wyboru. multi_select_data_source może mieć tylko jeden z tych parametrów:
externalDataSource

object (Action)

Zewnętrzne źródło danych, np. relacyjna baza danych.

platformDataSource

object (PlatformDataSource)

Źródło danych z Google Workspace.

SelectionType

Wartości w polu enum
CHECK_BOX Zestaw pól wyboru. Użytkownicy mogą zaznaczyć jedno lub więcej pól wyboru.
RADIO_BUTTON Zestaw przycisków. Użytkownicy mogą wybrać jeden przycisk.
SWITCH Zestaw przełączników. Użytkownicy mogą włączyć jeden lub więcej przełączników.
DROPDOWN Menu. Użytkownicy mogą wybrać 1 element z menu.
MULTI_SELECT

Są obsługiwane przez aplikacje do obsługi czatu, ale nie przez dodatki do Google Workspace.

Menu wielokrotnego wyboru na potrzeby danych statycznych lub dynamicznych. Na pasku menu użytkownicy wybierają co najmniej 1 element. Użytkownicy mogą też wpisywać wartości, aby wypełnić dane dynamiczne. Użytkownicy mogą na przykład zacząć wpisywać nazwę pokoju w Google Chat, a widżet automatycznie ją podsunie.

Aby wypełniać elementy w przypadku menu wielokrotnego wyboru, możesz użyć jednego z tych typów źródeł danych:

  • Dane statyczne: elementy są określane w widżecie jako obiekty SelectionItem. Maksymalnie 100 elementów.
  • Dane Google Workspace: elementy są wypełniane na podstawie danych z Google Workspace, np. użytkowników Google Workspace czy pokoi Google Chat.
  • Dane zewnętrzne: elementy są pobierane z zewnętrznego źródła danych spoza Google Workspace.

Przykłady implementacji menu wyboru wielokrotnego znajdziesz na stronie widżetu SelectionInput .

SelectionItem

Zapis JSON
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
Pola
text

string

Tekst, który identyfikuje lub opisuje produkt użytkownikom.

value

string

Wartość powiązana z tym elementem. Klient powinien go użyć jako wartości wejściowej formularza.

Szczegółowe informacje o pracy z danymi wejściowymi do formularzy znajdziesz w artykule Odbieranie danych z formularzy.

selected

boolean

Określa, czy element jest wybrany domyślnie. Jeśli w danych wejściowych można wybrać tylko jedną wartość (np. przycisk opcji lub menu), ustaw to pole tylko dla jednego elementu.

startIconUri

string

W przypadku menu wyboru wielokrotnego jest to adres URL ikony wyświetlanej obok pola text elementu. Obsługuje pliki PNG i JPEG. Musi to być adres URL HTTPS. Na przykład: https://developers.google.com/chat/images/quickstart-app-avatar.png.

bottomText

string

W przypadku menu wielokrotnego wyboru jest to opis tekstowy lub etykieta wyświetlana pod polem text elementu.

Działanie

Działanie opisujące zachowanie po przesłaniu formularza. Możesz na przykład wywołać skrypt Apps Script do obsługi formularza. W przypadku uruchomienia działania wartości formularza są wysyłane na serwer.

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

string

Funkcja niestandardowa do wywołania po kliknięciu lub niewłaściwym aktywowaniu elementu zawierającego ten element.

Przykład wykorzystania znajdziesz w artykule o tworzeniu kart interaktywnych.

parameters[]

object (ActionParameter)

Lista parametrów działań.

loadIndicator

enum (LoadIndicator)

Określa wskaźnik wczytywania, który wyświetla się podczas wysyłania wezwania do działania.

persistValues

boolean

Wskazuje, czy wartości formularza pozostają po wykonaniu czynności. Wartością domyślną jest false.

Jeśli true, wartości formularza pozostają po wywołaniu działania. Aby umożliwić użytkownikowi wprowadzanie zmian podczas przetwarzania działania, ustaw LoadIndicator na NONE. W przypadku wiadomości z kartami w aplikacjach do obsługi czatu musisz też ustawić wartość ResponseType działania na UPDATE_MESSAGE i użyć tej samej wartości cardId co karta zawierająca działanie.

Jeśli false, wartości formularza są czyszczone po uruchomieniu działania. Aby uniemożliwić użytkownikowi wprowadzanie zmian podczas przetwarzania działania, ustaw LoadIndicator na SPINNER.

interaction

enum (Interaction)

Opcjonalnie. Wymagane przy otwieraniu okna.

Co zrobić w odpowiedzi na interakcję z użytkownikiem, np. kliknięcie przez niego przycisku w wiadomości na karcie.

Jeśli nie określono inaczej, aplikacja reaguje, wykonując action w zwykły sposób, np. otwierając link lub uruchamiając funkcję.

Dzięki określeniu interaction aplikacja może reagować w specjalny interaktywny sposób. Jeśli na przykład ustawisz w interaction wartość OPEN_DIALOG, aplikacja będzie mogła otworzyć okno. Jeśli podasz wartość, wskaźnik wczytywania się nie wyświetli.

Są obsługiwane przez aplikacje do obsługi czatu, ale nie przez dodatki do Google Workspace. Jeśli określisz dodatek, zostanie ona usunięta z całej karty i klient nie będzie niczego wyświetlać.

ActionParameter

Lista parametrów ciągu znaków, które należy podać po wywołaniu metody działania. Rozważmy na przykład trzy przyciski drzemki: „Drzemka”, „Odłóż jeden dzień” i „Drzemka” w przyszłym tygodniu. Możesz użyć właściwości action method = snooze(), która przekazuje typ drzemki i czas drzemki na liście parametrów ciągu znaków.

Więcej informacji: CommonEventObject.

Zapis JSON
{
  "key": string,
  "value": string
}
Pola
key

string

Nazwa parametru skryptu działania.

value

string

Wartość parametru.

LoadIndicator

Określa wskaźnik wczytywania, który wyświetla się podczas wysyłania wezwania do działania.

Wartości w polu enum
SPINNER Ikona wczytywania oznacza, że zawartość się wczytuje.
NONE Nic nie jest wyświetlane.

Interakcja

Opcjonalnie. Wymagane przy otwieraniu okna.

Co zrobić w odpowiedzi na interakcję z użytkownikiem, np. kliknięcie przez niego przycisku w wiadomości na karcie.

Jeśli nie określono inaczej, aplikacja reaguje, wykonując action w zwykły sposób, np. otwierając link lub uruchamiając funkcję.

Dzięki określeniu interaction aplikacja może reagować w specjalny interaktywny sposób. Jeśli na przykład ustawisz w interaction wartość OPEN_DIALOG, aplikacja będzie mogła otworzyć okno.

Jeśli podasz wartość, wskaźnik wczytywania się nie wyświetli.

Są obsługiwane przez aplikacje do obsługi czatu, ale nie przez dodatki do Google Workspace. Jeśli określisz dodatek, zostanie ona usunięta z całej karty i klient nie będzie niczego wyświetlać.

Wartości w polu enum
INTERACTION_UNSPECIFIED Wartość domyślna. action działa w zwykły sposób.
OPEN_DIALOG

Otwiera okno, czyli okno interfejsu z kartami, za pomocą którego aplikacje Google Chat mogą komunikować się z użytkownikami.

Obsługiwane tylko przez aplikacje do obsługi czatu w odpowiedzi na kliknięcia przycisków w wiadomościach kart.

Nieobsługiwane przez dodatki do Google Workspace. Jeśli określisz dodatek, zostanie ona usunięta z całej karty i klient nie będzie niczego wyświetlać.

Rozwiązywanie problemów

Gdy aplikacja lub karta Google Chat zwróci błąd, w interfejsie czatu pojawi się komunikat „Coś poszło nie tak” lub „Nie udało się przetworzyć Twojego żądania”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat mogą dać nieoczekiwany wynik, na przykład komunikat na karcie.

Mimo że komunikat o błędzie może nie wyświetlić się w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci naprawić błędy występujące po włączeniu rejestrowania błędów w aplikacjach do obsługi czatu. Więcej informacji o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i rozwiązywanie problemów.