Przejdź do głównej treści
Polski— Wybierz język
Menu

Widżety interaktywne

Lekcja 19 z 25 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Czym jest widżet ChatKit?
  2. Kontenery i komponenty
  3. Projektowanie widżetu w Kreatorze Widżetów
  4. Co zawiera szablon?
  5. Wyświetlanie widżetu z respond
  6. Pozwolenie agentowi na decyzję
  7. Lista z możliwością kliknięcia
  8. Aktualizacja widżetu podczas wyświetlania
  9. A co z klasami Python?
  10. Kiedy używać widżetu
  11. Kluczowe wnioski

Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opisywała widżety jako komponenty React pisane przez dewelopera i rejestrowane w interfejsie, wykorzystując nieistniejący moduł @openai/chatkit/react. W ChatKit widżet to deklaratywny opis, który buduje Twój serwer, a ChatKit renderuje go samodzielnie. Lekcja opiera się na Python SDK openai-chatkit w wersji 1.6.5, które buduje widżety z szablonów .widget: jego klasy Card, Text, Badge… są przestarzałe. Przykłady zostały wykonane na lokalnym serwerze ChatKit. Źródła: Widżety ChatKit · Widżety (Python SDK) · Budowanie interaktywnych odpowiedzi z widżetami · Kreator widżetów.

Czym jest widżet ChatKit?

Odpowiedź tekstowa wystarcza do wyjaśnień. Jednak aby przedstawić zamówienie, porównać trzy pakiety lub potwierdzić spotkanie, tekst szybko zamienia się w ścianę linijek, które użytkownik musi czytać ponownie. Widżety zastępują ten tekst interfejsem: kartą, listą, formularzem lub wykresem, wyświetlanym wewnątrz strumienia rozmowy.

Podejście jest deklaratywne. Twój serwer nie dostarcza ani HTML, ani komponentu React: opisuje widżet w formacie JSON, używając zamkniętego zestawu komponentów i właściwości, i wysyła go do wątku jako pełnoprawny element (WidgetItem). ChatKit rysuje go swoimi własnymi komponentami, używając kolorów motywu z poprzedniej lekcji. Wynikają z tego dwie konsekwencje:

  • Możesz używać tylko komponentów i właściwości, które zna ChatKit. W zamian renderowanie pozostaje spójne z resztą interfejsu, a żaden arbitralny HTML ani JavaScript z serwera nie trafia na stronę.
  • Widżet jest częścią historii: w kolejnych turach jest konwertowany na dane wejściowe dla modelu, który dzięki temu „widzi“, co pokazał użytkownikowi.

Kontenery i komponenty

Każdy widżet ma korzeń, wybierany spośród trzech kontenerów:

KontenerZastosowanie
CardSamodzielna treść: podsumowanie, potwierdzenie, formularz. Akceptuje status oraz przyciski potwierdzenia/anulowania pod treścią
ListViewZestaw opcji: restauracje, pliki, zamówienia. Jego dziećmi są ListViewItem, z wbudowaną funkcjonalnością „zobacz więcej“ (limit)
BasicRezerwowane dla podglądów encji wyświetlanych po najechaniu kursorem na wzmiankę

Wewnątrz składasz komponenty: tekst (Title, Text, Caption, Markdown), etykiety (Badge), układ (Row, Col, Box, Spacer, Divider), media (Image, Icon), polecenia (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, które Form może grupować), wykresy (Chart) i animacje (Transition). Strona Komponentów w Kreatorze Widżetów wymienia właściwości każdego z nich, wraz z edytorem do ich testowania.

Projektowanie widżetu w Kreatorze Widżetów

Zalecany przepływ pracy zaczyna się w Kreatorze Widżetów w ChatKit Studio. Projektujesz tam układ, wypełniasz panel danych przykładowymi wartościami, aby ocenić renderowanie, a następnie eksportujesz plik .widget. Jest to plik JSON łączący szablon, schemat oczekiwanych danych (jsonSchema) i dane przykładowe. Umieść go w systemie kontroli wersji obok kodu serwera, na przykład w folderze widgets/.

Po stronie serwera WidgetTemplate ładuje plik, a build wypełnia go rzeczywistymi danymi:

from chatkit.widgets import WidgetTemplate

order_template = WidgetTemplate.from_file("widgets/order.widget")

