Eingabeeingabe

Das SelectionInput-Widget bietet eine Reihe von auswählbaren Elementen wie Kästchen, Optionsfelder, Schalter oder ein Drop-down-Menü. Sie können dieses Widget verwenden, um definierte und standardisierte Daten von Nutzern zu erfassen. Verwenden Sie stattdessen das TextInput-Widget, um nicht definierte Daten von Nutzern zu erfassen.

Das SelectionInput-Widget unterstützt Vorschläge, die Nutzern bei der Eingabe einheitlicher Daten helfen, sowie Aktionen bei Änderung, also Actions, die ausgeführt werden, wenn in einem Auswahleingabefeld eine Änderung vorgenommen wird, z. B. wenn ein Nutzer ein Element auswählt oder die Auswahl aufhebt.

Chat-Apps können den Wert ausgewählter Elemente empfangen und verarbeiten. Weitere Informationen zum Arbeiten mit Formulareingaben finden Sie unter Formulardaten empfangen.

Beispiele

Dieser Abschnitt enthält Beispiele für Karten, auf denen das SelectionInput-Widget verwendet wird. In den Beispielen werden verschiedene Arten von Abschnittseingaben verwendet:

• Kästchen
• Optionsschaltflächen
• Schalter
• Drop-down-Menü
• Menü mit Mehrfachauswahl

Beispiel 1: Kästchen

Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer mit einem SelectionInput-Widget mit Kästchen angeben muss, ob es sich um einen professionellen und/oder persönlichen Kontakt handelt:

Beispiel 2: Optionsfelder

Im folgenden Dialogfeld wird der Nutzer aufgefordert, mit einem SelectionInput-Widget mit Optionsfeldern anzugeben, ob ein Kontakt beruflich oder privat ist:

Beispiel 3: Schalter

Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, mit einem SelectionInput-Widget, das Schalter verwendet, anzugeben, ob ein Kontakt beruflich oder privat ist:

Beispiel 4: Drop-down-Menü

Im folgenden Dialogfeld wird der Nutzer aufgefordert, mit einem SelectionInput-Widget, das ein Drop-down-Menü verwendet, anzugeben, ob es sich um einen professionellen oder privaten Kontakt handelt:

Beispiel 5: Mehrfachauswahlmenü

Im Folgenden wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, Kontakte aus einem Mehrfachauswahlmenü auszuwählen:

Zusätzliche Datenquellen für Mehrfachauswahl-Menüs

Im folgenden Abschnitt wird erläutert, wie Sie mithilfe von Mehrfachauswahlmenüs Daten aus dynamischen Quellen füllen, z. B. aus einer Google Workspace-Anwendung oder einer externen Datenquelle.

Datenquellen aus Google Workspace

Für ein Mehrfachauswahlmenü können Sie Elemente aus den folgenden Datenquellen in Google Workspace ausfüllen:

• Google Workspace-Nutzer: Sie können nur Nutzer in derselben Google Workspace-Organisation ausfüllen.
• Chatbereiche: Der Nutzer, der Elemente in das Mehrfachauswahl-Menü eingibt, kann nur Gruppenbereiche ansehen und auswählen, zu denen er innerhalb seiner Google Workspace-Organisation gehö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 Mehrfachauswahlmenü mit Google Workspace-Nutzern. Zum Füllen von Nutzern wird commonDataSource 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 Mehrfachauswahlmenü mit Chatbereichen. Zum Ausfüllen von Bereichen wird mit der Auswahl das Feld hostAppDataSource angegeben. Im Mehrfachauswahlmenü wird außerdem defaultToCurrentSpace auf true gesetzt. Dadurch wird der aktuelle Bereich zur Standardauswahl 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

Mit Mehrfachauswahlmenüs lassen sich auch Elemente aus einer Datenquelle eines Drittanbieters oder einer externen Quelle füllen. Beispielsweise können Sie mit Mehrfachauswahl-Menüs einem Nutzer die Möglichkeit geben, aus einer Liste von Leads aus einem CRM-System (Customer-Relationship-Management) eine Auswahl zu treffen.

Wenn Sie eine externe Datenquelle verwenden möchten, geben Sie im Feld externalDataSource eine Funktion an, die Elemente aus der Datenquelle zurückgibt.

Wenn Sie die Anzahl der Anfragen an eine externe Datenquelle reduzieren möchten, können Sie vorgeschlagene Elemente hinzufügen, die im Mehrfachauswahlmenü angezeigt werden, bevor der Nutzer etwas im Menü eingibt. Sie können beispielsweise kürzlich gesuchte Kontakte für den Nutzer ausfüllen. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle übernehmen möchten, geben Sie SelectionItem-Objekte an.

