Dodawanie interaktywnych elementów interfejsu do kart

Z tego artykułu dowiesz się, jak dodawać widżety i elementy interfejsu do kart aby użytkownicy mogli korzystać z Twojej aplikacji Google Chat, np. przez klikając przycisk lub przesyłając informacje.

Aplikacje do obsługi czatu mogą korzystać z tych interfejsów Google Chat aby utworzyć interaktywne karty:

  • Wiadomości które zawierają co najmniej jedną kartę.
  • Strony główne, czyli kartę, która pojawia się na karcie Strona główna bezpośrednio wiadomości w aplikacji Google Chat.
  • okna dialogowe, czyli otwierane karty. w nowym oknie z wiadomości i stron głównych.

Gdy użytkownicy korzystają z kart, aplikacje Google Chat mogą używać danych, które na przetwarzanie danych i odpowiednio na nie zareagować. Więcej informacji: 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 kart

Wymagania wstępne

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywna aplikacja do obsługi czatu, wykonaj jedno z tych krótkich wprowadzeń dotyczące architektury aplikacji, której chcesz używać:

Dodaj przycisk

Widżet ButtonList wyświetla zestaw przycisków. Przyciski mogą zawierać tekst, lub zarówno tekst, jak i ikonę. Każdy Button obsługuje OnClick działanie w momencie kliknięcia przycisku. Na przykład:

  • Otwórz hiperlink z: OpenLink w celu dostarczenia użytkownikom dodatkowych informacji.
  • Uruchom action który uruchamia niestandardową funkcję, taką jak wywoływanie 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. Inny przycisk uruchamia funkcję niestandardową o nazwie goToView() i przekazuje viewType="BIRD EYE VIEW".

Dodaj przycisk w stylu Material Design

Poniżej znajduje się zestaw przycisków w różnych przyciskach w stylu Material Design stylów.

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

Dodaj przycisk z niestandardowym kolorem i nieaktywny przycisk

Aby uniemożliwić użytkownikom klikanie przycisków, skonfiguruj "disabled": "true".

Poniżej wyświetla się karta składająca się z widżetu ButtonList z dwoma przyciskami. Jeden z przycisków używa funkcji Pole Color aby dostosować tło przycisku koloru. Drugi przycisk jest dezaktywowany polem Disabled, które 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 ikonami Button widżety. Jeden z przycisków używa funkcji knownIcon aby wyświetlić wbudowaną ikonę poczty e-mail Google Chat. Drugi przycisk korzysta z funkcji iconUrl, aby wyświetlić niestandardowy widżet ikon.

Dodaj przycisk z ikoną i tekstem

Poniżej wyświetli się karta zawierająca widżet ButtonList z prośbą o potwierdzenie użytkownika do wysłania e-maila. Pierwszy z nich zawiera ikonę e-maila, drugi przycisk wyświetla tekst. Użytkownik może kliknąć ikonę lub tekst przycisk uruchamiania funkcji sendEmail.

Dostosowywanie przycisku do sekcji zwijanej

Dostosuj przycisk sterujący, który zwija i rozwija sekcje w Wybieraj spośród wielu ikon i obrazów, aby wizualnie przedstawić zawartość sekcji, ułatwiając użytkownikom zrozumienie i interakcję informacje.

Dodaj rozszerzone menu

Overflow menu mogą być używane na kartach czatu, oferując dodatkowe opcje i działania. Pozwala można dodać więcej opcji, nie zaśmiecając interfejsu karty, przejrzysty i uporządkowany projekt.

Dodaj listę chipsów

ChipList to uniwersalny i atrakcyjny wizualnie sposób wyświetlania informacji. Używaj list elementów do reprezentowania tagów, kategorii i innych istotnych danych, dzięki czemu użytkownicy będą mogli łatwiej poruszać się po materiałach i wchodzić z nimi w interakcję.

Zbieranie informacji od użytkowników

