Interaktive UI-Elemente zu Karten hinzufügen

Auf dieser Seite wird beschrieben, wie Sie Widgets und UI-Elemente zu Karten hinzufügen, damit Nutzer mit Ihrer Google Chat-App interagieren können, z. B. durch Klicken auf eine Schaltfläche oder Senden von Informationen.

Chat-Apps können die folgenden Chat-Schnittstellen verwenden, um interaktive Karten zu erstellen:

• Nachrichten, die eine oder mehrere Karten enthalten.
• Startseiten: Eine Karte, die auf dem Tab Startseite in Direktnachrichten mit der Chat-App angezeigt wird.
• Dialogfelder, d. h. Karten, die in einem neuen Fenster über Nachrichten und Startseiten geöffnet werden.

Wenn Nutzer mit Karten interagieren, können Chat-Apps die empfangenen Daten verwenden, um sie entsprechend zu verarbeiten und darauf zu reagieren. Weitere Informationen finden Sie unter Informationen von Google Chat-Nutzern erfassen und verarbeiten.

Mit dem Card Builder können Sie Nachrichten und Benutzeroberflächen für Chat-Apps entwerfen und in der Vorschau ansehen:

Vorbereitung

Eine Google Chat-App, die so konfiguriert ist, dass sie Nutzerinteraktionen empfangen und darauf reagieren kann. Wenn Sie eine interaktive Chat-App erstellen möchten, führen Sie eine der folgenden Kurzanleitungen aus, je nachdem, welche Anwendungsarchitektur Sie verwenden möchten:

• HTTP-Dienst mit Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Cloud Pub/Sub

Button hinzufügen

Im ButtonList-Widget wird eine Reihe von Schaltflächen angezeigt. Auf Schaltflächen können Text, ein Symbol oder beides angezeigt werden. 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 action aus, der eine benutzerdefinierte Funktion ausführt, z. B. einen API-Aufruf.

Aus Gründen der Barrierefreiheit unterstützen Schaltflächen Alternativtext.

Schaltfläche hinzufügen, mit der eine benutzerdefinierte Funktion ausgeführt wird

Im Folgenden sehen Sie eine Karte, die aus einem ButtonList-Widget mit zwei Schaltflächen besteht. Über eine Schaltfläche wird die Google Chat-Entwicklerdokumentation 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".

Schaltfläche im Material Design-Stil hinzufügen

Im Folgenden sehen Sie eine Reihe von Schaltflächen in verschiedenen Material Design-Schaltflächenstilen.

Wenn Sie den Material Design-Stil anwenden möchten, geben Sie das Attribut „color“ nicht an.

Button mit benutzerdefinierter Farbe und deaktivierten Button hinzufügen

Sie können verhindern, dass Nutzer auf eine Schaltfläche klicken, indem Sie "disabled": "true" festlegen.

Im Folgenden wird eine Karte mit einem ButtonList-Widget mit zwei Schaltflächen angezeigt. Bei einem Button wird das Feld Color verwendet, um die Hintergrundfarbe des Buttons anzupassen. Der andere Button wird mit dem Feld Disabled deaktiviert, sodass der Nutzer nicht darauf klicken und die Funktion ausführen kann.

Schaltfläche mit Symbol hinzufügen

Im Folgenden wird eine Karte mit einem ButtonList-Widget und zwei Button-Symbol-Widgets angezeigt. Eine Schaltfläche verwendet das Feld knownIcon, um das integrierte E-Mail-Symbol von Google Chat anzuzeigen. Die andere Schaltfläche verwendet das Feld iconUrl, um ein benutzerdefiniertes Symbol-Widget anzuzeigen.

Button mit Symbol und Text hinzufügen

Im Folgenden wird eine Karte mit einem ButtonList-Widget angezeigt, das den Nutzer auffordert, eine E-Mail zu senden. Die erste Schaltfläche zeigt ein E-Mail-Symbol und die zweite Schaltfläche zeigt Text an. Der Nutzer kann entweder auf das Symbol oder auf die Textschaltfläche klicken, um die Funktion sendEmail auszuführen.

Schaltfläche für einen minimierbaren Bereich anpassen

Passen Sie die Schaltfläche an, mit der Abschnitte innerhalb einer Karte minimiert und maximiert werden. Wählen Sie aus einer Reihe von Symbolen oder Bildern aus, um den Inhalt des Abschnitts visuell darzustellen. So können Nutzer die Informationen leichter verstehen und damit interagieren.

Dreipunkt-Menü hinzufügen