Der folgende Code zeigt ein Mehrfachauswahlmenü mit Elementen aus einem externen Kontaktsatz für den Nutzer. Im Menü wird standardmäßig ein Kontakt angezeigt und die Funktion getContacts ausgeführt, um Elemente aus der externen Datenquelle abzurufen und auszufüllen:

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 haben Sie außerdem die Möglichkeit, Elemente, die Nutzer beginnen, über das Mehrfachauswahlmenü automatisch zu vervollständigen. Wenn ein Nutzer beispielsweise beginnt, Atl für ein Menü einzugeben, das Städte in den USA enthält, kann Ihre Chat-App Atlanta automatisch vorschlagen, bevor der Nutzer mit der Eingabe fertig ist. Sie können bis zu 100 Elemente automatisch vervollständigen.

Zum automatischen Vervollständigen von Elementen erstellen Sie eine Funktion, die die externe Datenquelle abfragt und Elemente zurückgibt, wenn ein Nutzer eine Eingabe im Mehrfachauswahl-Menü eingibt. Die Funktion muss Folgendes tun:

• Übergeben Sie ein Ereignisobjekt, das die Nutzerinteraktion mit dem Menü darstellt.
• Prüfen Sie, ob der Wert invokedFunction des Interaktionsereignisses mit der Funktion im Feld externalDataSource übereinstimmt.
• Wenn die Funktionen übereinstimmen, werden vorgeschlagene Elemente aus der externen Datenquelle zurückgegeben. Wenn Sie Elemente basierend auf den Nutzertypen vorschlagen möchten, rufen Sie den Wert für den Schlüssel autocomplete_widget_query ab. Dieser Wert gibt an, was der Nutzer im Menü eingibt.

Mit dem folgenden Code werden Elemente aus einer externen Datenressource automatisch vervollständigt. In diesem Beispiel schlägt die Chat-App Elemente vor, je nachdem, wann die Funktion getContacts ausgelöst wird:

Apps Script

apps-script/selection-input/on-widget-update.gs

Auf GitHub ansehen