card = order_template.build({
    "number": "C-42",
    "status": "Shipped",
    "color": "success",
    "items": [{"name": "Keyboard", "price": "$49.90"}, {"name": "Mouse", "price": "$10.00"}],
    "total": "$59.90",
})

Ścieżka względna jest rozwiązywana względem pliku Python wywołującego from_file, a nie względem katalogu uruchomienia. build akceptuje słownik lub model Pydantic.

Co zawiera szablon?

Szablon to model Jinja produkujący JSON widżetu. Szablon karty zamówienia wygląda tak:

ORDER_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Row", "justify": "between", "align": "center", "children": [
      {"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
      {"type": "Badge", "label": {{ status | tojson }}, "color": {{ color | tojson }}}
    ]},
    {"type": "Divider"},
    {"type": "Col", "gap": 2, "children": [
      {%- for item in items %}
      {"type": "Row", "justify": "between", "children": [
        {"type": "Text", "value": {{ item.name | tojson }}},
        {"type": "Text", "value": {{ item.price | tojson }}}
      ]}{% if not loop.last %},{% endif %}
      {%- endfor %}
    ]},
    {"type": "Divider"},
    {"type": "Row", "justify": "between", "children": [
      {"type": "Text", "value": "Total", "weight": "semibold"},
      {"type": "Text", "value": {{ total | tojson }}, "weight": "semibold"}
    ]}
  ]
}
"""

order_template = WidgetTemplate({"version": "1.0", "name": "order", "template": ORDER_TEMPLATE})

Rzadko będziesz pisać szablon ręcznie, ponieważ Kreator Widżetów generuje go za Ciebie. Jednak umiejętność jego odczytania zaoszczędzi Ci czasu, gdy pojawi się pierwszy problem. Trzy uwagi:

  • Filtr tojson konwertuje każdą wartość na poprawny JSON (ciąg znaków w cudzysłowie, wartość logiczna jako true lub false) i escapuje znaki specjalne: apostrof lub cudzysłów w nazwie produktu nie zepsuje JSON-a.
  • Jinja działa w trybie ścisłym: brakujące dane powodują niepowodzenie build, zamiast produkować półpusty widżet.
  • build nie waliduje danych wobec jsonSchema. Ten schemat dokumentuje dane; jeśli pochodzą one z narzędzia lub bazy danych, zwaliduj je wcześniej, na przykład za pomocą modelu Pydantic.

Konstruktor WidgetTemplate(...) przyjmuje tę samą zawartość co już odczytany plik .widget: jest to przydatne do testów lub dla szablonu generowanego przez Twój własny kod.

Wyświetlanie widżetu z respond

Aby wysłać widżet do wątku, stream_widget produkuje odpowiednie zdarzenia ChatKit. Przekazujesz je ze swojej metody respond:

from chatkit.server import stream_widget

# W Twojej klasie ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # Twoje dane
    async for event in stream_widget(
        thread,
        card,
        copy_text="Order C-42: shipped, $59.90",
        generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
    ):
        yield event

copy_text to tekst kopiowany do schowka, gdy użytkownik kliknie przycisk kopiowania pod odpowiedzią. Serwer zapisuje widżet w samym store, jak każdy inny element nadawany.

Pozwolenie agentowi na decyzję

Najczęściej to nie Twój kod decyduje o wyświetleniu karty, lecz agent, gdy rozmowa tego wymaga. Daj mu narzędzie, które nadaje widżet za pomocą AgentContext.stream_widget: stream_agent_response, omawiane w lekcji 17, przesyła go do interfejsu w trakcie odpowiedzi.

from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext


@function_tool(description_override="Wyświetla szczegóły zamówienia jako kartę.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
    data = await get_order_data(number)  # Twój dostęp do danych
    await ctx.context.stream_widget(order_template.build(data))
    return f"Karta dla zamówienia {number} jest wyświetlana."

Dodaj narzędzie do listy tools agenta. Ciąg znaków zwracany przez narzędzie służy modelowi, który dzięki temu wie, że karta znajduje się na ekranie, i może ją skomentować, zamiast ją powtarzać.

Lista z możliwością kliknięcia

Aby zaproponować wybór, ListView prezentuje klikalne wiersze. Każdy ListViewItem może przenosić akcję, wyzwalaną kliknięciem bez konieczności wpisywania czegokolwiek przez użytkownika; następna lekcja pokaże, jak obsłużyć to po stronie serwera.

LIST_TEMPLATE = """
{
  "type": "ListView",
  "limit": 5,
  "children": [
    {%- for o in orders %}
    {
      "type": "ListViewItem",
      "key": {{ o.number | tojson }},
      "onClickAction": {"type": "order.open", "payload": {"number": {{ o.number | tojson }}}},
      "children": [
        {"type": "Col", "children": [
          {"type": "Text", "value": {{ ("Order " ~ o.number) | tojson }},
          {"type": "Caption", "value": {{ o.date | tojson }}}
        ]}
      ]
    }{% if not loop.last %},{% endif %}
    {%- endfor %}
  ]
}
"""

order_list_template = WidgetTemplate({"version": "1.0", "name": "order_list", "template": LIST_TEMPLATE})
list_widget = order_list_template.build({"orders": [{"number": "C-42", "date": "November 2"}, {"number": "C-41", "date": "October 28"}]})

Poza limitem limit ChatKit wyświetla link „zobacz więcej“.

Aktualizacja widżetu podczas wyświetlania

Widżet może ewoluować na oczach użytkownika, na przykład aby wyświetlić szkic, który model właśnie pisze. Przekaż do stream_widget generator asynchroniczny produkujący kolejne stany widżetu: ChatKit oblicza różnice i wysyła tylko to, co się zmieniło.

from collections.abc import AsyncGenerator

from chatkit.widgets import DynamicWidgetRoot, WidgetTemplate

draft_template = WidgetTemplate({
    "version": "1.0",
    "name": "draft",
    "template": """{"type": "Card", "children": [
        {"type": "Title", "value": "Draft"},
        {"type": "Text", "id": "body", "value": {{ text | tojson }}, "streaming": {{ in_progress | tojson }}}
    ]}""",
})


async def streaming_draft(chunks: AsyncGenerator[str, None]) -> AsyncGenerator[DynamicWidgetRoot, None]:
    text = ""
    async for chunk in chunks:
        text += chunk
        yield draft_template.build({"text": text, "in_progress": True})
    # Stan końcowy, gdy tekst jest kompletny
    yield draft_template.build({"text": text, "in_progress": False})

Tylko komponenty Text i Markdown z identyfikatorem id wyświetlają swoje aktualizacje w strumieniu, słowo po słowie; w przypadku innych ChatKit zastępuje zmodyfikowaną część widżetu.

A co z klasami Python?

Napotkasz, nawet w przewodnikach OpenAI, widżety budowane z klasami: Card(children=[Text(value="…")]). Nadal działają, ale SDK openai-chatkit 1.6.5 ogłasza je przestarzałymi na rzecz WidgetTemplate: ich użycie emituje ostrzeżenie wskazujące na pliki .widget. W nowym projekcie zacznij od szablonów. W istniejącym projekcie migruj we własnym tempie: ostrzeżenie niczego nie blokuje, ale przestarzała klasa może zniknąć w przyszłej wersji.

Kiedy używać widżetu

Dokumentacja wymienia typowe zastosowania:

  • zbieranie ustrukturyzowanych danych wejściowych za pomocą formularza lub prezentowanie bogatego wyniku (tabela, karta, wykres), którego tekst renderuje słabo;
  • oferowanie wyboru spośród kilku opcji;
  • łączenie widżetu z akcjami, aby zatwierdzić wybór, potwierdzić krok lub uruchomić przetwarzanie po stronie serwera;
  • towarzyszenie krótkiemu tekstowi wyjaśniającemu interaktywnym poleceniem.

Z drugiej strony, nie umieszczaj ich wszędzie. Widżet, który słowo w słowo powtarza to, co mówi tekst, nic nie wnosi, a rozmowa nasycona kartami staje się równie trudna do czytania co ściana tekstu.

Kluczowe wnioski

  • Widżet ChatKit to deklaratywny opis (JSON) budowany przez Twój serwer, a nie komponent React: ChatKit renderuje go samodzielnie
  • Trzy kontenery: Card (samodzielna treść), ListView (lista opcji), Basic (podglądy encji)
  • Projektuj w Kreatorze Widżetów, eksportuj plik .widget, ładuj go za pomocą WidgetTemplate.from_file(...), i wypełniaj za pomocą build(data); klasy Card, Text… są przestarzałe
  • Nadawaj za pomocą stream_widget z respond lub z narzędzia agenta za pomocą ctx.context.stream_widget
  • Generator asynchroniczny aktualizuje widżet na żywo; tylko Text i Markdown z id strumieniują słowo po słowie