Overflow menu kann in Chatkarten verwendet werden, um zusätzliche Optionen und Aktionen anzubieten. So können Sie mehr Optionen einfügen, ohne die Oberfläche der Karte zu überladen, und sorgen für ein übersichtliches und organisiertes Design.

Chip-Liste hinzufügen

Das Widget ChipList bietet eine vielseitige und visuell ansprechende Möglichkeit, Informationen anzuzeigen. Verwenden Sie Chip-Listen, um Tags, Kategorien oder andere relevante Daten darzustellen. So können Nutzer leichter in Ihren Inhalten navigieren und mit ihnen interagieren.

Informationen von Nutzern erheben

In diesem Abschnitt wird erläutert, wie Sie Widgets hinzufügen können, die Informationen wie Text oder Auswahlen erfassen.

Informationen zum Verarbeiten von Nutzereingaben finden Sie unter Informationen von Google Chat-Nutzern erfassen und verarbeiten.

Text erfassen

Das TextInput-Widget bietet ein Feld, in das Nutzer Text eingeben können. Das Widget unterstützt Vorschläge, die Nutzern helfen, einheitliche Daten einzugeben, und On-Change-Aktionen, d. h. Actions, die ausgeführt werden, wenn eine Änderung im Texteingabefeld auftritt, z. B. wenn ein Nutzer Text hinzufügt oder löscht.

Wenn Sie abstrakte oder unbekannte Daten von Nutzern erfassen müssen, verwenden Sie dieses TextInput-Widget. Wenn Sie bestimmte Daten von Nutzern erfassen möchten, verwenden Sie stattdessen das Widget SelectionInput.

Das folgende Beispiel zeigt eine Karte mit einem TextInput-Widget:

Datums- oder Uhrzeitangaben erfassen

Mit dem DateTimePicker-Widget können Nutzer ein Datum, eine Uhrzeit oder beides eingeben. Alternativ können Nutzer die Auswahl verwenden, um Datum und Uhrzeit auszuwählen. Wenn Nutzer ein ungültiges Datum oder eine ungültige Uhrzeit eingeben, wird eine Fehlermeldung angezeigt, in der sie aufgefordert werden, die Informationen korrekt einzugeben.

Im Folgenden wird eine Karte mit drei verschiedenen Arten von DateTimePicker-Widgets angezeigt:

Nutzer Elemente auswählen lassen

Das SelectionInput-Widget bietet eine Reihe von auswählbaren Elementen, z. B. 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 erheben möchten, verwenden Sie stattdessen das Widget TextInput.

Das Widget SelectionInput unterstützt Vorschläge, die Nutzern helfen, einheitliche Daten einzugeben, und On-Change-Aktionen, d. h. Actions, die ausgeführt werden, wenn eine Änderung in einem Auswahleingabefeld auftritt, 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 Von Nutzern eingegebene Informationen verarbeiten.

In diesem Abschnitt finden Sie Beispiele für Karten, die das Widget SelectionInput verwenden. In den Beispielen werden verschiedene Arten von Abschnittseingaben verwendet:

• Kästchen
• Optionsfelder
• Schalter
• Drop-down-Menü
• Menü für die Mehrfachauswahl

Kästchen hinzufügen

Im Folgenden sehen Sie eine Karte, auf der der Nutzer angeben soll, ob ein Kontakt beruflich, privat oder beides ist. Dazu wird ein SelectionInput-Widget mit Kästchen verwendet:

Optionsfeld hinzufügen

Im Folgenden wird eine Karte angezeigt, auf der der Nutzer gefragt wird, ob ein Kontakt beruflich oder privat ist. Dazu wird ein SelectionInput-Widget mit Optionsfeldern verwendet:

Schalter hinzufügen

Im Folgenden wird eine Karte angezeigt, auf der der Nutzer aufgefordert wird, anzugeben, ob ein Kontakt beruflich, privat oder beides ist. Dazu wird ein SelectionInput-Widget mit Schaltern verwendet:

Drop-down-Menü hinzufügen

Im Folgenden wird eine Karte angezeigt, auf der der Nutzer mit einem SelectionInput-Widget, das ein Drop-down-Menü verwendet, angeben soll, ob ein Kontakt beruflich oder privat ist:

Drop-down-Menüs dynamisch füllen

Verfügbar für Google Chat-Apps.

Sie können Elemente für ein Drop-down-Menü dynamisch aus Datenquellen in Google Workspace oder aus einer externen Datenquelle füllen. Wenn Sie dynamische Datenquellen verwenden möchten, geben Sie das Feld dataSourceConfigs an, das ein Array von DataSourceConfig-Objekten ist. Jeder DataSourceConfig kann entweder einen platformDataSource oder einen remoteDataSource enthalten. Derzeit wird nur ein DataSourceConfig unterstützt.

