Zaprojektuj interaktywną kartę lub okno

Z tego artykułu dowiesz się, jak dodawać widżety i elementy interfejsu do kart i komunikatów, aby użytkownicy mogli korzystać z aplikacji Google Chat, np. przez kliknięcie przycisku czy przesłanie informacji.

Za pomocą kreatora kart możesz zaprojektować i wyświetlić podgląd wiadomości kart JSON przeznaczonych do aplikacji Google Chat:

Otwórz Kreator kart

Wymagania wstępne

  • Konto Google Workspace z dostępem do Google Chat.
  • Opublikowana aplikacja Google Chat. Aby utworzyć aplikację do obsługi czatu, skorzystaj z tego quickstart.

    • Dodaj przycisk

    Widżet ButtonList wyświetla zestaw przycisków. Na przyciskach może być tekst, ikona lub zarówno tekst, jak i ikona. Każda Button obsługuje działanie OnClick, które ma miejsce, gdy użytkownik kliknie przycisk. Na przykład:

    • Otwórz hiperlink z adresem OpenLink, aby udostępnić użytkownikom dodatkowe informacje.
    • Uruchom action, który uruchamia funkcję niestandardową, np. wywołanie interfejsu API.

    W przypadku ułatwień dostępu przyciski obsługują tekst alternatywny.

    Dodaj przycisk uruchamiający funkcję niestandardową

    Poniżej znajduje się karta zawierająca widżet ButtonList z 2 przyciskami. Jeden przycisk otwiera dokumentację dla deweloperów Google Chat w nowej karcie. Drugi przycisk uruchamia funkcję niestandardową o nazwie goToView() i przekazuje parametr viewType="BIRD EYE VIEW".

    Dodaj przycisk z niestandardowym kolorem i nieaktywny przycisk

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

    Poniżej wyświetli się karta składająca się z widżetu ButtonList z 2 przyciskami. Za pomocą pola Color jednego z przycisków można dostosować kolor tła przycisku. Drugi przycisk jest dezaktywowany w polu Disabled, co uniemożliwia użytkownikowi kliknięcie przycisku i wykonanie funkcji.

    Dodawanie przycisku z ikoną

    Poniżej wyświetli się karta składająca się z widżetu ButtonList z 2 widżetami ikon Button. Jeden z przycisków wyświetla ikonę wbudowanej poczty e-mail w Google Chat za pomocą pola knownIcon. Drugi przycisk korzysta z pola iconUrl do wyświetlania niestandardowego widżetu z ikoną.

    Dodaj przycisk z ikoną i tekstem

    Poniżej wyświetli się karta zawierająca widżet ButtonList, który zachęca użytkownika do wysłania e-maila. Pierwszy to ikona e-maila, a drugi tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby uruchomić funkcję sendEmail.

    Dodawanie elementów interfejsu do wyboru

    Widżet SelectionInput zawiera zestaw elementów do wyboru, takich jak pola wyboru, opcje, przełączniki i menu. Możesz używać tego widżetu do zbierania zdefiniowanych i ustandaryzowanych danych o użytkownikach. Aby zbierać od użytkowników niezdefiniowane dane, użyj widżetu TextInput.

    Widżet SelectionInput obsługuje sugestie, które ułatwiają użytkownikom wprowadzanie jednolitych danych, i działania związane ze zmianą – Actions wywoływane, gdy zmiana w polu do wprowadzania danych, na przykład wybranie lub odznaczenie elementu przez użytkownika.

    Aplikacje do obsługi czatu mogą otrzymywać i przetwarzać wartość wybranych elementów. Szczegółowe informacje o pracy z danymi wejściowymi formularza znajdziesz w artykule Odbieranie danych formularza.

    W tej sekcji znajdziesz przykłady kart, które korzystają z widżetu SelectionInput. W przykładach używane są różne typy danych wejściowych sekcji:

    Dodaj pole wyboru

    Poniżej wyświetla się okno z prośbą o wskazanie, czy kontakt jest służbowy, prywatny, czy jedno i drugi, za pomocą widżetu SelectionInput z polami wyboru:

    Dodaj opcję

    Poniżej wyświetla się okno z prośbą o wskazanie, czy kontakt jest służbowy czy osobisty, w widżecie SelectionInput z przyciskami opcji:

    Dodaj przełącznik

    Poniżej wyświetla się okno z prośbą o wskazanie w widżecie SelectionInput z przełącznikami, czy kontakt jest zawodowy, prywatny czy też oba te rodzaje kontaktów:

    Poniżej wyświetla się okno z prośbą o wskazanie użytkownika w widżecie SelectionInput korzystającym z menu, czy jest to kontakt służbowy, czy osobisty:

    Dodaj menu wielokrotnego wyboru

    Poniżej wyświetli się okno z prośbą o wybranie kontaktów z menu wielokrotnego wyboru:

    Użyj źródeł danych w menu wielokrotnego wyboru

    W tej sekcji wyjaśniamy, jak używać menu wielokrotnego wyboru do wypełniania danych ze źródeł dynamicznych, takich jak aplikacja Google Workspace lub zewnętrzne źródło danych.

    Źródła danych z Google Workspace

    Elementy menu wielokrotnego wyboru możesz uzupełnić z tych źródeł danych w Google Workspace:

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

    Aby używać źródeł danych Google Workspace, określ pole platformDataSource. W przeciwieństwie do innych typów danych wejściowych wyboru obiekty SectionItem są pomijane, ponieważ te elementy są pozyskiwane dynamicznie z Google Workspace.

    Poniższy kod przedstawia menu wielokrotnego wyboru z użytkownikami Google Workspace. Aby zapełnić użytkowników, pole wyboru ustawia wartość commonDataSource na USER:

    JSON

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

    Poniższy kod przedstawia menu wielokrotnego wyboru z pokojami czatu. Aby można było wstawić spacje, pole wyboru określa pole hostAppDataSource. Menu wyboru wielokrotnego ustawia też defaultToCurrentSpace na true, co oznacza, że bieżący obszar jest domyślnym wyborem w menu:

    JSON

    {
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}
    Źródła danych spoza Google Workspace

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

    Aby użyć zewnętrznego źródła danych, w polu externalDataSource określ funkcję, która zwraca elementy ze źródła danych.

    Aby zmniejszyć liczbę żądań wysyłanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu wielokrotnego wyboru, zanim użytkownicy w nim wpiszą. Możesz na przykład wypełnić ostatnio wyszukiwane kontakty użytkownika. Aby wypełniać sugerowane elementy z zewnętrznego źródła danych, określ obiekty SelectionItem.

    Poniższy kod pokazuje menu wielokrotnego wyboru z elementami z zewnętrznego zbioru kontaktów użytkownika. W menu domyślnie wyświetla się 1 kontakt i uruchamia funkcję getContacts do pobierania i wypełniania elementów z zewnętrznego źródła danych:

    JSON

    {
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

    W przypadku zewnętrznych źródeł danych możesz też automatycznie uzupełniać elementy, które użytkownicy zaczynają wpisywać, korzystając z menu wyboru wielokrotnego. Jeśli na przykład użytkownik zacznie wpisywać Atl, aby wyświetlić menu z miastami w Polsce, aplikacja Google Chat może automatycznie zasugerować Atlanta, zanim użytkownik skończy pisać. Możesz użyć autouzupełniania maksymalnie 100 elementów.

    Aby automatycznie uzupełniać elementy, tworzysz funkcję, która wysyła zapytania do zewnętrznego źródła danych i zwraca elementy za każdym razem, gdy użytkownik wpisze tekst w menu wyboru wielokrotnego. Funkcja musi:

    • Przekazuj obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
    • Sprawdź, czy wartość invokedFunction zdarzenia interakcji pasuje do funkcji z pola externalDataSource.
    • Gdy funkcje są zgodne, zwracają sugerowane elementy z zewnętrznego źródła danych. Aby sugerować elementy na podstawie wpisanego przez użytkownika hasła, pobierz wartość klucza autocomplete_widget_query. Ta wartość odzwierciedla to, co użytkownik wpisuje w menu.

    Podany niżej kod automatycznie uzupełnia elementy z zewnętrznego zasobu danych. Korzystając z poprzedniego przykładu, aplikacja Google Chat sugeruje elementy na podstawie chwili wywołania funkcji getContacts:

    Google Apps Script

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

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Node.js

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

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Dodaj pole, w którym użytkownik może wpisywać tekst

    Widżet TextInput zawiera pole, w którym użytkownicy mogą wpisywać tekst. Widżet obsługuje sugestie, które ułatwiają użytkownikom wpisywanie jednolitych danych, oraz działania Actions wykonywane po wprowadzeniu zmiany w polu do wprowadzania tekstu, np. gdy użytkownik doda lub usunie tekst.

    Jeśli chcesz zbierać abstrakcyjne lub nieznane dane od użytkowników, użyj tego widżetu TextInput. Aby zbierać określone dane od użytkowników, użyj widżetu SelectionInput.

    Informacje o przetwarzaniu tekstu wpisywanego przez użytkowników znajdziesz w artykule Odbieranie danych formularza.

    Oto karta zawierająca widżet TextInput:

    Pozwól użytkownikowi wybrać datę i godzinę

    Widżet DateTimePicker pozwala użytkownikom wpisać datę, godzinę lub zarówno datę, jak i godzinę. Użytkownicy mogą też wybierać daty i godziny za pomocą selektora. Jeśli użytkownicy wpiszą nieprawidłową datę lub godzinę, selektor wyświetli błąd z prośbą o prawidłowe wpisanie informacji.

    Informacje o przetwarzaniu wartości daty i godziny wpisanych przez użytkowników znajdziesz w artykule Odbieranie danych formularza.

    Zobaczysz kartę zawierającą 3 różne typy widżetów DateTimePicker:

    Weryfikuj dane wprowadzane na kartach

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

    Ustaw wymagane widżety działań

    W action na karcie dodaj nazwy widżetów, które są potrzebne do wykonania działania, do listy requiredWidgets.

    Jeśli wymienione tu widżety nie mają wartości po wywołaniu tego działania, przesyłanie działania formularza zostanie anulowane.

    Jeśli działanie jest ustawione na "all_widgets_are_required": "true", wymagane są wszystkie widżety na karcie.

    Ustaw działanie all_widgets_are_required w wyborze wielokrotnym

    JSON

    {
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "value": "contact-1",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 1",
                "bottomText": "Contact one description",
                "selected": false
              },
              {
                "value": "contact-2",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 2",
                "bottomText": "Contact two description",
                "selected": false
              },
              {
                "value": "contact-3",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 3",
                "bottomText": "Contact three description",
                "selected": false
              },
              {
                "value": "contact-4",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 4",
                "bottomText": "Contact four description",
                "selected": false
              },
              {
                "value": "contact-5",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 5",
                "bottomText": "Contact five description",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

    Ustawianie działania all_widgets_are_required w elemencie dateTimePicker

    JSON

    {
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}

    Ustaw w menu działanie all_widgets_are_required

    JSON

    {
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

    Ustawianie weryfikacji widżetu do wprowadzania tekstu

    W polu weryfikacji widżetu textInput można określić limit znaków i typ danych wejściowych tego widżetu.

    Ustawianie limitu znaków dla widżetu wpisywania tekstu

    JSON

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

    Ustawianie typu danych wejściowych widżetu do wprowadzania tekstu

    JSON

    {
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

    Rozwiązywanie problemów

    Gdy aplikacja lub karta w Google Chat zwróci błąd, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. Czasami w UI Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład wiadomość na karcie.

    Mimo że komunikat o błędzie może nie być wyświetlany w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane logów, które pomogą Ci w naprawianiu błędów, gdy logowanie błędów w aplikacjach Google Chat jest włączone. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami w Google Chat.