Na tej stronie wyjaśniamy, jak dodawać widżety i elementy interfejsu do kart, aby użytkownicy mogli wchodzić w interakcje z Twoją aplikacją Google Chat, np. klikać przyciski lub przesyłać informacje.
Aplikacje do obsługi czatu mogą tworzyć karty interaktywne za pomocą tych interfejsów Google Chat:
- 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 będą wchodzić w interakcję z kartami, aplikacje czatu mogą używać otrzymanych danych do przetwarzania i odpowiedniego reagowania. Więcej informacji znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników Google Chat.
Za pomocą kreatora kart możesz zaprojektować i wyświetlić podgląd komunikatów oraz interfejsów użytkownika aplikacji do obsługi czatu:
Otwórz kreatora kartWymagania wstępne
Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację czatu, 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 z adresem
OpenLink
, aby udostępnić użytkownikom dodatkowe informacje. - Uruchom
action
funkcję niestandardową, która wykonuje funkcję niestandardową, np. wywołuje interfejs API.
W celu ułatwienia dostępu przyciski obsługują tekst alternatywny.
Dodawanie przycisku, który uruchamia funkcję niestandardową
Poniżej znajduje się karta zawierająca widżet ButtonList
z 2 przyciskami.
Jeden przycisk otwiera dokumentację dla deweloperów Google Chat w nowej karcie. Drugi przycisk uruchamia funkcję niestandardową o nazwie goToView()
i przekazuje parametr viewType="BIRD EYE VIEW"
.
Dodaj przycisk w stylu Material Design
Poniżej znajdziesz zestaw przycisków w różnych stylach Material Design.
Aby zastosować styl Material Design, nie podawaj atrybutu „kolor”.
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 dostosowywania koloru tła przycisku. Drugi przycisk jest dezaktywowany w polu 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ć wbudowaną ikonę poczty e-mail Google Chat. Drugi przycisk używa pola iconUrl
do wyświetlania widżetu niestandardowej ikony.
Dodawanie przycisku z ikoną i tekstem
Na poniższym obrazku widać kartę z widżetem ButtonList
, który prosi użytkownika o wysłanie e-maila. Pierwszy to ikona e-maila,
a drugi tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby uruchomić funkcję sendEmail
.
Dostosowywanie przycisku do sekcji zwijanej
Dostosuj przycisk sterujący, który składa i rozwija sekcje na karcie. Wybierz jedną z dostępnych 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żna używać na kartach czatu, aby oferować dodatkowe opcje i działania. Umożliwia dodanie większej liczby opcji bez zaśmiecania interfejsu karty, co zapewnia przejrzysty i uporządkowany układ.
Dodaj listę chipsów
Widget ChipList
umożliwia wszechstronne i atrakcyjne wizualnie wyświetlanie informacji.
Używaj list elementów, aby reprezentować tagi, kategorie lub inne istotne dane, dzięki czemu użytkownicy łatwiej będą mogli się poruszać po Twoich treściach i z nimi wchodzić w interakcje.
Zbieranie informacji o użytkownikach
W tej sekcji wyjaśniamy, jak dodawać widżety zbierające informacje, np. tekst lub wybrane elementy.
Aby dowiedzieć się, jak przetwarzać dane wprowadzane przez użytkowników, przeczytaj artykuł Zbieranie i przetwarzanie informacji o użytkownikach 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. gdy użytkownik dodaje lub usuwa tekst.
Jeśli chcesz zbierać od użytkowników dane abstrakcyjne lub nieznane, użyj tego widgeta TextInput
. Aby zbierać od użytkowników określone dane, użyj zamiast tego widgetu SelectionInput
.
Poniżej znajduje się karta zawierająca widżet TextInput
:
Zbieranie dat lub 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 wpisanie informacji.
Poniżej widać kartę składającą się z 3 rodzajów widżetów:DateTimePicker
Pozwalanie użytkownikom na wybór 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ć nieokreślone dane od użytkowników, użyj zamiast tego widgetu 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ść wybranych elementów. Szczegółowe informacje o pracy z danymi wprowadzanymi 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:
Dodaj pole wyboru
Poniżej widać kartę, która prosi użytkownika o wskazanie, czy kontakt jest służbowy, prywatny czy oba, z użyciem widżetu SelectionInput
z polami wyboru:
Dodaj opcję
Poniżej znajduje się karta z prośbą o wskazanie, czy kontakt jest służbowy czy osobisty, w widżecie SelectionInput
z przyciskami wyboru:
Dodawanie przełącznika
Poniżej znajduje się karta, która prosi użytkownika o wskazanie, czy kontakt jest służbowy, prywatny czy oba, za pomocą widżetu SelectionInput
, który wykorzystuje przełączniki:
Dodawanie menu
Na poniższym obrazku widać kartę, która prosi użytkownika o wskazanie, czy kontakt jest służbowy czy prywatny, za pomocą widżetu SelectionInput
, który wykorzystuje menu:
Dodawanie menu wyboru wielu elementów
Poniżej znajduje się karta z prośbą 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ć dane tylko o użytkownikach 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, określ pole platformDataSource
. W przeciwieństwie do innych typów danych wyboru pomijasz obiekty SectionItem
, ponieważ te elementy wyboru są dynamicznie pobierane z Google Workspace.
Poniższy kod przedstawia menu wielokrotnego wyboru z użytkownikami 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 można było wstawić spacje, pole wyboru określa pole hostAppDataSource
. Menu wybierania wielu elementów ustawia też parametr 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 np. użyć menu wielokrotnego wyboru, 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, w polu externalDataSource
określ funkcję, która zwraca elementy ze źródła danych.
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 wielokrotnego wyboru, zanim użytkownicy zaczną wpisywać w nim tekst. Możesz na przykład wypełnić ostatnio wyszukiwane kontakty użytkownika. Aby wypełnić sugerowane produkty z zewnętrznego źródła danych, określ obiekty SelectionItem
.
Poniższy kod pokazuje menu wielokrotnego wyboru z elementami z zewnętrznego zbioru 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 wyboru wielokrotnego. 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 użyć autouzupełniania 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ść odzwierciedla to, co użytkownik wpisuje w menu.
Ten kod automatycznie uzupełnia elementy z zewnętrznego zasobu 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 dowiesz się, jak weryfikować dane wprowadzone na karcie action
i w widżetach.
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 sekcji action
na karcie dodaj do listy requiredWidgets
nazwy widżetów, których działanie wymaga.
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.
Gdy dla działania ustawiona jest wartość "all_widgets_are_required": "true"
, wszystkie widżety na karcie są wymagane do wykonania tego działania.
Ustawianie działania all_widgets_are_required
w elemencie typu „wieloznaczny wybór”
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
}
]
}
}
]
}
]
}
Ustawianie działania all_widgets_are_required
w elemencie 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
}
]
}
}
]
}
]
}
Ustawianie weryfikacji widżetu do wprowadzania tekstu
W polu weryfikacji 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 lub karta czatu powoduje nieoczekiwany wynik, na przykład wiadomość na karcie może się nie wyświetlić.
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ć. Aby dowiedzieć się, jak wyświetlać, debugować i naprawiać błędy, przeczytaj artykuł Rozwiązywanie problemów z błędami Google Chat.