Elemente aus Google Workspace einfügen

Wenn Sie Elemente aus Google Workspace-Datenquellen wie Google Workspace-Nutzern einfügen möchten, geben Sie das Feld platformDataSource in einem DataSourceConfig an. Im Gegensatz zur Verwendung von statischen items lassen Sie SelectionItem-Objekte weg, da diese Auswahlelemente dynamisch aus Google Workspace stammen.

Der folgende Code zeigt ein Drop-down-Menü, das Google Workspace-Nutzer enthält:

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

Elemente aus einer externen Datenquelle einfügen

Wenn Sie Elemente aus einer Drittanbieter- oder externen Datenquelle, z. B. einem CRM-System (Customer Relationship Management), einfügen möchten, verwenden Sie das Feld remoteDataSource in einem DataSourceConfig, um eine Funktion anzugeben, die Elemente aus der Datenquelle zurückgibt.

Der folgende Code zeigt ein Drop-down-Menü, das Elemente aus einer externen Gruppe von Kontakten füllt, indem die Funktion getCrmLeads ausgeführt wird:

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Wenn Sie die Anzahl der Anfragen an eine dynamische Datenquelle reduzieren möchten, können Sie vorgeschlagene Elemente einfügen, die im Drop-down-Menü angezeigt werden, bevor Nutzer etwas eingeben. Sie können das Drop-down-Menü auch so konfigurieren, dass Elemente basierend auf der Eingabe der Nutzer automatisch vervollständigt werden. Legen Sie dazu minCharactersTrigger in DataSourceConfig fest. Wenn ein Nutzer mindestens die in minCharactersTrigger angegebene Anzahl von Zeichen eingibt, wird die in remoteDataSource angegebene Funktion ausgelöst. Das an Ihre Funktion übergebene Ereignisobjekt enthält die Eingabe des Nutzers im Schlüssel autocomplete_widget_query.

Menü mit Mehrfachauswahl hinzufügen

Im Folgenden wird eine Karte angezeigt, auf der der Nutzer aufgefordert wird, Kontakte aus einem Mehrfachauswahlmenü auszuwählen:

Sie können Elemente für ein Menü mit Mehrfachauswahl 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 im Menü zur Mehrfachauswahl eingibt, kann nur Bereiche sehen und auswählen, zu denen er in seiner Google Workspace-Organisation gehört.

Wenn Sie Google Workspace-Datenquellen verwenden möchten, geben Sie das Feld platformDataSource an. Im Gegensatz zu anderen Auswahl-Eingabetypen lassen Sie SelectionItem-Objekte weg, da diese Auswahlelemente dynamisch aus Google Workspace stammen.

Der folgende Code zeigt ein Menü zur Mehrfachauswahl von Google Workspace-Nutzern. Um Nutzer hinzuzufügen, wird commonDataSource in der Auswahleingabe auf USER gesetzt:

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

Der folgende Code zeigt ein Mehrfachauswahlmenü für Chatbereiche. Um Leerzeichen zu füllen, wird in der Auswahleingabe das Feld hostAppDataSource angegeben. Im Mehrfachauswahlmenü wird außerdem defaultToCurrentSpace auf true gesetzt, wodurch der aktuelle Space zur Standardauswahl im Menü wird:

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

Menüs mit Mehrfachauswahl können auch Elemente aus einer Drittanbieter- oder externen Datenquelle enthalten. Sie können beispielsweise Menüs mit Mehrfachauswahl verwenden, um einem Nutzer die Auswahl aus einer Liste von Verkaufsleads aus einem CRM-System (Customer Relationship Management) zu ermöglichen.

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 einfügen, die im Menü für die Mehrfachauswahl angezeigt werden, bevor Nutzer etwas eingeben. Sie können beispielsweise die zuletzt gesuchten Kontakte für den Nutzer ausfüllen. Wenn Sie vorgeschlagene Elemente aus einer externen Datenquelle einfügen möchten, geben Sie SelectionItem-Objekte an.

Das folgende Codebeispiel zeigt ein Menü mit Mehrfachauswahl, das Elemente aus einer externen Datenquelle abfragt und einfügt:

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

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

.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

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

Vorgeschlagene Elemente aus einer dynamischen Datenquelle einfügen