/**
 * 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

Auf GitHub ansehen

/**
 * 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
            },
          ]
        }
      }
    }
  };
}

JSON-Darstellung und -Felder

JSON-Darstellung

{ "name": string, "label": string, "type": enum (SelectionType), "items": [ { object (SelectionItem) } ], "onChangeAction": { object (Action) }, "multiSelectMaxSelectedItems": integer, "multiSelectMinQueryLength": integer, // Union field multi_select_data_source can be only one of the following: "externalDataSource": { object (Action) }, "platformDataSource": { object (PlatformDataSource) } // End of list of possible types for union field multi_select_data_source. }

Felder
name	string Der Name, der die Auswahl in einem Formulareingabeereignis identifiziert. Weitere Informationen zum Arbeiten mit Formulareingaben finden Sie unter Formulardaten empfangen.
label	string Der Text, der in der Benutzeroberfläche über dem Eingabefeld für die Auswahl angezeigt wird. Geben Sie Text ein, mit dem der Nutzer die von Ihrer App benötigten Informationen eingeben kann. Wenn Nutzende beispielsweise die Dringlichkeit eines Arbeitstickets aus einem Drop-down-Menü auswählen, könnte das Label „Dringlichkeit“ oder „Dringlichkeit auswählen“ lauten.
type	enum (SelectionType) Der Elementtyp, der Nutzern in einem SelectionInput-Widget angezeigt wird. Auswahltypen unterstützen verschiedene Arten von Interaktionen. Nutzer können beispielsweise ein oder mehrere Kästchen auswählen, aber nur einen Wert aus einem Drop-down-Menü.
items[]	object (SelectionItem) Array mit auswählbaren Elementen Beispiel: ein Array mit Optionsfeldern oder Kästchen. Unterstützt bis zu 100 Elemente.
onChangeAction	object (Action) Wenn angegeben, wird das Formular gesendet, wenn sich die Auswahl ändert. Ist dies nicht der Fall, müssen Sie eine separate Schaltfläche zum Senden des Formulars angeben. Weitere Informationen zum Arbeiten mit Formulareingaben finden Sie unter Formulardaten empfangen.
multiSelectMaxSelectedItems	integer Bei Mehrfachauswahl-Menüs die maximale Anzahl von Elementen, die ein Nutzer auswählen kann. Der Mindestwert beträgt 1 Element. Wenn nicht angegeben, werden standardmäßig 3 Elemente verwendet.
multiSelectMinQueryLength	integer Bei Mehrfachauswahl-Menüs die Anzahl der Textzeichen, die ein Nutzer eingibt, bevor die Chat-App abgefragt wird, und die vorgeschlagenen Elemente werden im Menü angezeigt. Wenn keine Vorgabe erfolgt, gilt standardmäßig 0 Zeichen für statische Datenquellen und 3 Zeichen für externe Datenquellen.
Union-Feld multi_select_data_source. Nur Chat-Apps. Bei einem Menü mit Mehrfachauswahl ist dies die Datenquelle, mit der die ausgewählten Elemente gefüllt werden. Für multi_select_data_source ist nur einer der folgenden Werte zulässig:
externalDataSource	object (Action) Eine externe Datenquelle, z. B. eine relationale Datenbank.
platformDataSource	object (PlatformDataSource) Eine Datenquelle aus Google Workspace.

SelectionType

Enums
CHECK_BOX	Eine Reihe von Kästchen. Nutzer können ein oder mehrere Kästchen auswählen.
RADIO_BUTTON	Eine Reihe von Optionsfeldern Nutzer können ein Optionsfeld auswählen.
SWITCH	Eine Reihe von Schaltern. Nutzer können einen oder mehrere Schalter aktivieren.
DROPDOWN	Ein Drop-down-Menü. Nutzer können einen Eintrag aus dem Menü auswählen.
MULTI_SELECT	Wird von Chat-Apps unterstützt, aber nicht von Google Workspace-Add-ons. Ein Mehrfachauswahlmenü für statische oder dynamische Daten. Die Nutzenden wählen in der Menüleiste ein oder mehrere Elemente aus. Nutzer können auch Werte eingeben, um dynamische Daten auszufüllen. Nutzer können beispielsweise mit der Eingabe des Namens eines Gruppenbereichs in Google Chat beginnen und das Widget schlägt den Gruppenbereich automatisch vor. Wenn Sie Elemente für ein Menü mit Mehrfachauswahl befüllen möchten, können Sie eine der folgenden Arten von Datenquellen verwenden: Statische Daten: Elemente werden im Widget als SelectionItem-Objekte angegeben. Maximal 100 Elemente. Google Workspace-Daten: Elemente werden anhand von Daten aus Google Workspace ausgefüllt, z. B. Google Workspace-Nutzer oder Google Chat-Gruppenbereiche. Externe Daten: Die Werte für die Elemente stammen aus einer externen Datenquelle außerhalb von Google Workspace. Beispiele für die Implementierung von Mehrfachauswahl-Menüs finden Sie auf der Widget-Seite SelectionInput .

SelectionItem

JSON-Darstellung
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string }

Felder
text	string Der Text, der den Artikel für Nutzer identifiziert oder beschreibt.
value	string Der mit diesem Element verknüpfte Wert. Der Client sollte diesen Wert als Formulareingabewert verwenden. Weitere Informationen zum Arbeiten mit Formulareingaben finden Sie unter Formulardaten empfangen.
selected	boolean Gibt an, ob das Element standardmäßig ausgewählt ist. Wenn für die Auswahl nur ein Wert akzeptiert wird (z. B. für Optionsfelder oder ein Drop-down-Menü), legen Sie dieses Feld nur für ein Element fest.
startIconUri	string Bei Mehrfachauswahl-Menüs die URL des Symbols, das neben dem Feld text des Elements angezeigt wird. Unterstützt PNG- und JPEG-Dateien. Muss eine HTTPS-URL sein. Beispiel: https://developers.google.com/chat/images/quickstart-app-avatar.png.
bottomText	string Bei Mehrfachauswahl-Menüs eine Textbeschreibung oder ein Label, die bzw. das unter dem Feld text des Elements angezeigt wird.

Aktion

Eine Aktion, die das Verhalten beim Senden des Formulars beschreibt. Sie können beispielsweise ein Apps Script-Skript aufrufen, um das Formular zu verarbeiten. Wird die Aktion ausgelöst, werden die Formularwerte an den Server gesendet.

JSON-Darstellung
{ "function": string, "parameters": [ { object (ActionParameter) } ], "loadIndicator": enum (LoadIndicator), "persistValues": boolean, "interaction": enum (Interaction) }

Felder
function	string Eine benutzerdefinierte Funktion, die ausgelöst wird, wenn auf das enthaltene Element geklickt oder anderweitig aktiviert wird. Informationen zur Verwendung finden Sie unter Interaktive Karten erstellen.
parameters[]	object (ActionParameter) Liste der Aktionsparameter.
loadIndicator	enum (LoadIndicator) Gibt die Ladeanzeige an, die die Aktion anzeigt, während der Aufruf an die Aktion ausgeführt wird.
persistValues	boolean Gibt an, ob Formularwerte nach der Aktion erhalten bleiben. Der Standardwert ist false. Beim Wert true bleiben Formularwerte erhalten, nachdem die Aktion ausgelöst wurde. Damit der Nutzer Änderungen vornehmen kann, während die Aktion verarbeitet wird, setzen Sie LoadIndicator auf NONE. Für Kartennachrichten in Chat-Apps müssen Sie auch ResponseType der Aktion auf UPDATE_MESSAGE setzen und denselben Wert cardId wie auf der Karte verwenden, die die Aktion enthielt. Bei false werden die Formularwerte beim Auslösen der Aktion gelöscht. Um zu verhindern, dass der Nutzer Änderungen vornimmt, während die Aktion verarbeitet wird, setzen Sie LoadIndicator auf SPINNER.
interaction	enum (Interaction) Optional. Erforderlich beim Öffnen eines Dialogfelds. Was Sie als Reaktion auf eine Interaktion mit einem Nutzer tun sollten, z. B. wenn er auf eine Schaltfläche in einer Nachrichtennachricht klickt. Wenn keine Angabe erfolgt, führt die Anwendung wie gewohnt ein action aus, z. B. das Öffnen eines Links oder das Ausführen einer Funktion. Durch Angabe eines interaction kann die App auf spezielle interaktive Weise reagieren. Wenn Sie beispielsweise interaction auf OPEN_DIALOG setzen, kann von der Anwendung ein Dialog geöffnet werden. Wenn dieses Flag angegeben ist, wird keine Ladeanzeige angezeigt. Wird von Chat-Apps unterstützt, aber nicht von Google Workspace-Add-ons. Wenn das Attribut für ein Add-on angegeben ist, wird die gesamte Karte entfernt und im Client wird nichts angezeigt.

ActionParameter

Liste der Zeichenfolgenparameter, die beim Aufrufen der Aktionsmethode angegeben werden sollen. Stellen Sie sich beispielsweise drei Schlummertasten vor: „Jetzt schlummern“, „Ein Tag zurückstellen“ oder „Nächste Woche schlummern“. Sie können action method = snooze() verwenden und den Schlummertyp und die Schlummerzeit in der Liste der Stringparameter übergeben.

Weitere Informationen finden Sie unter CommonEventObject.

JSON-Darstellung
{ "key": string, "value": string }

Felder
key	string Der Name des Parameters für das Aktionsskript.
value	string Wert des Parameters.

LoadIndicator

Gibt die Ladeanzeige an, die die Aktion anzeigt, während der Aufruf an die Aktion ausgeführt wird.

Enums
SPINNER	Ein rotierendes Ladesymbol zeigt an, dass Inhalte geladen werden.
NONE	Es wird nichts angezeigt.

Interaktion

Optional. Erforderlich beim Öffnen eines Dialogfelds.

Was Sie als Reaktion auf eine Interaktion mit einem Nutzer tun sollten, z. B. wenn er auf eine Schaltfläche in einer Nachrichtennachricht klickt.

Wenn keine Angabe erfolgt, führt die Anwendung wie gewohnt ein action aus, z. B. das Öffnen eines Links oder das Ausführen einer Funktion.

Durch Angabe eines interaction kann die App auf spezielle interaktive Weise reagieren. Wenn Sie beispielsweise interaction auf OPEN_DIALOG setzen, kann von der Anwendung ein Dialog geöffnet werden.

Wenn dieses Flag angegeben ist, wird keine Ladeanzeige angezeigt.

Wird von Chat-Apps unterstützt, aber nicht von Google Workspace-Add-ons. Wenn das Attribut für ein Add-on angegeben ist, wird die gesamte Karte entfernt und im Client wird nichts angezeigt.

Enums
INTERACTION_UNSPECIFIED	Standardwert. action wird wie gewohnt ausgeführt.
OPEN_DIALOG	Öffnet ein Dialogfeld, eine kartenbasierte Oberfläche im Fenstermodus, über die Chat-Apps mit Nutzern interagieren. Dies wird nur von Chat-Apps unterstützt, wenn auf eine Schaltfläche auf Nachrichten geklickt wird. Wird von Google Workspace-Add-ons nicht unterstützt. Wenn das Attribut für ein Add-on angegeben ist, wird die gesamte Karte entfernt und im Client wird nichts angezeigt.

Fehlerbehebung

Wenn eine Google Chat-App oder -Karte einen Fehler zurückgibt, wird in der Chat-Oberfläche die Meldung „Ein Fehler ist aufgetreten“ oder „Anfrage kann nicht verarbeitet werden“ angezeigt. Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, die Chat-App oder -Karte aber zu einem unerwarteten Ergebnis führt, z. B. wird keine Kartennachricht angezeigt.

Obwohl eine Fehlermeldung möglicherweise nicht in der Chat-Benutzeroberfläche angezeigt wird, stehen beschreibende Fehlermeldungen und Protokolldaten zur Verfügung, mit denen Sie Fehler beheben können, wenn die Fehlerprotokollierung für Chat-Apps aktiviert ist. Weitere Informationen finden Sie im Hilfeartikel Fehler in Google Chat beheben.