Z tego artykułu dowiesz się, jak dodawać widżety i elementy interfejsu do kart i komunikatów, aby użytkownicy mogli korzystać z aplikacji Google Chat, np. przez kliknięcie przycisku czy przesłanie informacji.
Za pomocą kreatora kart możesz zaprojektować i wyświetlić podgląd wiadomości kart JSON przeznaczonych do aplikacji Google Chat:
Otwórz Kreator kartWymagania wstępne
Dodaj przycisk
Widżet ButtonList
wyświetla zestaw przycisków. Na przyciskach może być tekst, ikona lub zarówno tekst, jak i ikona. Każda Button
obsługuje działanie OnClick
, które ma miejsce, gdy użytkownik kliknie przycisk. 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 przypadku ułatwień dostępu przyciski obsługują tekst alternatywny.
Dodaj przycisk uruchamiający 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 z niestandardowym kolorem i nieaktywny przycisk
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. Za pomocą pola Color
jednego z przycisków można dostosować kolor 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ą.
Dodaj przycisk 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 to ikona e-maila,
a drugi tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby uruchomić funkcję sendEmail
.
Dodawanie elementów interfejsu do wyboru
Widżet SelectionInput
zawiera zestaw elementów do wyboru, takich jak pola wyboru, opcje, przełączniki i menu. Możesz używać tego widżetu do zbierania zdefiniowanych i ustandaryzowanych danych o użytkownikach. Aby zbierać od użytkowników niezdefiniowane dane, użyj widżetu TextInput
.
Widżet SelectionInput
obsługuje sugestie, które ułatwiają użytkownikom wprowadzanie jednolitych danych, i działania związane ze zmianą – Actions
wywoływane, gdy zmiana w polu do wprowadzania danych, na przykład wybranie lub odznaczenie elementu przez użytkownika.
Aplikacje do obsługi czatu mogą otrzymywać i przetwarzać wartość wybranych elementów. Szczegółowe informacje o pracy z danymi wejściowymi formularza znajdziesz w artykule Odbieranie danych formularza.
W tej sekcji znajdziesz przykłady kart, które korzystają z widżetu SelectionInput
.
W przykładach używane są różne typy danych wejściowych sekcji:
Dodaj pole wyboru
Poniżej wyświetla się okno z prośbą o wskazanie, czy kontakt jest służbowy, prywatny, czy jedno i drugi, za pomocą widżetu SelectionInput
z polami wyboru:
Dodaj opcję
Poniżej wyświetla się okno z prośbą o wskazanie, czy kontakt jest służbowy czy osobisty, w widżecie SelectionInput
z przyciskami opcji:
Dodaj przełącznik
Poniżej wyświetla się okno z prośbą o wskazanie w widżecie SelectionInput
z przełącznikami, czy kontakt jest zawodowy, prywatny czy też oba te rodzaje kontaktów:
Dodaj menu
Poniżej wyświetla się okno z prośbą o wskazanie użytkownika w widżecie SelectionInput
korzystającym z menu, czy jest to kontakt służbowy, czy osobisty:
Dodaj menu wielokrotnego wyboru
Poniżej wyświetli się okno z prośbą o wybranie kontaktów z menu wielokrotnego wyboru:
Użyj źródeł danych w menu wielokrotnego wyboru
W tej sekcji wyjaśniamy, jak używać menu wielokrotnego wyboru do wypełniania danych ze źródeł dynamicznych, takich jak aplikacja Google Workspace lub zewnętrzne źródło danych.
Źródła danych z Google Workspace
Elementy menu wielokrotnego wyboru możesz uzupełnić z tych źródeł danych w Google Workspace:
- Użytkownicy Google Workspace: możesz wypełniać pola tylko użytkowników należących do 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, określ 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.
Poniższy kod przedstawia menu wielokrotnego wyboru z użytkownikami Google Workspace.
Aby zapełnić użytkowników, pole wyboru ustawia wartość 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 z pokojami czatu. Aby można było wstawić spacje, pole wyboru określa pole hostAppDataSource
. Menu wyboru wielokrotnego ustawia też defaultToCurrentSpace
na true
, co oznacza, że bieżący obszar 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 wyboru wielokrotnego może 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 dokonanie wyboru z listy potencjalnych klientów z systemu 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 zmniejszyć 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 w nim wpiszą. Możesz na przykład wypełnić ostatnio wyszukiwane kontakty użytkownika. Aby wypełniać sugerowane elementy 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:
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ż 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
, aby wyświetlić menu z miastami w Polsce, aplikacja Google Chat może automatycznie zasugerować Atlanta
, zanim użytkownik skończy pisać. Możesz użyć autouzupełniania 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:
- Przekazuj obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
- Sprawdź, czy wartość
invokedFunction
zdarzenia interakcji pasuje do 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.
Podany niżej kod automatycznie uzupełnia elementy z zewnętrznego zasobu danych. Korzystając z poprzedniego przykładu, aplikacja Google Chat sugeruje elementy na podstawie chwili wywołania funkcji getContacts
:
Google Apps Script
Node.js
Dodaj pole, w którym użytkownik może wpisywać tekst
Widżet 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ć abstrakcyjne lub nieznane dane od użytkowników, użyj tego widżetu TextInput
. Aby zbierać określone dane od użytkowników, użyj widżetu SelectionInput
.
Informacje o przetwarzaniu tekstu wpisywanego przez użytkowników znajdziesz w artykule Odbieranie danych formularza.
Oto karta zawierająca widżet TextInput
:
Pozwól użytkownikowi wybrać datę i 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.
Informacje o przetwarzaniu wartości daty i godziny wpisanych przez użytkowników znajdziesz w artykule Odbieranie danych formularza.
Zobaczysz kartę zawierającą 3 różne typy widżetów DateTimePicker
:
Weryfikuj dane wprowadzane na kartach
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 do wprowadzania tekstu zawiera tekst wpisany przez użytkownika lub czy zawiera określoną liczbę znaków.
Ustaw wymagane widżety działań
W action
na karcie dodaj nazwy widżetów, które są potrzebne do wykonania działania, do listy requiredWidgets
.
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.
Ustaw działanie all_widgets_are_required
w wyborze wielokrotnym
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 w menu działanie all_widgets_are_required
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.
Mimo że komunikat o błędzie może nie być wyświetlany w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane logów, które pomogą Ci w naprawianiu błędów, gdy logowanie błędów w aplikacjach Google Chat jest włączone. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami w Google Chat.