Dodawanie interaktywnych elementów interfejsu do kart

Na tej stronie dowiesz się, jak dodawać widżety i elementy interfejsu do kart, aby użytkownicy mogli wchodzić w interakcje z Twoją aplikacją w Google Chat, np. klikać przyciski lub przesyłać informacje.

Aplikacje Google Chat mogą używać tych interfejsów Google Chat do tworzenia interaktywnych kart:

• Wiadomości zawierające co najmniej 1 kartę.
• Strony główne, czyli karty wyświetlane na karcie Strona główna w wiadomościach bezpośrednich z aplikacją Google Chat.
• Okna dialogowe, czyli karty, które otwierają się w nowym oknie z wiadomości i stron głównych.

Gdy użytkownicy wchodzą w interakcję z kartami, aplikacje w Google Chat 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.

Użyj narzędzia do tworzenia kart, aby projektować i wyświetlać podgląd wiadomości oraz interfejsów użytkownika aplikacji Google Chat:

Wymagania wstępne

Aplikacja Google Chat skonfigurowana do odbierania zdarzeń interakcji i odpowiadania na nie. Aby utworzyć interaktywną aplikację do obsługi czatu, wykonaj jeden z tych przewodników Szybki start, 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

ButtonListWidżet wyświetla zestaw przycisków. Przyciski mogą wyświetlać tekst, ikonę lub tekst i ikonę. Każdy element Button obsługuje OnClickdziałanie wykonywane, gdy użytkownicy klikną przycisk. Na przykład:

• Otwórz hiperlink za pomocą elementu OpenLink, aby przekazać użytkownikom dodatkowe informacje.
• Uruchom action, która uruchamia funkcję niestandardową, np. wywołuje interfejs API.

Przyciski obsługują tekst alternatywny, co ułatwia korzystanie z nich osobom z niepełnosprawnościami.

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ę dewelopera 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 przycisków Material Design.

Aby zastosować styl Material Design, nie uwzględniaj atrybutu „color”.

Dodawanie przycisku z niestandardowym kolorem i dezaktywowanego przycisku

Możesz uniemożliwić użytkownikom kliknięcie przycisku, ustawiając wartość "disabled": "true".

Poniżej znajduje się karta składająca się z widżetu ButtonList z 2 przyciskami. Jeden przycisk korzysta z pola Color, aby dostosować kolor 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 znajduje się karta składająca się z widżetu ButtonList z 2 widżetami ikon Button. Jeden przycisk używa pola knownIcon do wyświetlania wbudowanej ikony e-maila Google Chat. Drugi przycisk używa pola iconUrl do wyświetlania widżetu ikony niestandardowej.

Dodawanie przycisku z ikoną i tekstem

Poniżej znajduje się karta z widżetem ButtonList, który wyświetla użytkownikowi prośbę o wysłanie e-maila. Pierwszy przycisk zawiera ikonę e-maila, a drugi – tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby uruchomić funkcję sendEmail.

Dostosowywanie przycisku sekcji zwijanej

Dostosuj przycisk sterowania, który zwija i rozwija sekcje w karcie. Wybierz jedną z ikon lub obrazów, aby wizualnie przedstawić zawartość sekcji, co ułatwi użytkownikom zrozumienie informacji i interakcję z nimi.

Dodawanie rozszerzonego menu

Element Overflow menu można stosować na kartach Google Chat, aby oferować dodatkowe opcje i działania. Umożliwia to dodanie większej liczby opcji bez zaśmiecania interfejsu karty, co zapewnia przejrzysty i uporządkowany wygląd.

Dodawanie listy elementów

Widżet ChipList to wszechstronny i atrakcyjny wizualnie sposób wyświetlania informacji. Używaj list z elementami, aby przedstawiać tagi, kategorie lub inne istotne dane, co ułatwi użytkownikom poruszanie się po treściach i wchodzenie z nimi w interakcję.

Zbieranie informacji od użytkowników

Z tej sekcji dowiesz się, jak dodawać widżety, które zbierają informacje, np. tekst lub wybrane opcje.

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

TextInputWidżet udostępnia pole, w którym użytkownicy mogą wpisywać tekst. Widżet obsługuje sugestie, które pomagają użytkownikom wprowadzać jednolite dane, oraz działania po zmianie, które są Actions wykonywane, gdy w polu wprowadzania tekstu nastąpi zmiana, np. gdy użytkownik doda lub usunie tekst.

