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 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 wyświetlana na karcie Strona główna w czatach 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 zaprojektować i wyświetlić podgląd komunikatów oraz interfejsów użytkownika aplikacji do obsługi czatu:
Otwórz Kreator 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 z Google Cloud Functions.
- Google Apps Script
- Google Cloud Dialogflow CX,
- Google Cloud Pub/Sub
Dodawanie przycisku
Widżet ButtonList
wyświetla zestaw przycisków. Na przyciskach może być tekst, ikona lub zarówno tekst, jak i ikona. 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
, który uruchamia 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 składająca się z widżetu 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"
.
Dodawanie przycisku 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
Aby uniemożliwić użytkownikom klikanie przycisków, skonfiguruj "disabled": "true"
.
Poniżej wyświetli się karta składająca się z widżetu ButtonList
z 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ą
Poniżej wyświetli się karta składająca się z widżetu ButtonList
z 2 widżetami ikon Button
. Jeden z przycisków wyświetla ikonę wbudowanej poczty e-mail w Google Chat za pomocą pola knownIcon
. Drugi przycisk korzysta z pola iconUrl
do wyświetlania niestandardowego widżetu z ikoną.
Dodawanie przycisku z ikoną i tekstem
Poniżej wyświetli się karta zawierająca widżet ButtonList
, który zachęca użytkownika do wysłania 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że być używany na kartach czatu, aby udostępniać 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 projekt.
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 od użytkowników
W tej sekcji wyjaśniamy, jak dodawać widżety zbierające informacje, np. tekst lub wybrane elementy.
Aby dowiedzieć się, jak przetwarzać informacje wprowadzone 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. Widżet obsługuje sugestie, które ułatwiają użytkownikom wpisywanie jednolitych danych, oraz działania Actions
wykonywane po wprowadzeniu zmiany w polu do wprowadzania tekstu, np. gdy użytkownik doda lub usunie 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 zarówno datę, jak i godzinę. Użytkownicy mogą też wybierać daty i godziny za pomocą selektora. Jeśli użytkownicy wpiszą nieprawidłową datę lub godzinę, selektor wyświetli błąd z prośbą o prawidłowe wpisanie informacji.
Zobaczysz kartę zawierającą 3 różne typy widżetów DateTimePicker
:
Pozwalanie użytkownikom na wybór elementów
Widżet SelectionInput
zawiera zestaw elementów do wyboru, takich jak pola wyboru, opcje, przełączniki i 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ś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:
Dodaj pole wyboru
Poniżej znajduje się karta z prośbą o wskazanie, czy kontakt jest związany z pracą, czy z kontaktem osobistym, czy z widżetem SelectionInput
z polami wyboru:
Dodaj opcję
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 z prośbą o wskazanie użytkownika za pomocą widżetu SelectionInput
z przełącznikami, który zawiera informacje o tym, czy kontakt jest zawodowy, prywatny czy też oba te rodzaje danych:
Dodaj 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:
Dodaj menu wielokrotnego wyboru
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 dodający elementy w menu wyboru wielokrotnego może wyświetlać i wybierać tylko pokoje, do których należą, w swojej 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 wyboru obiekty SectionItem
są pomijane, ponieważ te elementy są pozyskiwane dynamicznie z Google Workspace.
Podany niżej kod pokazuje menu z wieloma zaznaczonymi 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ć kontakty wyszukiwane ostatnio przez 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. W menu domyślnie wyświetla się 1 kontakt i uruchamia funkcję getContacts
do pobierania i wypełniania elementów z zewnętrznego źródła danych:
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ć, korzystając z 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 automatycznie uzupełnić maksymalnie 100 elementów.
Aby automatycznie uzupełniać elementy, tworzysz funkcję, która wysyła zapytania do zewnętrznego źródła danych i zwraca elementy za każdym razem, gdy użytkownik wpisze tekst w menu wyboru wielokrotnego. 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 są zgodne, zwracają sugerowane elementy z zewnętrznego źródła danych. Aby sugerować elementy na podstawie wpisanego przez użytkownika hasła, 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
Z tego artykułu dowiesz się, jak sprawdzać dane wprowadzane do action
i widżetów karty.
Możesz na przykład sprawdzić, czy pole tekstowe zawiera tekst wpisany przez użytkownika lub czy zawiera określoną liczbę znaków.
Ustaw wymagane widżety działań
W ramach sekcji action
na karcie dodaj do listy requiredWidgets
nazwy widżetów, których działanie wymaga.
Jeśli wymienione tu widżety nie mają wartości po wywołaniu tego działania, przesyłanie działania formularza zostanie anulowane.
Jeśli działanie jest ustawione na "all_widgets_are_required": "true"
, wymagane są wszystkie widżety na karcie.
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 widżetu textInput
można określić limit znaków i typ danych wejściowych tego widżetu.
Ustawianie limitu znaków dla widżetu wpisywania 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 wejściowych widżetu do 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 lub karta w Google Chat zwróci błąd, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. Czasami w UI Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład 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ć. Aby dowiedzieć się, jak wyświetlać, debugować i naprawiać błędy, przeczytaj artykuł Rozwiązywanie problemów z błędami Google Chat.