W tej sekcji wyjaśniono, jak dodawać widżety zbierające informacje, takie jak: tekstu lub zaznaczenia.

Aby dowiedzieć się, jak przetwarzać informacje wprowadzane przez użytkowników, zobacz Zbieranie i przetwarzanie informacji od użytkowników Google Chat

Zbierz tekst

Widżet TextInput udostępnia pole, w którym użytkownicy mogą wpisywać tekst. widżet obsługuje sugestie, które ułatwiają wprowadzanie jednolitych danych, i w razie potrzeby czynności, Actions uruchamianych, gdy nastąpi zmiana w polu do wprowadzania tekstu, np. dodanie przez użytkownika Usuwanie tekstu.

Jeśli chcesz zbierać abstrakcyjne lub nieznane dane od użytkowników, użyj tego Widżet TextInput. Aby zebrać zdefiniowane dane od użytkowników, użyj funkcji SelectionInput widżet.

Oto karta zawierająca widżet TextInput:

Daty lub godziny zbierania danych

Widżet DateTimePicker umożliwia użytkownikom wpisywanie daty, godziny lub zarówno daty, za jednym razem. Użytkownicy mogą też wybierać daty i godziny za pomocą selektora. Jeśli dane wejściowe użytkownika nieprawidłowa data lub godzina, selektor wyświetla błąd z prośbą o podanie danych i poprawić informacje.

Poniżej znajduje się karta z 3 różnymi typami DateTimePicker widżetu:

Pozwól użytkownikom wybierać elementy

Widżet SelectionInput zawiera zestaw elementów, które można wybrać, takich jak pola wyboru, opcje, przełączniki, lub za pomocą menu rozwijanego. Możesz używać tego widżetu aby zbierać zdefiniowane i ustandaryzowane dane od użytkowników. Do zbierania niezdefiniowanych danych użytkowników, użyj widżetu TextInput.

Widżet SelectionInput obsługuje sugestie, które pomagają użytkownikom wpisywać jednolite dane danych i działań w przypadku zmiany, Actions. uruchamianych, gdy nastąpi zmiana w polu do wprowadzania danych, np. w polu użytkownika wybierając lub odznaczając element.

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 Informacje o procesach wprowadzane przez użytkowników.

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 znajduje się karta z prośbą o określenie, czy do kontaktów służbowych, osobistych lub na oba te sposoby, z widżetem SelectionInput, który używa pól wyboru:

Dodaj opcję

Poniżej znajduje się karta z prośbą o określenie, czy jest przeznaczony do kontaktów zawodowych lub osobistych, korzystając z widżetu SelectionInput, który używa opcje:

Dodaj przełącznik

Poniżej znajduje się karta z prośbą o określenie, czy do kontaktów służbowych, osobistych lub na oba te rodzaje, korzystając z widżetu SelectionInput, używa przełączników:

Poniżej znajduje się karta z prośbą o określenie, czy jest przeznaczony do kontaktów zawodowych lub osobistych, korzystając z widżetu SelectionInput, który używa menu:

Dodaj menu wielokrotnego wyboru

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

Możesz uzupełnić elementy menu wielokrotnego wyboru na podstawie tych danych źródeł w Google Workspace:

  • Użytkownicy Google Workspace: możesz wypełniać pola tylko użytkowników w tej samej organizacji Google Workspace.
  • Pokoje czatu: użytkownik wpisuje elementy podczas wyboru wielokrotnego. mogą wyświetlać i wybierać tylko pokoje, do których należą organizacji Google Workspace.

Aby używać źródeł danych Google Workspace, określ platformDataSource . W przeciwieństwie do innych typów wprowadzania zaznaczenia – SectionItem ponieważ te elementy są pobierane 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"
    }
  }
}

Ten kod pokazuje menu wielokrotnego wyboru w Google Chat spacje. Aby wstawić spacje, pole wyboru określa parametr hostAppDataSource. Menu wyboru wielokrotnego zawiera też Od defaultToCurrentSpace do true, przez co bieżący pokój jest ustawiony jako domyślny w menu:

JSON

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

Menu wyboru wielokrotnego może też zawierać elementy z danych innych firm lub danych zewnętrznych źródła. Możesz na przykład użyć menu wielokrotnego wyboru, aby ułatwić użytkownikowi lista potencjalnych klientów generowanych przez system zarządzania relacjami z klientami (CRM).

Aby użyć zewnętrznego źródła danych, użyj pola externalDataSource do: 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 pojawiają się w menu wielokrotnego wyboru, zanim użytkownicy wpiszą w menu. Możesz na przykład wypełnić ostatnio wyszukiwane kontakty jako użytkownika. Aby uzupełnić sugerowane elementy z zewnętrznego źródła danych, wpisz SelectionItem obiektów.

Ten kod pokazuje menu wielokrotnego wyboru z elementów z zewnętrznego zestawu kontaktów dla użytkownika. W menu domyślnie wyświetlany jest jeden kontakt i uruchamia funkcję getContacts, aby pobrać i wypełnić elementy z zewnętrzne źródło 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 uruchamiane przez użytkowników w menu wielokrotnego wyboru. Jeśli na przykład użytkownik zacznie wpisywać Atl dla zapytania obejmujące miasta w Stanach Zjednoczonych, Aplikacja do obsługi czatu może automatycznie sugerować Atlanta przed użytkownikiem kończy pisanie. Możesz użyć autouzupełniania maksymalnie 100 elementów.

Aby automatycznie uzupełniać elementy, utwórz funkcję, która wysyła zapytania do danych zewnętrznych źródła i zwraca elementy za każdym razem, gdy użytkownik wpisze tekst w menu wyboru wielokrotnego. musi wykonać te czynności:

  • Przekazuj obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
  • Określ, że zdarzenie interakcji invokedFunction odpowiada funkcji z pola externalDataSource.
  • Jeśli funkcje są zgodne, zwraca sugerowane elementy na podstawie danych zewnętrznych. źródła. Aby sugerować elementy na podstawie wpisanego przez użytkownika hasła, pobierz wartość atrybutu autocomplete_widget_query klawisz. Ta wartość odzwierciedla tekst wpisywany przez użytkownika w menu.

Podany niżej kod automatycznie uzupełnia elementy z zewnętrznego zasobu danych. Korzystanie z poprzedni przykład: aplikacja Google Chat sugeruje elementy na podstawie po wywołaniu funkcji getContacts:

Google Apps Script

apps-script/selection-input/on-widget-update.gs
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Weryfikuj dane wprowadzane na kartach

Z tego artykułu dowiesz się, jak zweryfikować dane wprowadzone w action karty i widżety. Można na przykład sprawdzić, czy pole do wprowadzania tekstu zawiera tekst wpisany przez użytkownika lub że zawiera określoną liczbę znaków.

Ustaw wymagane widżety działań

W ramach tego action karty, dodaj nazwy widżetów, które są potrzebne do wykonania działania, do swojej listy requiredWidgets.

Jeśli wymienione tutaj widżety nie mają wartości w momencie wywołania tego działania, to przesłanie formularza zostanie anulowane.

Gdy "all_widgets_are_required": "true" jest ustawione dla działania, wszystkie widżety widoczne 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: textInput do widżetu, może on określać limit znaków i typ danych wejściowych w widżecie do wprowadzania tekstu.

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 Google Chat lub card zwraca błąd, Interfejs czatu wyświetla komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. Czasami interfejs Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja Google Chat lub zwraca nieoczekiwany wynik; na przykład wiadomość w formie karty .

Komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, opisowe komunikaty o błędach i dane dziennika, które pomogą Ci w naprawianiu błędów gdy logowanie błędów aplikacji Google Chat jest włączone. Aby uzyskać pomoc w wyświetlaniu, debugowania i naprawiania błędów, zapoznaj się z artykułem Rozwiązywanie problemów z błędami w Google Chat