Jeśli musisz zbierać od użytkowników abstrakcyjne lub nieznane dane, użyj tego widżetuTextInput. Aby zbierać określone dane od użytkowników, użyj widżetu SelectionInput.

Poniżej znajdziesz kartę z widżetem TextInput:

Zbieranie dat i godzin

DateTimePickerWidżet umożliwia użytkownikom wprowadzanie daty, godziny lub obu tych wartości. Użytkownicy mogą też używać selektora do wybierania dat i godzin. Jeśli użytkownicy wpiszą nieprawidłową datę lub godzinę, selektor wyświetli błąd z prośbą o poprawne wprowadzenie informacji.

Poniżej znajduje się karta składająca się z 3 rodzajów widżetów:DateTimePicker

Umożliwianie użytkownikom wybierania elementów

SelectionInputWidżet udostępnia zestaw elementów do wyboru, takich jak pola wyboru, przyciski opcji, przełączniki lub menu. Za pomocą tego widżetu możesz zbierać od użytkowników zdefiniowane i znormalizowane dane. Aby zbierać od użytkowników niezdefiniowane dane, użyj widżetu TextInput.

Widżet SelectionInput obsługuje sugestie, które pomagają użytkownikom wprowadzać jednolite dane, oraz działania po zmianie, które są Actions wykonywane, gdy w polu wprowadzania wyboru nastąpi zmiana, np. gdy użytkownik wybierze lub odznaczy element.

Aplikacje do obsługi czatu mogą odbierać i przetwarzać wartość wybranych produktów. Więcej informacji o pracy z danymi wejściowymi formularza znajdziesz w artykule Przetwarzanie informacji wprowadzonych przez użytkowników.

Ta sekcja zawiera przykłady kart, które korzystają z widżetu SelectionInput. W przykładach użyto różnych typów danych wejściowych sekcji:

• Pola wyboru
• Opcje
• Przełączniki
• Menu
• Menu wielokrotnego wyboru

Dodawanie pola wyboru

Poniżej znajduje się karta, na której użytkownik jest proszony o określenie, czy kontakt jest służbowy, osobisty czy oba, z widżetem SelectionInput, który korzysta z pól wyboru:

Dodawanie przycisku opcji

Poniżej znajduje się karta z prośbą o określenie, czy kontakt jest służbowy czy prywatny, oraz widżet SelectionInput z przyciskami opcji:

Dodawanie przełącznika

Poniżej znajduje się karta z prośbą o określenie, czy kontakt jest służbowy, osobisty czy oba, z widżetem SelectionInput, który używa przełączników:

Dodawanie menu

Poniżej wyświetla się karta z prośbą o określenie, czy kontakt jest służbowy czy prywatny, z widżetem SelectionInput, który korzysta z menu.

Dodawanie menu wielokrotnego wyboru

Poniżej znajduje się karta z prośbą o wybranie kontaktów z menu wielokrotnego wyboru:

Elementy menu wielokrotnego wyboru możesz wypełniać danymi z tych źródeł w Google Workspace:

• Użytkownicy Google Workspace: możesz wypełnić 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 pokoje, do których należy w organizacji Google Workspace.

Aby używać źródeł danych Google Workspace, musisz określić pole platformDataSource. W przeciwieństwie do innych typów danych wejściowych wyboru pomijasz obiekty SelectionItem, ponieważ te elementy wyboru są dynamicznie pobierane z Google Workspace.

Poniższy kod przedstawia menu wielokrotnego wyboru użytkowników Google Workspace. Aby wypełnić listę użytkowników, dane wejściowe wyboru ustawiają wartość commonDataSource na USER:

{   "selectionInput": {     "name": "contacts",     "type": "MULTI_SELECT",     "label": "Selected contacts",     "multiSelectMaxSelectedItems": 5,     "multiSelectMinQueryLength": 1,     "platformDataSource": {       "commonDataSource": "USER"     }   } } 

Poniższy kod pokazuje menu wielokrotnego wyboru przestrzeni na czacie. Aby wypełnić miejsca, w polu wyboru należy określić pole hostAppDataSource. W menu wielokrotnego wyboru ustawia się też wartość defaultToCurrentSpace na true, co sprawia, że bieżący pokój jest domyślnie wybierany w menu:

{   "selectionInput": {     "name": "spaces",     "type": "MULTI_SELECT",     "label": "Selected contacts",     "multiSelectMaxSelectedItems": 3,     "multiSelectMinQueryLength": 1,     "platformDataSource": {       "hostAppDataSource": {         "chatDataSource": {           "spaceDataSource": {             "defaultToCurrentSpace": true           }         }       }     }   } } 

Menu wielokrotnego wyboru mogą też zawierać elementy pochodzące ze źródła danych zewnętrznego lub firmy zewnętrznej. Możesz na przykład użyć menu wielokrotnego wyboru, aby pomóc użytkownikowi wybrać 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 podaj 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 zaczną wpisywać tekst w menu. Możesz na przykład wypełnić listę ostatnio wyszukiwanych kontaktów 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 elementów z zewnętrznego zestawu kontaktów użytkownika. Menu domyślnie wyświetla 1 kontakt i uruchamia funkcję getContacts, aby pobrać i wypełnić elementy z zewnętrznego źródła danych:

selectionInput: {   name: "contacts",   type: "MULTI_SELECT",   label: "Selected contacts",   multiSelectMaxSelectedItems: 3,   multiSelectMinQueryLength: 1,   externalDataSource: { function: "getContacts" },   // Suggested items loaded by default.   // The list is static here but it could be dynamic.   items: [getContact("3")] }

'selectionInput': {   'name': "contacts",   'type': "MULTI_SELECT",   'label': "Selected contacts",   'multiSelectMaxSelectedItems': 3,   'multiSelectMinQueryLength': 1,   'externalDataSource': { 'function': "getContacts" },   # Suggested items loaded by default.   # The list is static here but it could be dynamic.   'items': [get_contact("3")] }

.setSelectionInput(new GoogleAppsCardV1SelectionInput()   .setName("contacts")   .setType("MULTI_SELECT")   .setLabel("Selected contacts")   .setMultiSelectMaxSelectedItems(3)   .setMultiSelectMinQueryLength(1)   .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))   .setItems(List.of(getContact("3")))))))))));

