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. indem sie auf eine Schaltfläche klicken oder Informationen senden.
Mit dem Card Builder können Sie JSON-Kartennachrichten für Chat-Apps erstellen und als Vorschau ansehen:
Card Builder öffnenVoraussetzungen
Schaltfläche hinzufügen
Das ButtonList-Widget enthält eine Reihe von Schaltflächen. Schaltflächen können Text, ein Symbol oder sowohl Text als auch ein Symbol anzeigen. Jede Button unterstützt eine OnClick-Aktion, die ausgeführt wird, wenn Nutzer auf die Schaltfläche klicken. Beispiel:
- Öffnen Sie einen Hyperlink mit
OpenLink, um Nutzern zusätzliche Informationen bereitzustellen. - Führen Sie einen
actionaus, der eine benutzerdefinierte Funktion ausführt, z. B. das 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 den Parameter viewType="BIRD EYE VIEW".
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 besteht. Für eine Schaltfläche wird das Feld Color verwendet, um die Hintergrundfarbe der Schaltfläche anzupassen. Die andere Schaltfläche wird über das Feld Disabled deaktiviert, wodurch der Nutzer daran gehindert wird, auf die Schaltfläche zu klicken und die Funktion auszuführen.
Schaltfläche mit einem Symbol hinzufügen
Die folgende Karte zeigt eine Karte, die aus einem ButtonList-Widget mit zwei Symbol-Button-Widgets besteht. Bei einer Schaltfläche wird das Feld knownIcon verwendet, um das in Google Chat integrierte E-Mail-Symbol anzuzeigen. Bei der anderen Schaltfläche wird über das Feld iconUrl ein Widget für benutzerdefinierte Symbole angezeigt.
Schaltfläche mit Symbol und Text hinzufügen
Im Folgenden wird eine Karte mit einem ButtonList-Widget angezeigt, das den Nutzer zum Senden einer E-Mail auffordert. Die erste Schaltfläche zeigt ein E-Mail-Symbol und die zweite Schaltfläche Text an. Der Nutzer kann entweder auf das Symbol oder die Textschaltfläche klicken, um die Funktion sendEmail auszuführen.
Auswählbare UI-Elemente hinzufügen
Das SelectionInput-Widget enthält eine Reihe auswählbarer Elemente wie Kästchen, Optionsfelder, Schalter oder ein Drop-down-Menü. Mit diesem Widget können Sie definierte und standardisierte Daten von Nutzern erfassen. Wenn Sie nicht definierte Daten von Nutzern erfassen möchten, verwenden Sie stattdessen das TextInput-Widget.
Das SelectionInput-Widget unterstützt Vorschläge, mit denen Nutzer einheitliche Daten eingeben können, und Aktionen bei Änderungen, bei denen es sich um Actions-Aktionen handelt, die ausgeführt werden, wenn eine Änderung in einem Auswahleingabefeld erfolgt, z. B. wenn ein Nutzer ein Element auswählt oder die Auswahl wieder aufhebt.
Chat-Apps können den Wert ausgewählter Elemente empfangen und verarbeiten. Weitere Informationen zum Arbeiten mit Formulareingaben finden Sie unter Formulardaten empfangen.
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 mithilfe eines SelectionInput-Widgets mit Kästchen aufgefordert wird, anzugeben, ob ein Kontakt beruflich, privat oder beides ist:
Optionsfeld hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer über ein SelectionInput-Widget mit Optionsfeldern aufgefordert wird, anzugeben, ob es sich um einen professionellen oder persönlichen Kontakt handelt:
Schalter hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, mit einem SelectionInput-Widget, das Schalter verwendet, anzugeben, ob ein Kontakt beruflich, privat oder beides ist:
Drop-down-Menü hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer mithilfe eines SelectionInput-Widgets, das ein Drop-down-Menü verwendet, anzugeben, ob es sich um einen beruflichen oder privaten Kontakt handelt:
Mehrfachauswahl-Menü hinzufügen
Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, Kontakte aus einem Mehrfachauswahlmenü auszuwählen:
Datenquellen für Menüs mit Mehrfachauswahl verwenden
Im folgenden Abschnitt wird erläutert, wie Sie Mehrfachauswahlmenüs verwenden, um Daten aus dynamischen Quellen wie einer Google Workspace-Anwendung oder einer externen Datenquelle zu füllen.
Datenquellen aus Google Workspace
Sie können Elemente für ein Mehrfachauswahl-Menü aus den folgenden Datenquellen in Google Workspace füllen:
- Google Workspace-Nutzer: Sie können nur Nutzer innerhalb derselben Google Workspace-Organisation hinzufügen.
- Chatbereiche: Der Nutzer, der Elemente in das Mehrfachauswahlmenü eingibt, kann nur Gruppenbereiche ansehen und auswählen, denen er in seiner Google Workspace-Organisation angehört.
Wenn Sie Google Workspace-Datenquellen verwenden möchten, geben Sie das Feld platformDataSource an. Im Gegensatz zu anderen Auswahleingabetypen lassen Sie SectionItem-Objekte weg, da diese Auswahlelemente dynamisch aus Google Workspace stammen.
Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Google Workspace-Nutzern.
Um Nutzer hinzuzufügen, wird commonDataSource durch die Auswahleingabe auf USER gesetzt:
JavaScript Object Notation
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Der folgende Code zeigt ein Mehrfachauswahl-Menü von Chatbereichen. Zum Ausfüllen von Gruppenbereichen wird in der Auswahleingabe das Feld hostAppDataSource angegeben. Im Mehrfachauswahl-Menü wird defaultToCurrentSpace außerdem auf true gesetzt. Dadurch wird der aktuelle Bereich zur Standardauswahl im Menü:
JavaScript Object Notation
{
"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 einer Drittanbieter- oder externen Datenquelle darstellen. Sie können beispielsweise Mehrfachauswahlmenüs verwenden, um einem Nutzer die Auswahl aus einer Liste von Leads aus einem CRM-System (Customer-Relationship-Management) zu erleichtern.
Wenn Sie eine externe Datenquelle verwenden möchten, geben Sie im Feld externalDataSource eine Funktion an, die Elemente aus der Datenquelle zurückgibt.
Um die Anfragen an eine externe Datenquelle zu reduzieren, können Sie vorgeschlagene Elemente hinzufügen, die im Mehrfachauswahlmenü angezeigt werden, bevor der Nutzer Text über das Menü eingibt. Sie können beispielsweise kürzlich gesuchte Kontakte für den Nutzer darstellen. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle einfügen möchten, geben Sie SelectionItem-Objekte an.
Der folgende Code zeigt ein Mehrfachauswahl-Menü mit Elementen aus einer externen Gruppe von Kontakten für den Nutzer. Im Menü wird standardmäßig ein Kontakt angezeigt und die Funktion getContacts wird ausgeführt, um Elemente aus der externen Datenquelle abzurufen und mit Daten zu füllen:
JavaScript Object Notation
{
"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 Elemente, die Nutzer mit der Eingabe beginnen, auch über das Mehrfachauswahlmenü automatisch vervollständigen. Wenn ein Nutzer beispielsweise beginnt, Atl für ein Menü für Städte in den USA einzugeben, kann Ihre Chat-App Atlanta automatisch vorschlagen, bevor der Nutzer die Eingabe beendet hat. Sie können bis zu 100 Elemente automatisch vervollständigen.
Zur automatischen Vervollständigung von Elementen erstellen Sie eine Funktion, die die externe Datenquelle abfragt und Elemente zurückgibt, wenn ein Nutzer das Mehrfachauswahlmenü eingibt. Die Funktion muss folgende Voraussetzungen erfüllen:
- Übergeben Sie ein Ereignisobjekt, das die Nutzerinteraktion mit dem Menü darstellt.
- Prüfen Sie, ob der Wert
invokedFunctiondes Interaktionsereignisses mit der Funktion aus dem FeldexternalDataSourceübereinstimmt. - Wenn die Funktionen übereinstimmen, werden vorgeschlagene Elemente aus der externen Datenquelle zurückgegeben. Wenn Sie Elemente basierend auf dem Nutzertyp vorschlagen möchten, rufen Sie den Wert für den Schlüssel
autocomplete_widget_queryab. Dieser Wert gibt an, was der Nutzer im Menü eingibt.
Mit dem folgenden Code werden Elemente aus einer externen Datenressource automatisch vervollständigt. Im vorherigen Beispiel schlägt die Chat-App Elemente basierend darauf vor, wann die Funktion getContacts ausgelöst wird:
Apps Script
Node.js
Feld hinzufügen, in das Nutzer Text eingeben können
Das TextInput-Widget enthält ein Feld, in das Nutzer Text eingeben können. Das Widget unterstützt Vorschläge, mit denen Nutzer einheitliche Daten eingeben können, und Aktionen bei Änderungen, also Actions-Aktionen, die ausgeführt werden, wenn eine Änderung im Texteingabefeld vorgenommen wird, z. B. wenn ein Nutzer Text hinzufügt oder löscht.
Verwenden Sie dieses TextInput-Widget, wenn Sie abstrakte oder unbekannte Daten von Nutzern erheben möchten. Verwenden Sie stattdessen das SelectionInput-Widget, um definierte Daten von Nutzern zu erfassen.
Informationen zur Verarbeitung des eingegebenen Texts finden Sie unter Formulardaten empfangen.
Das folgende Beispiel zeigt eine Karte, die aus einem TextInput-Widget besteht:
Nutzer dürfen Datum und Uhrzeit auswählen
Im DateTimePicker-Widget können Nutzer ein Datum, eine Uhrzeit oder beides eingeben. Alternativ können Nutzer das Datum und die Uhrzeit über die Auswahl festlegen. Wenn Nutzer ein ungültiges Datum oder eine ungültige Uhrzeit eingeben, wird in der Auswahl ein Fehler angezeigt, der sie zur korrekten Eingabe der Informationen auffordert.
Informationen zur Verarbeitung der vom Nutzer eingegebenen Datums- und Uhrzeitwerte finden Sie unter Formulardaten empfangen.
Die folgende Karte zeigt eine Karte, die aus drei verschiedenen Arten von DateTimePicker-Widgets besteht:
In Karten eingegebene Daten validieren
Auf dieser Seite wird erläutert, wie du die in die action und Widgets einer Karte eingegebenen Daten validieren kannst.
Sie können beispielsweise prüfen, ob ein Texteingabefeld Text enthält, der vom Nutzer eingegeben wurde oder eine bestimmte Anzahl von Zeichen enthält.
Erforderliche Widgets für Aktionen festlegen
Füge in die action-Liste der Karte die Namen von Widgets, die für eine Aktion erforderlich sind, zur requiredWidgets-Liste hinzu.
Wenn hier aufgeführte Widgets beim Aufrufen dieser Aktion keinen Wert haben, wird das Senden der Formularaktion abgebrochen.
Wenn "all_widgets_are_required": "true" für eine Aktion festgelegt ist, werden alle Widgets auf der Karte für diese Aktion benötigt.
all_widgets_are_required-Aktion in der Mehrfachauswahl festlegen
JavaScript Object Notation
{
"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
JavaScript Object Notation
{
"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
JavaScript Object Notation
{
"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
Im Validierungsfeld des textInput-Widgets können die Zeichenbeschränkung und der Eingabetyp für dieses Texteingabe-Widget angegeben werden.
Zeichenbeschränkung für ein Texteingabe-Widget festlegen
JavaScript Object Notation
{
"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
JavaScript Object Notation
{
"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 -Karte einen Fehler zurückgibt, wird in der Chat-Oberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht verarbeitet werden.“ Manchmal wird in der Chat-UI keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte liefert ein unerwartetes Ergebnis. So kann z. B. keine Kartenmeldung angezeigt werden.
Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-UI angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, um Sie beim Beheben von Fehlern zu unterstützen, wenn das Fehler-Logging für Chat-Apps aktiviert ist. Informationen zum Ansehen, Debuggen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.