Auf dieser Seite wird erläutert, wie Sie Karten- oder Dialogfeldnachrichten Widgets und UI-Elemente hinzufügen. damit Nutzer mit Ihrer Google Chat App interagieren können, z. B. über auf eine Schaltfläche klicken oder Informationen übermitteln.
Mit dem Card Builder können Sie JSON-Kartennachrichten für Chat-Apps erstellen und als Vorschau ansehen:
Card Builder öffnenVorbereitung
Schaltfläche hinzufügen
Die
ButtonList-Widget
zeigt eine Reihe von Schaltflächen an. Schaltflächen können Text,
-Symbol oder sowohl Text als auch ein Symbol. Jedes
Button
unterstützt ein
OnClick Aktion
die angezeigt wird, wenn Nutzende
auf die Schaltfläche klicken. Beispiel:
- Hyperlink öffnen mit
OpenLink, um Nutzern zusätzliche Informationen zu bieten. - Führen Sie einen
actionzum Ausführen einer benutzerdefinierten Funktion wie dem Aufrufen einer API.
Aus Gründen der Barrierefreiheit unterstützen Schaltflächen alternativen Text.
Schaltfläche zum Ausführen einer benutzerdefinierten Funktion hinzufügen
Die folgende Karte besteht aus einem ButtonList-Widget mit zwei Schaltflächen.
Über nur eine Schaltfläche wird die Entwicklerdokumentation für Google Chat in einem neuen Tab geöffnet. Die
andere Schaltfläche führt eine benutzerdefinierte Funktion namens goToView() aus und übergibt
viewType="BIRD EYE VIEW"-Parameter.
Eine Schaltfläche mit einer benutzerdefinierten Farbe und einer deaktivierten Schaltfläche hinzufügen
Du kannst verhindern, dass Nutzer auf eine Schaltfläche klicken, indem du "disabled": "true" festlegst.
Im Folgenden sehen Sie eine Karte, die aus einem ButtonList-Widget mit zwei
Schaltflächen. Eine Schaltfläche verwendet die
Feld „Color“
um den Hintergrund der Schaltfläche anzupassen
Farbe. Die andere Schaltfläche wird über das Feld Disabled deaktiviert, das
Verhindert, dass die Nutzenden auf die Schaltfläche klicken und die Funktion ausführen.
Schaltfläche mit einem Symbol hinzufügen
Im Folgenden wird eine Karte angezeigt, die aus einem ButtonList-Widget mit zwei Symbolen besteht.
Button-Widgets Eine Schaltfläche verwendet die
knownIcon
Feld, um das integrierte E-Mail-Symbol von Google Chat anzuzeigen. Für die andere Schaltfläche
iconUrl-Feld
Widget für benutzerdefinierte Symbole.
Schaltfläche mit Symbol und Text hinzufügen
Im Folgenden wird eine Karte mit einem ButtonList-Widget angezeigt, das Sie auffordert,
um eine E-Mail zu senden. Die erste Schaltfläche enthält ein E-Mail-Symbol und
auf die zweite Schaltfläche. Die Nutzenden können entweder auf das Symbol oder den Text
Schaltfläche zum Ausführen der Funktion sendEmail.
Auswählbare UI-Elemente hinzufügen
SelectionInput-Widget
enthält auswählbare Elemente wie Kontrollkästchen, Optionsfelder,
oder ein Drop-down-Menü. Sie können dieses Widget verwenden,
um definierte und standardisierte Daten
von Nutzenden zu erfassen. Um undefinierte Daten zu erfassen
verwenden, verwenden Sie stattdessen das Widget TextInput.
Das SelectionInput-Widget unterstützt Vorschläge, die Nutzern bei der Eingabe der einheitlichen
Daten und Aktionen bei Änderungen, die
Actions
die ausgeführt werden, wenn eine Änderung in einem Auswahleingabefeld auftritt, z. B. einem Nutzer
Auswählen oder Aufheben der Auswahl eines Elements.
Chat-Apps können den Wert ausgewählter Elemente empfangen und verarbeiten. Weitere Informationen zur Arbeit mit Formulareingaben finden Sie unter Von Nutzern eingegebene Informationen verarbeiten.
Dieser Abschnitt enthält Beispiele für Karten, für die das SelectionInput-Widget verwendet wird.
In den Beispielen werden verschiedene Arten von Abschnittseingaben verwendet:
Kästchen hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, anzugeben, ob ein
beruflich, privat oder beides ist, und zwar mit einem SelectionInput-Widget, das
verwendet Kontrollkästchen:
Optionsfeld hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, anzugeben, ob ein
Kontakt ist beruflich oder persönlich mit einem SelectionInput-Widget, das
Optionsfeldern:
Schalter hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, anzugeben, ob ein
Ihr Kontakt beruflich, privat oder beides ist, mit einem SelectionInput-Widget, das
verwendet Schalter:
Drop-down-Menü hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, anzugeben, ob ein
Kontakt ist beruflich oder persönlich mit einem SelectionInput-Widget, das
ein Dropdown-Menü:
Mehrfachauswahl-Menü hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, Kontakte auszuwählen. aus einem Mehrfachauswahl-Menü:
Datenquellen für Menüs mit Mehrfachauswahl verwenden
Im folgenden Abschnitt wird erläutert, wie Daten mit Mehrfachauswahl-Menüs dargestellt werden. aus dynamischen Quellen wie einer Google Workspace-Anwendung oder externen Daten Quelle.
Datenquellen aus Google Workspace
Sie können Elemente für ein Mehrfachauswahl-Menü aus den folgenden Datenquellen ausfüllen in: Google Workspace:
- Google Workspace-Nutzer: Sie können nur Nutzer in der in derselben Google Workspace-Organisation.
- Chatbereiche: Der Nutzer, der Elemente in die Mehrfachauswahl eingibt nur Gruppenbereiche anzeigen und auswählen, zu denen sie innerhalb ihrer Google Workspace-Organisation.
Wenn Sie Google Workspace-Datenquellen verwenden möchten, geben Sie die
platformDataSource
ein. Im Gegensatz zu anderen Auswahleingabetypen
SectionItem
-Objekte, da diese Auswahlelemente dynamisch aus
Google Workspace
Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Google Workspace-Nutzern.
Um Nutzer hinzuzufügen, wird commonDataSource durch die Auswahleingabe auf USER gesetzt:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Der folgende Code zeigt ein Mehrfachauswahl-Menü für Google Chat
Leerzeichen. Um Gruppenbereiche auszufüllen, gibt die Auswahleingabe die
hostAppDataSource. Das Mehrfachauswahl-Menü legt auch fest,
defaultToCurrentSpace auf true, wodurch der aktuelle Bereich zum Standard wird
im Menü:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Datenquellen außerhalb von Google Workspace
Menüs mit Mehrfachauswahl können auch Elemente aus Daten von Drittanbietern oder externen Daten darstellen Quelle. Sie können beispielsweise Mehrfachauswahl-Menüs verwenden, um Nutzern die Auswahl aus einem Liste der Leads aus einem CRM-System (Customer-Relationship-Management).
Wenn Sie eine externe Datenquelle verwenden möchten, verwenden Sie das Feld externalDataSource für
eine Funktion angeben, die Elemente aus der Datenquelle zurückgibt.
Um die Anzahl der Anfragen an eine externe Datenquelle zu reduzieren, können Sie
Vorgeschlagene Elemente, die im Mehrfachauswahl-Menü angezeigt werden, bevor Nutzer Text eingeben
Menü. Sie können beispielsweise kürzlich gesuchte Kontakte für die
Nutzer. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle füllen möchten, geben Sie
SelectionItem
Objekte.
Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Elementen aus einem
Gruppe von externen Kontakten für den Nutzer. Im Menü wird standardmäßig ein Kontakt angezeigt
und führt die Funktion getContacts aus, um Elemente aus der
externe Datenquelle:
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
}
]
}
}
Bei externen Datenquellen können Sie von Nutzern gestartete Elemente auch automatisch vervollständigen lassen
die Eingabe im Mehrfachauswahl-Menü. Wenn ein Nutzer z. B. beginnt, Atl für eine
unter "Städte in den USA" angezeigt,
Die Chat-App kann Atlanta vor dem Nutzer automatisch vorschlagen
die Eingabe beendet. Sie können bis zu 100 Elemente automatisch vervollständigen.
Zur automatischen Vervollständigung von Elementen erstellen Sie eine Funktion, die die externen Daten abfragt. Quelle und gibt Elemente zurück, wenn ein Nutzer eine Eingabe über das Mehrfachauswahl-Menü ausführt. Die muss Folgendes ausgeführt werden:
- Übergeben Sie ein Ereignisobjekt, das die Nutzerinteraktion mit dem Menü darstellt.
- Erkennen, dass das Interaktionsereignis
invokedFunctionvalue entspricht der Funktion aus dem FeldexternalDataSource. - Bei Übereinstimmung der Funktionen vorgeschlagene Elemente aus den externen Daten zurückgeben
Quelle. Um Elemente basierend auf den Nutzertypen vorzuschlagen, rufen Sie den Wert für die
autocomplete_widget_query-Schlüssel. Dieser Wert gibt an, was der Nutzer im Menü aus.
Mit dem folgenden Code werden Elemente aus einer externen Datenressource automatisch vervollständigt. Mit der
Beispiels gezeigt hat, schlägt die Chat-App Elemente vor, die auf
Die Funktion getContacts wird ausgelöst:
Apps Script
Node.js
Feld hinzufügen, in das Nutzer Text eingeben können
TextInput-Widget
stellt ein Feld bereit, in das Nutzende Text eingeben können. Die
Widget unterstützt Vorschläge, mit denen Nutzer einheitliche Daten eingeben können.
Aktionen, die
Actions
die ausgeführt werden, wenn eine Änderung im Texteingabefeld vorgenommen wird, z. B. wenn ein Nutzer
Text löschen.
Wenn Sie abstrakte oder unbekannte Daten von Nutzern erfassen müssen, verwenden Sie
Widget „TextInput“. Um definierte Daten von Nutzenden zu sammeln, verwenden Sie die
SelectionInput
Widget hinzufügen.
Informationen zur Verarbeitung des eingegebenen Texts finden Sie unter Von Nutzern eingegebene Informationen verarbeiten.
Das folgende Beispiel zeigt eine Karte, die aus einem TextInput-Widget besteht:
Nutzer dürfen Datum und Uhrzeit auswählen
Die
DateTimePicker-Widget
können Nutzende ein Datum, eine Uhrzeit oder beides
zu einer bestimmten Zeit. Alternativ können Nutzer das Datum und die Uhrzeit über die Auswahl festlegen. Wenn Nutzer
ungültige Datums- oder Zeitangaben angezeigt werden, wird in der Auswahl ein Fehler angezeigt, über den der Nutzer zur Eingabe aufgefordert wird.
die Informationen korrekt sind.
Informationen zur Verarbeitung der von Nutzern eingegebenen Datums- und Uhrzeitwerte finden Sie unter Von Nutzern eingegebene Informationen verarbeiten.
Im Folgenden sehen Sie eine Karte mit drei verschiedenen Arten von
DateTimePicker-Widgets:
In Karten eingegebene Daten validieren
Auf dieser Seite wird erläutert, wie du die in das action einer Karte eingegebenen Daten validieren kannst.
und Widgets.
Sie können beispielsweise prüfen, ob in ein Texteingabefeld Text eingegeben wird, der vom
oder eine bestimmte Anzahl von Zeichen enthalten.
Erforderliche Widgets für Aktionen festlegen
Im Rahmen der action der Karte
Fügt Namen von Widgets, die eine Aktion benötigt, zur requiredWidgets-Liste hinzu.
Wenn hier aufgeführte Widgets beim Aufrufen dieser Aktion keinen Wert haben, wird die Formularaktion abgebrochen.
Wenn "all_widgets_are_required": "true" für eine Aktion festgelegt ist,
auf der Karte sind für diese Aktion erforderlich.
all_widgets_are_required-Aktion in der Mehrfachauswahl festlegen
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
}
]
}
}
]
}
]
}
all_widgets_are_required-Aktion in dateTimePicker festlegen
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"
}
}
]
}
]
}
all_widgets_are_required-Aktion im Drop-down-Menü festlegen
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
}
]
}
}
]
}
]
}
Validierung für ein Texteingabe-Widget festlegen
In der textInput
Validierungsfeld des Widgets können Sie die Zeichenbeschränkung und den Eingabetyp für
dieses Texteingabe-Widgets.
Zeichenbeschränkung für ein Texteingabe-Widget festlegen
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
}
}
}
]
}
]
}
Eingabetyp für ein Texteingabe-Widget festlegen
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"
}
}
}
]
}
]
}
Fehlerbehebung
Wenn eine Google Chat App oder card gibt einen Fehler zurück. Der Parameter In der Chatoberfläche wird die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht verarbeitet werden.“ Manchmal kann die Chat-UI Es wird zwar keine Fehlermeldung angezeigt, aber die Chat-App oder die Karte zu einem unerwarteten Ergebnis führt. z. B. wird eine Kartennachricht angezeigt werden.
Auch wenn in der Chat-Benutzeroberfläche möglicherweise keine Fehlermeldung angezeigt wird, Es stehen beschreibende Fehlermeldungen und Protokolldaten zur Verfügung, mit denen Sie Fehler beheben können. wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Hilfe bei der Anzeige: Debugging und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben