Na tej stronie znajdziesz informacje o tym, jak dodawać widżety i elementy interfejsu do kart, aby użytkownicy mogli wchodzić w interakcje z aplikacją Google Chat, na przykład klikając przycisk lub przesyłając informacje.
Aplikacje czatu mogą używać tych interfejsów Google Chat 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 będą wchodzić w interakcję z kartami, aplikacje czatu mogą używać otrzymanych danych do przetwarzania i odpowiedniego reagowania. Szczegółowe informacje znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników Google Chat.
Za pomocą Kreatora kart możesz projektować i przeglądać podglądy wiadomości oraz interfejsów aplikacji 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 oba te elementy. 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
OpenLink
, aby przekazać 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 składająca się z widżetu ButtonList
z 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 znajdziesz 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 dostosowywania 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ą
Poniżej 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 niestandardowego widżetu 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 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 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. 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
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 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 o użytkownikach Google Chat.
Zbieranie tekstu
Widget TextInput
udostępnia 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 widgetó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ć jednolite 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 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:
Dodawanie pola wyboru
Poniżej widać kartę, która prosi użytkownika o wskazanie, czy kontakt jest służbowy, prywatny czy oba, za pomocą widżetu SelectionInput
z polami 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
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 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ć dane tylko dla użytkowników w 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 wejściowych w przypadku obiektów SelectionItem
nie musisz ich pomijać, ponieważ te elementy są dynamicznie pobierane z Google Workspace.
Podany niżej kod pokazuje menu z wieloma zaznaczonymi użytkownikami Google Workspace.
Aby wypełnić listę użytkowników, ustawienia 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ż 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 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, w polu externalDataSource
podaj funkcję, która zwraca 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, podaj obiekty SelectionItem
.
Poniższy kod pokazuje menu z wieloznacznikiem 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 uzupełnić maksymalnie 100 elementów.
Aby wypełniać pola automatycznie, 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 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 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
}
]
}
}
]
}
]
}
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 przypadku widżetu pola tekstowego
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.