Zaprojektuj interaktywną kartę lub okno

Na tej stronie wyjaśniamy, jak dodawać widżety i elementy interfejsu do wiadomości na kartach lub w oknach, aby umożliwić użytkownikom interakcję z aplikacją Google Chat, na przykład kliknięcie przycisku czy przesłanie informacji.


Projektuj karty i wyświetl ich podgląd w kreatorze kart.

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 Google Chat, postępuj zgodnie z tym quickstart.
  • Dodaj przycisk

    Widżet ButtonList wyświetla zestaw przycisków. Na przyciskach może być wyświetlany tekst, ikonę lub zarówno tekst, jak i ikonę. Każdy element Button obsługuje działanie OnClick, które wykonuje się, gdy użytkownik kliknie przycisk. Na przykład:

    • Otwórz hiperlink w elemencie OpenLink, aby przekazać użytkownikom dodatkowe informacje.
    • Uruchom action, który uruchamia funkcję niestandardową, np. wywoływanie interfejsu API.

    Na potrzeby ułatwień dostępu przyciski obsługują tekst alternatywny.

    Dodawanie przycisku, który uruchamia funkcję niestandardową

    Poniżej znajdziesz kartę składającą się z widżetu ButtonList i 2 przycisków. Przycisk One otwiera dokumentację dla deweloperów Google Chat w nowej karcie. Inny przycisk uruchamia funkcję niestandardową o nazwie goToView() i przekazuje parametr viewType="BIRD EYE VIEW".

    Dodawanie przycisku z niestandardowym kolorem i przycisku zdezaktywowanego

    Aby uniemożliwić użytkownikom klikanie przycisku, ustaw "disabled": "true".

    Poniżej widać kartę składającą się z widżetu ButtonList i 2 przycisków. Jeden przycisk używa pola Color do dostosowania koloru 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 widać kartę składającą się z widżetu ButtonList z 2 ikonami Button widżetów. Jeden przycisk używa pola knownIcon do wyświetlania ikony poczty e-mail wbudowanej w Google Chat. Drugi przycisk korzysta z pola iconUrl do wyświetlania niestandardowego widżetu z ikoną.

    Dodaj przycisk z ikoną i tekstem

    Poniżej widać kartę składającą się z widżetu ButtonList, który zachęca użytkownika do wysłania e-maila. Pierwszy przycisk ma ikonę e-maila, a drugi – tekst. Użytkownik może kliknąć ikonę lub przycisk tekstowy, aby uruchomić funkcję sendEmail.

    Dodaj elementy interfejsu, które można wybrać

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

    Widżet SelectionInput obsługuje sugestie, które ułatwiają użytkownikom wprowadzanie jednolitych danych i działania przy zmianie, czyli Actions, które są uruchamiane, gdy zachodzi zmiana w polu do wprowadzania wyboru (np. zaznaczenie lub odznaczenie elementu przez użytkownika).

    Aplikacje do obsługi czatu mogą odbierać i przetwarzać wartość wybranych elementów. Więcej informacji o pracy z danymi formularzy znajdziesz w artykule Odbieranie danych z formularzy.

    Ta sekcja zawiera przykłady kart korzystających z widżetu SelectionInput. W przykładach używane są różne typy danych wejściowych sekcji:

    Dodaj pole wyboru

    Poniżej widać okno z prośbą o podanie przez użytkownika, czy kontakt ma charakter zawodowy, prywatny czy osobisty, za pomocą widżetu SelectionInput z polami wyboru:

    Dodaj opcję

    Poniżej wyświetla się okno z prośbą o podanie przez użytkownika, czy kontakt jest zawodowy czy prywatny, za pomocą widżetu SelectionInput z przyciskami:

    Dodawanie przełącznika

    Poniżej wyświetli się okno z prośbą o podanie w widżecie SelectionInput, który używa przełączników, o określenie, czy kontakt ma charakter zawodowy, prywatny czy osobisty:

    Poniżej wyświetla się okno z prośbą o określenie, czy kontakt ma charakter służbowy czy prywatny za pomocą widżetu SelectionInput, który używa menu:

    Dodaj menu wielokrotnego wyboru

    Poniżej widać okno dialogowe z prośbą o wybranie kontaktów z menu wielokrotnego wyboru:

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

    Z tej sekcji dowiesz się, jak używać menu wyboru wielokrotnego do wypełniania danych ze źródeł dynamicznych, takich jak aplikacja Google Workspace czy zewnętrzne źródło danych.

    Źródła danych z Google Workspace

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

    • Użytkownicy Google Workspace: możesz dodać użytkowników tylko z tej samej organizacji Google Workspace.
    • Pokoje czatu: użytkownik, który wpisuje elementy w menu wyboru wielokrotnego, może tylko wyświetlać i wybierać pokoje, które należą do jego organizacji Google Workspace.

    Aby używać źródeł danych Google Workspace, musisz określić pole platformDataSource. W przeciwieństwie do innych typów danych wejściowych wyboru pomijasz obiekty SectionItem, ponieważ są one pobierane dynamicznie z Google Workspace.

    Poniższy kod przedstawia menu wielokrotnego wyboru użytkowników Google Workspace. Aby użytkownicy mogli być użytkownikami, dane wejściowe wyboru powodują ustawienie 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 pokoi czatu. Aby można było wypełniać pokoje, dane wejściowe wyboru określają pole hostAppDataSource. Menu wyboru wielokrotnego ustawia też defaultToCurrentSpace na true, co sprawia, że bieżący pokój 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 mogą też wypełniać elementy z zewnętrznego lub zewnętrznego źródła danych. Dzięki nim możesz na przykład ułatwić użytkownikowi wybór z listy potencjalnych klientów z systemu zarządzania relacjami z klientami (CRM).

    Aby użyć zewnętrznego źródła danych, za pomocą pola externalDataSource możesz określić funkcję, która zwraca elementy ze źródła danych.

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

    Poniższy kod przedstawia wielokrotne wybieranie elementów z zewnętrznego zbioru kontaktów użytkownika. W menu wyświetlany jest domyślnie 1 kontakt i uruchamia funkcję getContacts, która pobiera i uzupełnia elementy 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ć w menu wyboru wielokrotnego. Jeśli na przykład użytkownik zacznie wpisywać Atl, aby wyświetlić menu wypełniane miastami w Stanach Zjednoczonych, aplikacja Google Chat może automatycznie zasugerować wartość Atlanta, zanim użytkownik skończy pisać. Możesz automatycznie uzupełnić maksymalnie 100 elementów.

    Aby korzystać z autouzupełniania elementów, utwórz funkcję, która wysyła zapytanie do zewnętrznego źródła danych i zwraca elementy za każdym razem, gdy użytkownik wpisuje tekst w menu wyboru wielokrotnego. Ta funkcja musi:

    • Przekaż obiekt zdarzenia, który reprezentuje interakcję użytkownika z menu.
    • Sprawdź, czy wartość invokedFunction zdarzenia interakcji odpowiada funkcji określonej w polu externalDataSource.
    • Gdy funkcje się zgadzają, zwracaj sugerowane elementy z zewnętrznego źródła danych. Aby sugerować elementy na podstawie typów użytkowników, pobierz wartość klucza autocomplete_widget_query. Ta wartość odzwierciedla to, co użytkownik wpisuje w menu.

    Ten kod automatycznie uzupełnia elementy z zewnętrznego zasobu danych. W poprzednim przykładzie aplikacja Google Chat sugeruje elementy na podstawie czasu 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 udostępnia pole, w którym użytkownicy mogą wpisywać tekst. Widżet obsługuje sugestie, które ułatwiają użytkownikom wprowadzanie jednolitych danych i działania przy zmianie, czyli Actions uruchamiane, gdy w polu wprowadzania zmiany nastąpi zmiana. Przykładem może być dodanie lub usunięcie tekstu przez użytkownika.

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

    Aby dowiedzieć się, jak przetworzyć tekst wpisany przez użytkowników, przeczytaj artykuł Odbieranie danych z formularzy.

    Oto karta składająca się z widżetu TextInput:

    Pozwalaj 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 w selektorze. Jeśli użytkownicy wprowadzą nieprawidłową datę lub godzinę, w selektorze wyświetli się błąd i prośba o poprawne wpisanie informacji.

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

    Poniżej znajdziesz kartę złożoną z 3 różnych typów widżetów DateTimePicker:

    Rozwiązywanie problemów

    Gdy aplikacja lub karta Google Chat zwróci błąd, interfejs czatu wyświetli komunikat „Coś poszło nie tak” lub „Nie udało się przetworzyć Twojej prośby”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład komunikat na karcie może się nie pojawić.

    Mimo że komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci naprawić błędy występujące po włączeniu logowania błędów w aplikacjach do obsługi czatu. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i ich naprawianie.