Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Widgetar interaktiva

Lektion 19 av 25 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Vad är en ChatKit-widget?
  2. Behållare och komponenter
  3. Designa widgeten i Widget Builder
  4. Vad en mall innehåller
  5. Visa widgeten från respond
  6. Låta agenten bestämma
  7. En klickbar lista
  8. Uppdatera en widget medan den visas
  9. Vad händer med Python-klasserna?
  10. När ska du använda en widget?
  11. Viktiga punkter

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:t openai-chatkit version 1.6.5, som bygger widgetar från .widget-mallar: dess klasser Card, 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ållareAnvändning
CardFristående innehåll: en sammanfattning, en bekräftelse, ett formulär. Accepterar en status samt bekräfta/avbryt-knappar under innehållet
ListViewEn uppsättning alternativ: restauranger, filer, ordrar. Dess barn är ListViewItem, med inbyggd “visa mer”-funktionalitet (limit)
BasicReserverat 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 tojson konverterar varje värde till giltig JSON (en citerad sträng, en boolean som true eller false) 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 build att misslyckas, istället för att producera en halvtom widget.
  • build validerar inte data mot jsonSchema. 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 med WidgetTemplate.from_file(...), och fyll den med build(data); klasserna Card, Text… är föråldrade
  • Sänd ut med stream_widget från respond, eller från ett agentverktyg med ctx.context.stream_widget
  • En asynkron generator uppdaterar widgeten live; endast Text och Markdown med ett id strömmar ord för ord