selectionInput: {   name: "contacts",   type: "MULTI_SELECT",   label: "Selected contacts",   multiSelectMaxSelectedItems: 3,   multiSelectMinQueryLength: 1,   externalDataSource: { function: "getContacts" },   // Suggested items loaded by default.   // The list is static here but it could be dynamic.   items: [getContact("3")] }

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 zawiera miasta w Stanach Zjednoczonych, aplikacja Google Chat może automatycznie zasugerować Atlanta, zanim użytkownik skończy wpisywać. Możesz automatycznie uzupełnić maksymalnie 100 produktów.

Aby autouzupełniać elementy, utwórz funkcję, która wysyła zapytania do zewnętrznego źródła danych i zwraca elementy, gdy użytkownik wpisuje tekst w menu wielokrotnego wyboru. Funkcja musi wykonać te czynności:

• Przekaż obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
• Sprawdź, czy wartość zdarzenia interakcji invokedFunction jest zgodna z funkcją z pola externalDataSource.
• Gdy funkcje są zgodne, zwracaj sugerowane produkty ze źródła danych zewnętrznych. Aby sugerować elementy na podstawie tego, co wpisuje użytkownik, pobierz wartość klucza autocomplete_widget_query. Ta wartość reprezentuje to, co użytkownik wpisuje w menu.

Poniższy kod automatycznie uzupełnia elementy z zewnętrznego źródła danych. W poprzednim przykładzie aplikacja Chat sugeruje elementy na podstawie tego, kiedy zostanie wywołana funkcja getContacts:

/**  * Responds to a WIDGET_UPDATE event in Google Chat.  *  * @param {Object} event The event object from Chat API.  * @return {Object} Response from the Chat app.  */ function onWidgetUpdate(event) {   if (event.common["invokedFunction"] === "getContacts") {     const query = event.common.parameters["autocomplete_widget_query"];     return { actionResponse: {       type: "UPDATE_WIDGET",       updatedWidget: { suggestions: { items: [         // The list is static here but it could be dynamic.         getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")       // Only return items based on the query from the user       ].filter(e => !query || e.text.includes(query))}}     }};   } }  /**  * Generate a suggested contact given an ID.  *  * @param {String} id The ID of the contact to return.  * @return {Object} The contact formatted as a suggested item for selectors.  */ function getContact(id) {   return {     value: id,     startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",     text: "Contact " + id   }; }

def on_widget_update(event: dict) -> dict:   """Responds to a WIDGET_UPDATE event in Google Chat."""   if "getContacts" == event.get("common").get("invokedFunction"):     query = event.get("common").get("parameters").get("autocomplete_widget_query")     return { 'actionResponse': {       'type': "UPDATE_WIDGET",       'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [         # The list is static here but it could be dynamic.         get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")       # Only return items based on the query from the user       ]))}}     }}   def get_contact(id: str) -> dict:   """Generate a suggested contact given an ID."""   return {     'value': id,     'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",     'text': "Contact " + id   }

// Responds to a WIDGET_UPDATE event in Google Chat. Message onWidgetUpdate(JsonNode event) {   if ("getContacts".equals(event.at("/invokedFunction").asText())) {     String query = event.at("/common/parameters/autocomplete_widget_query").asText();     return new Message().setActionResponse(new ActionResponse()       .setType("UPDATE_WIDGET")       .setUpdatedWidget(new UpdatedWidget()         .setSuggestions(new SelectionItems().setItems(List.of(           // The list is static here but it could be dynamic.           getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")         // Only return items based on the query from the user         ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));   }   return null; }  // Generate a suggested contact given an ID. GoogleAppsCardV1SelectionItem getContact(String id) {   return new GoogleAppsCardV1SelectionItem()     .setValue(id)     .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")     .setText("Contact " + id); }

/**  * Responds to a WIDGET_UPDATE event in Google Chat.  *  * @param {Object} event The event object from Chat API.  * @return {Object} Response from the Chat app.  */ function onWidgetUpdate(event) {   if (event.common["invokedFunction"] === "getContacts") {     const query = event.common.parameters["autocomplete_widget_query"];     return { actionResponse: {       type: "UPDATE_WIDGET",       updatedWidget: { suggestions: { items: [         // The list is static here but it could be dynamic.         getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")       // Only return items based on the query from the user       ].filter(e => !query || e.text.includes(query))}}     }};   } }  /**  * Generate a suggested contact given an ID.  *  * @param {String} id The ID of the contact to return.  * @return {Object} The contact formatted as a suggested item for selectors.  */ function getContact(id) {   return {     value: id,     startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",     text: "Contact " + id   }; }

Sprawdzanie danych wprowadzonych na kartach

Na tej stronie dowiesz się, jak weryfikować dane wprowadzane do action i widżetów karty. Możesz na przykład sprawdzić, czy w polu tekstowym użytkownik wpisał tekst lub czy zawiera ono określoną liczbę znaków.

Ustawianie wymaganych widżetów dla działań

W ramach karty action dodaj do listy requiredWidgets nazwy widżetów, których działanie potrzebuje.

Jeśli w momencie wywołania tej czynności którykolwiek z wymienionych tu widżetów nie ma wartości, przesyłanie działania formularza zostanie anulowane.

Jeśli dla działania ustawiono wartość "all_widgets_are_required": "true", wszystkie widżety na karcie są wymagane przez to działanie.

Ustawianie działania all_widgets_are_required w przypadku wielokrotnego wyboru

{   "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 selektorze daty i godziny

{   "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"           }         }       ]     }   ] } 

Ustawianie działania all_widgets_are_required w menu

{   "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 wprowadzania tekstu

W polu weryfikacji widżetu textInput może określić limit znaków i typ danych wejściowych dla tego widżetu wprowadzania tekstu.

Ustawianie limitu znaków w widżecie wprowadzania tekstu

{   "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 wprowadzania tekstu

{   "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, w interfejsie Google Chat pojawia się komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat daje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż w interfejsie czatu może nie wyświetlać się komunikat o błędzie, opisowe komunikaty o błędach i dane logowania są dostępne, aby pomóc w naprawieniu błędów, gdy rejestrowanie błędów w aplikacjach na czat jest włączone. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat.

Powiązane artykuły

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• DateTimePicker widżet