Bei externen Datenquellen können Sie auch Elemente automatisch vervollständigen und vorschlagen, die Nutzer in einem Mehrfachauswahl- oder Drop-down-Menü eingeben. Wenn ein Nutzer beispielsweise Atl für ein Menü eingibt, das Städte in den USA enthält, kann Ihre Chat-App Atlanta automatisch vorschlagen, bevor der Nutzer die Eingabe beendet hat. Sie können bis zu 100 Artikel vorschlagen.

Damit vorgeschlagene Elemente zurückgegeben werden, muss die Funktion, die die externe Datenquelle abfragt, Folgendes tun:

1. Ein Ereignisobjekt verarbeiten, das die Chat-App empfängt, wenn Nutzer etwas in das Menü eingeben.
2. Rufen Sie aus dem Ereignisobjekt den Wert ab, den der Nutzer eingibt. Dieser wird im Feld event.commonEventObject.parameters["autocomplete_widget_query"] dargestellt.
3. Fragen Sie die Datenquelle mit dem vom Nutzer eingegebenen Wert ab, um eine oder mehrere SelectionItems zu erhalten, die dem Nutzer vorgeschlagen werden sollen.
4. Geben Sie vorgeschlagene Elemente zurück, indem Sie die Aktion RenderActions mit einem modifyCard-Objekt zurückgeben.

Das folgende Codebeispiel zeigt, wie eine Chat-App Elemente im Mehrfachauswahlmenü auf einer Karte dynamisch vorschlägt. Wenn ein Nutzer etwas in das Menü eingibt, fragt die im Feld externalDataSource des Widgets angegebene Funktion oder der Endpunkt eine externe Datenquelle ab und schlägt Elemente vor, die der Nutzer auswählen kann:

/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("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 selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(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 Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("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 selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

In Karten eingegebene Daten validieren

Auf dieser Seite wird erläutert, wie Sie Daten validieren, die in die action und Widgets einer Karte eingegeben wurden. Sie können beispielsweise prüfen, ob in ein Texteingabefeld Text vom Nutzer eingegeben wurde oder ob es eine bestimmte Anzahl von Zeichen enthält.

Erforderliche Widgets für Aktionen festlegen

Fügen Sie als Teil der action der Karte die Namen der Widgets, die eine Aktion benötigt, der Liste requiredWidgets hinzu.

Wenn eines der hier aufgeführten Widgets beim Aufrufen dieser Aktion keinen Wert hat, wird die Übermittlung der Formularaktion abgebrochen.

Wenn "allWidgetsAreRequired": true für eine Aktion festgelegt ist, sind alle Widgets in der Karte für diese Aktion erforderlich.

allWidgetsAreRequired-Aktion in der Mehrfachauswahl festlegen

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "allWidgetsAreRequired": 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
              }
            ]
          }
        }
      ]
    }
  ]
}

allWidgetsAreRequired-Aktion in dateTimePicker festlegen

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

allWidgetsAreRequired-Aktion im Drop-down-Menü festlegen

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "allWidgetsAreRequired": 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 Widgets textInput können Sie die Zeichenbeschränkung und den Eingabetyp für dieses Texteingabe-Widget angeben.

Zeichenbeschränkung für ein Texteingabe-Widget festlegen

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"characterLimit": 15},
            "onChangeAction":{
              "allWidgetsAreRequired": true
            }
          }
        }
      ]
    }
  ]
}

Eingabetyp für ein Texteingabe-Widget festlegen

{
  "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": {
              "inputType": "EMAIL"
            },
            "onChangeAction": {
              "allWidgetsAreRequired": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "inputType": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "inputType": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

Fehlerbehebung

Wenn eine Google Chat-App oder Karte einen Fehler zurückgibt, wird auf der Chat-Oberfläche die Meldung „Ein Fehler ist aufgetreten“ angezeigt. oder „Ihre Anfrage kann nicht verarbeitet werden.“ Manchmal wird in der Chat-Benutzeroberfläche keine Fehlermeldung angezeigt, aber die Chat-App oder -Karte liefert ein unerwartetes Ergebnis. Beispielsweise wird eine Kartennachricht möglicherweise nicht angezeigt.

Auch wenn in der Chat-Benutzeroberfläche möglicherweise keine Fehlermeldung angezeigt wird, sind beschreibende Fehlermeldungen und Protokolldaten verfügbar, mit denen Sie Fehler beheben können, wenn das Fehler-Logging für Chat-Apps aktiviert ist. Hilfe zum Anzeigen, Debuggen und Beheben von Fehlern finden Sie unter Google Chat-Fehler beheben.

Weitere Informationen

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• DateTimePicker-Widget

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

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