Widgetar interaktiva
På denna sida
Lektionen omskriven den 3 november 2026. Den tidigare versionen beskrev widgetar som React-komponenter skrivna av utvecklaren och registrerade i gränssnittet, med hjälp av en icke-existerande modul
@openai/chatkit/react. I ChatKit är en widget en deklarativ beskrivning som din server bygger och som ChatKit sedan renderar själv. Denna lektion följer Python SDK:topenai-chatkitversion 1.6.5, som bygger widgetar från.widget-mallar: dess klasserCard,Text,Badge… är föråldrade. Exemplen har körts på en lokal ChatKit-server. Källor: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.
Vad är en ChatKit-widget?
Ett textsvar räcker för förklaringar. Men för att presentera en order, jämföra tre abonnemang eller bekräfta en tid blir text snabbt en vägg av rader som användaren måste läsa om. Widgetar ersätter den texten med ett gränssnitt: ett kort, en lista, ett formulär eller ett diagram, visat direkt i konversationsflödet.
Approachen är deklarativ. Din server levererar varken HTML eller en React-komponent: den beskriver widgeten i JSON, med hjälp av en sluten uppsättning komponenter och egenskaper, och skickar den till tråden som ett fullvärdigt element (en WidgetItem). ChatKit ritar upp den med sina egna komponenter, med hjälp av temafärgerna från föregående lektion. Två konsekvenser följer:
- Du kan bara använda komponenter och egenskaper som ChatKit känner till. I gengäld förblir renderingen konsekvent med resten av gränssnittet, och ingen godtycklig HTML eller JavaScript från servern når sidan.
- Widgeten är en del av historiken: i efterföljande turer konverteras den till indata för modellen, som därmed “ser” vad den visade användaren.
Behållare och komponenter
Varje widget har en rot, vald från tre behållare:
| Behållare | Användning |
|---|---|
Card | Fristående innehåll: en sammanfattning, en bekräftelse, ett formulär. Accepterar en status samt bekräfta/avbryt-knappar under innehållet |
ListView | En uppsättning alternativ: restauranger, filer, ordrar. Dess barn är ListViewItem, med inbyggd “visa mer”-funktionalitet (limit) |
Basic | Reserverat för förhandsvisning av entiteter som visas vid hovring över en omnämnande |
Inuti dessa sätter du ihop komponenter: text (Title, Text, Caption, Markdown), etiketter (Badge), layout (Row, Col, Box, Spacer, Divider), media (Image, Icon), kommandon (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, vilka en Form kan gruppera), diagram (Chart) och animationer (Transition). Komponentsidan i Widget Builder listar egenskaperna för var och en, med en editor för att testa dem.
Designa widgeten i Widget Builder
Det avsedda arbetsflödet börjar i ChatKit Studios Widget Builder. Du designar layouten där, fyller datapanelen med exempelvärden för att bedöma renderingen, och exporterar sedan en .widget-fil. Detta är en JSON-fil som kombinerar mallen, schemat för förväntad data (jsonSchema) och exempeldata. Versionshantera den tillsammans med din serverkod, till exempel i en mapp widgets/.
På serversidan laddar WidgetTemplate filen och build fyller den med riktig data:
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",
})
En relativ sökväg löses från Python-filen som anropar from_file, inte från startkatalogen. build accepterar en dictionary eller en Pydantic-modell.
Vad en mall innehåller
Mallen är en Jinja-modell som producerar widgetens JSON. Orderkortsmallen ser ut så här:
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})
Du kommer sällan skriva en mall för hand, eftersom Widget Builder genererar den. Men att läsa en sparar dig tid när det första problemet uppstår. Tre anmärkningar:
- Filtern
tojsonkonverterar varje värde till giltig JSON (en citerad sträng, en boolean somtrueellerfalse) och escaperar specialtecken: ett apostrof eller citattecken i ett produktnamn kommer inte att förstöra JSON:en. - Jinja körs i strikt läge: saknad data får
buildatt misslyckas, istället för att producera en halvtom widget. buildvaliderar inte data motjsonSchema. Detta schema dokumenterar datan; om den kommer från ett verktyg eller en databas, validera den i förväg, till exempel med en Pydantic-modell.
Konstruktorn WidgetTemplate(...) tar samma innehåll som en redan inläst .widget-fil: detta är smidigt för tester, eller för en mall genererad av din egen kod.
Visa widgeten från respond
För att skicka widgeten till tråden producerar stream_widget motsvarande ChatKit-händelser. Du vidarebefordrar dem från din metod respond:
from chatkit.server import stream_widget
# I din ChatKitServer-klass
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # din data
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 är texten som kopieras till urklipp när användaren klickar på kopieringsknappen under svaret. Servern sparar widgeten till store själv, precis som vilket sändningselement som helst.
Låta agenten bestämma
Oftast är det inte din kod som bestämmer att ett kort ska visas, utan agenten, när konversationen kräver det. Ge den ett verktyg som sänder ut widgeten med AgentContext.stream_widget: stream_agent_response, sett i lektion 17, överför den till gränssnittet mitt i svaret.
from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext
@function_tool(description_override="Visar orderdetaljer som ett kort.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
data = await get_order_data(number) # din dataåtkomst
await ctx.context.stream_widget(order_template.build(data))
return f"Kortet för order {number} visas."
Lägg till verktyget i agentens lista tools. Strängen som returneras av verktyget tjänar modellen, som därmed vet att kortet finns på skärmen och kan kommentera det istället för att upprepa det.
En klickbar lista
För att erbjuda ett val presenterar ListView klickbara rader. Varje ListViewItem kan bära en åtgärd, utlöst vid klick utan att användaren behöver skriva något; nästa lektion visar hur du hanterar detta på serversidan.
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"}]})
Utöver limit visar ChatKit en länk “visa mer”.
Uppdatera en widget medan den visas
En widget kan utvecklas framför användarens ögon, till exempel för att visa ett utkast som modellen skriver. Ge stream_widget en asynkron generator som producerar successiva tillstånd av widgeten: ChatKit beräknar skillnaderna och skickar bara det som ändras.
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})
# Sluttillstånd, när texten är klar
yield draft_template.build({"text": text, "in_progress": False})
Endast komponenterna Text och Markdown med ett id visar sina uppdateringar i en ström, ord för ord; för andra ersätter ChatKit den modifierade delen av widgeten.
Vad händer med Python-klasserna?
Du kommer stöta på, även i OpenAI-guider, widgetar byggda med klasser: Card(children=[Text(value="…")]). De fungerar fortfarande, men SDK:t openai-chatkit 1.6.5 deklarerar dem som föråldrade till förmån för WidgetTemplate: att använda dem emitterar en varning som pekar på .widget-filer. För ett nytt projekt, börja med mallar. För ett befintligt projekt, migrera i din egen takt: varningen blockerar inget, men en föråldrad klass kan försvinna i en framtida version.
När ska du använda en widget?
Dokumentationen citerar typiska användningsområden:
- samla in strukturerad indata med ett formulär, eller presentera ett rikt resultat (tabell, kort, diagram) som text återger dåligt;
- erbjuda ett val mellan flera alternativ;
- kombinera widgeten med åtgärder, för att validera ett val, bekräfta ett steg eller starta server-side-bearbetning;
- ackompanjera en kort förklarande text med ett interaktivt kommando.
Å andra sidan, placera dem inte överallt. En widget som upprepar ord för ord vad texten säger tillför inget, och en konversation mättad med kort blir lika svår att läsa som en vägg av text.
Viktiga punkter
- En ChatKit-widget är en deklarativ beskrivning (JSON) byggd av din server, inte en React-komponent: ChatKit renderar den själv
- Tre behållare:
Card(fristående innehåll),ListView(lista med alternativ),Basic(förhandsvisning av entiteter) - Designa i Widget Builder, exportera en
.widget-fil, ladda den medWidgetTemplate.from_file(...), och fyll den medbuild(data); klassernaCard,Text… är föråldrade - Sänd ut med
stream_widgetfrånrespond, eller från ett agentverktyg medctx.context.stream_widget - En asynkron generator uppdaterar widgeten live; endast
TextochMarkdownmed ettidströmmar ord för ord