Widżety interaktywne
Na tej stronie
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 SDKopenai-chatkitw wersji 1.6.5, które buduje widżety z szablonów.widget: jego klasyCard,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:
| Kontener | Zastosowanie |
|---|---|
Card | Samodzielna treść: podsumowanie, potwierdzenie, formularz. Akceptuje status oraz przyciski potwierdzenia/anulowania pod treścią |
ListView | Zestaw opcji: restauracje, pliki, zamówienia. Jego dziećmi są ListViewItem, z wbudowaną funkcjonalnością „zobacz więcej“ (limit) |
Basic | Rezerwowane 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
tojsonkonwertuje każdą wartość na poprawny JSON (ciąg znaków w cudzysłowie, wartość logiczna jakotruelubfalse) 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. buildnie waliduje danych wobecjsonSchema. 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); klasyCard,Text… są przestarzałe - Nadawaj za pomocą
stream_widgetzrespondlub z narzędzia agenta za pomocąctx.context.stream_widget - Generator asynchroniczny aktualizuje widżet na żywo; tylko
TextiMarkdownzidstrumieniują słowo po słowie