Na tej stronie wyjaśniamy, jak dodawać widżety i elementy interfejsu użytkownika do kart, aby użytkownicy mogli wchodzić w interakcje z Twoją aplikacją Google Chat, np. klikać przyciski lub przesyłać informacje.
Aplikacje czatu mogą używać tych interfejsów czatu do tworzenia interaktywnych kart:
- Wiadomości zawierające co najmniej 1 kartę.
- Strony główne – karta, która pojawia się na karcie Strona główna w wiadomościach bezpośrednich w aplikacji Google Chat.
- Dialogi, czyli karty otwierane w nowym oknie z wiadomości i stron głównych.
Gdy użytkownicy korzystają z kart, aplikacje do czatu mogą używać otrzymanych danych do przetwarzania i odpowiedniego reagowania. Szczegółowe informacje znajdziesz w artykule Zbieranie i przetwarzanie informacji o użytkownikach Google Chat.
Korzystając z Kreatora kart, możesz projektować i przeglądać interfejsy użytkownika oraz wiadomości w aplikacji Google Chat:
Otwórz kreatora kartWymagania wstępne
Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat, wykonaj jeden z tych samouczków w zależności od architektury aplikacji, której chcesz użyć:
- Usługa HTTP w Google Cloud Functions
- Google Apps Script
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
Dodawanie przycisku
Widżet ButtonList
zawiera zestaw przycisków. Przyciski mogą zawierać tekst, ikonę lub tekst i ikonę. Każdy przycisk Button
obsługuje działanie OnClick
, które następuje po kliknięciu przycisku przez użytkownika. Na przykład:
- Otwórz hiperlink za pomocą
OpenLink
, aby przekazać użytkownikom dodatkowe informacje. - Uruchom
action
, który wykonuje funkcję niestandardową, np. wywołanie interfejsu API.
W celu ułatwienia dostępu przyciski obsługują tekst alternatywny.
Dodawanie przycisku, który uruchamia funkcję niestandardową
Poniżej znajduje się karta z widżetem ButtonList
i 2 przyciskami.
Jeden przycisk otwiera dokumentację Google Chat dla deweloperów w nowej karcie. Drugi przycisk uruchamia funkcję niestandardową o nazwie goToView()
i przekazuje parametr viewType="BIRD EYE VIEW"
.
Dodawanie przycisku w stylu Material Design
Poniżej widać zestaw przycisków w różnych stylach Material Design.
Aby zastosować styl Material Design, nie dodawaj atrybutu „color”.
Dodawanie przycisku z niestandardowym kolorem i dezaktywowanym przyciskiem
Możesz uniemożliwić użytkownikom klikanie przycisku, ustawiając wartość "disabled": "true"
.
Poniżej widać kartę z widżetem ButtonList
i 2 przyciskami. Jeden przycisk używa pola Color
do dostosowania koloru tła przycisku. Drugi przycisk jest dezaktywowany za pomocą pola Disabled
, co uniemożliwia użytkownikowi kliknięcie przycisku i wykonanie funkcji.
Dodawanie przycisku z ikoną
Na poniższym obrazku widać kartę składającą się z widżetu ButtonList
z 2 widżetami ikony Button
. Jeden przycisk używa pola knownIcon
, aby wyświetlić ikonę poczty e-mail wbudowanej w Google Chat. Drugi przycisk używa pola iconUrl
do wyświetlania niestandardowego widżetu ikony.
Dodawanie przycisku z ikoną i tekstem
Na poniższym zrzucie ekranu widać kartę z widżetem ButtonList
, który prosi użytkownika o wysłanie e-maila. Pierwszy przycisk ma ikonę e-maila, a drugi – tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby uruchomić funkcję sendEmail
.
Dostosowywanie przycisku sekcji z możliwością zwijania
Dostosuj przycisk sterujący, który zwija i rozwija sekcje na karcie. Wybierz spośród wielu ikon lub obrazów, aby wizualnie przedstawić zawartość sekcji. Dzięki temu użytkownicy łatwiej zrozumieją informacje i będą mogli z nimi wchodzić w interakcje.
Dodawanie rozszerzonego menu
Overflow menu
może być używany na kartach czatu, aby oferować dodatkowe opcje i działania. Dzięki temu możesz uwzględnić więcej opcji bez zaśmiecania interfejsu karty, co zapewnia przejrzysty i uporządkowany wygląd.
Dodawanie listy elementów
Widget ChipList
zapewnia wszechstronny i atrakcyjny wizualnie sposób wyświetlania informacji.
Używaj list elementów, aby reprezentować tagi, kategorie lub inne istotne dane, ułatwiając użytkownikom poruszanie się po treściach i interakcję z nimi.
Zbieranie informacji o użytkownikach
W tej sekcji dowiesz się, jak dodawać widżety, które zbierają informacje, takie jak tekst lub zaznaczenia.
Aby dowiedzieć się, jak przetwarzać dane wprowadzane przez użytkowników, przeczytaj artykuł Zbieranie i przetwarzanie informacji od użytkowników Google Chat.
Zbieranie tekstu
Widget TextInput
zawiera pole, w którym użytkownicy mogą wpisywać tekst. Widget obsługuje sugestie, które pomagają użytkownikom wprowadzać jednolite dane, oraz działania wykonywane po zmianie, które są Actions
uruchamiane po zmianie w polu tekstowym, np. po dodaniu lub usunięciu tekstu przez użytkownika.
Jeśli chcesz zbierać od użytkowników dane abstrakcyjne lub nieznane, użyj tego widgeta TextInput
. Aby zbierać określone dane od użytkowników, użyj zamiast tego widżetu SelectionInput
.
Poniżej znajduje się karta zawierająca widżet TextInput
:
Zbieranie dat i godzin
Widżet DateTimePicker
pozwala użytkownikom wpisać datę, godzinę lub równocześnie datę i godzinę. Użytkownicy mogą też wybrać datę i godzinę za pomocą selektora. Jeśli użytkownicy wpiszą nieprawidłową datę lub godzinę, selektor wyświetli błąd z prośbą o poprawne wprowadzenie informacji.
Poniżej widać kartę składającą się z 3 rodzajów widżetów:DateTimePicker
Pozwalanie użytkownikom na wybieranie elementów
Widget SelectionInput
zawiera zestaw elementów do wyboru, takich jak pola wyboru, przyciski opcji, przełączniki lub menu. Za pomocą tego widżetu możesz zbierać zdefiniowane i ujednolicone dane od użytkowników. Aby zbierać z użytkowników dane o nieokreślonym charakterze, użyj zamiast tego widżetu TextInput
.
Widget SelectionInput
obsługuje sugestie, które pomagają użytkownikom wprowadzać ujednolicone dane, oraz działania wykonywane po zmianie, które są Actions
uruchamiane po zmianie w polu wyboru, np. gdy użytkownik wybierze lub odznaczy element.
Aplikacje do obsługi czatu mogą otrzymywać i przetwarzać wartości wybranych elementów. Szczegółowe informacje o obsługiwaniu danych wprowadzanych przez użytkowników znajdziesz w artykule Przetwarzanie informacji wprowadzanych przez użytkowników.
Ta sekcja zawiera przykłady kart, które korzystają z widżetu SelectionInput
.
Przykłady wykorzystują różne typy danych wejściowych sekcji:
Dodawanie pola wyboru
Na karcie wyświetla się prośba o wskazanie, czy kontakt jest służbowy, prywatny czy oba, za pomocą widżetu SelectionInput
z pola wyboru:
Dodawanie przycisku opcji
Na karcie wyświetla się widget SelectionInput
z przyciskami opcji, który prosi użytkownika o wskazanie, czy kontakt jest służbowy czy prywatny:
Dodawanie przełącznika
Na karcie wyświetla się widget SelectionInput
z przełącznikami, który prosi użytkownika o wskazanie, czy kontakt jest służbowy, prywatny czy oba:
Dodawanie menu
Na karcie wyświetla się widget SelectionInput
z menu, w którym użytkownik może określić, czy kontakt jest służbowy czy prywatny:
Dodawanie menu wyboru wielu elementów
Poniżej widać kartę, która prosi użytkownika o wybranie kontaktów z menu wielokrotnego wyboru:
Elementy menu z wieloma opcjami możesz wypełniać z tych źródeł danych w Google Workspace:
- Użytkownicy Google Workspace: możesz wypełniać listę tylko użytkownikami z tej samej organizacji Google Workspace.
- Pokoje czatu: użytkownik wpisujący elementy w menu wielokrotnego wyboru może wyświetlać i wybierać tylko te pokoje, do których należy w organizacji Google Workspace.
Aby używać źródeł danych Google Workspace, musisz podać pole platformDataSource
. W przeciwieństwie do innych typów danych wyboru pomijasz obiekty SelectionItem
, ponieważ te elementy wyboru są dynamicznie pobierane z Google Workspace.
Podany niżej kod pokazuje menu z wieloma zaznaczeniami użytkowników Google Workspace.
Aby wypełnić listę użytkowników, dane wejściowe wyboru ustawiają commonDataSource
na USER
:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Poniższy kod pokazuje menu z wieloma opcjami wyboru w ChatSpaces. Aby wypełnić pola, pole wyboru określa pole hostAppDataSource
. Menu wybierania wielu elementów ustawia też opcję defaultToCurrentSpace
na true
, co powoduje, że bieżący pokój jest domyślnie wybrany w menu:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Menu z wieloma opcjami mogą też wypełniać elementy z zewnętrznego źródła danych lub źródła danych firmy zewnętrznej. Możesz na przykład użyć menu z wieloma opcjami, aby ułatwić użytkownikowi wybór z listy potencjalnych klientów w systemie do zarządzania relacjami z klientami (CRM).
Aby użyć zewnętrznego źródła danych, użyj pola externalDataSource
, aby określić funkcję zwracającą elementy z tego źródła.
Aby ograniczyć liczbę żądań wysyłanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu wyboru wielokrotnego, zanim użytkownicy zaczną wpisywać w nim tekst. Możesz na przykład wypełnić kontakty ostatnio wyszukiwane przez użytkownika. Aby wypełnić sugerowane produkty z zewnętrznego źródła danych, określ obiekty SelectionItem
.
Ten kod pokazuje menu z opcją wielokrotnego wybierania elementów z zewnętrznego zestawu kontaktów użytkownika. Menu wyświetla domyślnie 1 kontakt i uruchamia funkcję getContacts
, aby pobrać i wypełnić elementy ze źródła danych zewnętrznych:
Node.js
Python
Java
Google Apps Script
W przypadku zewnętrznych źródeł danych możesz też automatycznie uzupełniać elementy, które użytkownicy zaczynają wpisywać w menu wielokrotnego wyboru. Jeśli na przykład użytkownik zacznie wpisywać Atl
w menu, które wyświetla miasta w Stanach Zjednoczonych, aplikacja Google Chat może automatycznie zaproponować Atlanta
, zanim użytkownik skończy pisać. Możesz automatycznie wypełnić maksymalnie 100 elementów.
Aby automatycznie uzupełniać elementy, utwórz funkcję, która wysyła zapytanie do zewnętrznego źródła danych i zwraca elementy, gdy użytkownik wpisze coś w menu wielokrotnego wyboru. Funkcja musi:
- Przekaż obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
- Sprawdź, czy wartość zdarzenia interakcji
invokedFunction
odpowiada funkcji z polaexternalDataSource
. - Gdy funkcje się zgadzają, zwracają sugerowane elementy ze źródła danych zewnętrznych. Aby sugerować produkty na podstawie tego, co wpisze użytkownik, pobierz wartość klucza
autocomplete_widget_query
. Ta wartość odpowiada temu, co użytkownik wpisze w menu.
Poniższy kod automatycznie uzupełnia elementy z zewnętrznego źródła danych. W przypadku poprzedniego przykładu aplikacja Google Chat sugeruje elementy na podstawie tego, kiedy uruchamia się funkcja getContacts
:
Node.js
Python
Java
Google Apps Script
Sprawdzanie danych wprowadzanych na karty
Na tej stronie wyjaśniamy, jak weryfikować dane wprowadzone do action
karty i widżetów.
Możesz na przykład sprawdzić, czy pole tekstowe zawiera tekst wpisany przez użytkownika lub czy zawiera określoną liczbę znaków.
Ustawianie wymaganych widżetów do działań
W ramach action
karty dodaj do listy requiredWidgets
nazwy widżetów, których potrzebuje działanie.
Jeśli po wywołaniu tego działania którykolwiek z wymienionych tu widżetów nie ma wartości, przesłanie działania formularza zostanie anulowane.
Jeśli dla działania ustawiona jest wartość "all_widgets_are_required": "true"
, oznacza to, że działanie wymaga wszystkich widżetów na karcie.
Ustawianie działania all_widgets_are_required
w elemencie typu „wielokryterialny”
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
}
]
}
}
]
}
]
}
Ustaw działanie all_widgets_are_required
w elementach 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"
}
}
]
}
]
}
Ustaw działanie all_widgets_are_required
w menu
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
}
]
}
}
]
}
]
}
Konfigurowanie weryfikacji w widżecie wprowadzania tekstu
W polu walidacji widgetu textInput
możesz określić limit znaków i typ danych dla tego widgetu wprowadzania tekstu.
Ustawianie limitu znaków w widżecie wprowadzania tekstu
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
}
}
}
]
}
]
}
Ustawianie typu danych w widżecie wprowadzania tekstu
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"
}
}
}
]
}
]
}
Rozwiązywanie problemów
Gdy aplikacja Google Chat lub karta zwraca błąd, interfejs Google Chat wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs czatu nie wyświetla żadnego komunikatu o błędzie, ale aplikacja Google Chat lub karta daje nieoczekiwany wynik. Na przykład może nie wyświetlić się wiadomość na karcie.
Komunikat o błędzie może się nie wyświetlać w interfejsie czatu, ale gdy włączone jest rejestrowanie błędów w przypadku aplikacji czatu, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci je naprawić. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami Google Chat.