Widgetit interaktiivisina elementteinä
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026. Edellinen versio kuvasi widgetit kehittäjän kirjoittamina React-komponentteina, jotka rekisteröitiin käyttöliittymään käyttäen olematonta
@openai/chatkit/react-moduulia. ChatKitissa widgetti on deklaratiivinen kuvaus, jonka palvelimesi rakentaa ja jonka ChatKit renderöi itse. Tämä oppitunti noudattaaopenai-chatkitPython SDK:n versiota 1.6.5, joka rakentaa widgettejä.widget-mallipohjista: senCard,Text,Badge…-luokat ovat vanhentuneita. Esimerkit suoritettiin paikallisella ChatKit-palvelimella. Lähteet: ChatKit-widgetit · Widgetit (Python SDK) · Rakenna interaktiivisia vastauksia widgeteillä · Widget Builder.
Mikä on ChatKit-widgetti?
Tekstivastaus riittää selityksiin. Mutta kun haluat esittää tilauksen, verrata kolmea hinnoittelusuunnitelmaa tai vahvistaa ajanvarauksen, tekstistä tulee nopeasti rivimuuri, jota käyttäjän on luettava uudelleen. Widgetit korvaavat tämän tekstin käyttöliittymällä: kortilla, listalla, lomakkeella tai kaaviolla, jotka näytetään keskusteluvirran sisällä.
Lähestymistapa on deklaratiivinen. Palvelimesi ei toimita HTML-koodia eikä React-komponenttia: se kuvaa widgetin JSON-muodossa käyttäen suljettua joukkoa komponentteja ja ominaisuuksia, ja lähettää sen säikeeseen täysivaltaisena elementtinä (WidgetItem). ChatKit piirtää sen omilla komponenteillaan käyttäen edellisestä oppitunnista tuttuja teemavärejä. Tästä seuraa kaksi asiaa:
- Voit käyttää vain komponentteja ja ominaisuuksia, jotka ChatKit tuntee. Vastineeksi renderöinti pysyy yhdenmukaisena muun käyttöliittymän kanssa, eikä palvelimelta tuleva mielivaltainen HTML tai JavaScript pääse sivulle.
- Widgetti on osa historiaa: myöhemmissä vuoroissa se muunnetaan mallin syötteeksi, jolloin malli ”näkee”, mitä se näytti käyttäjälle.
Säiliöt ja komponentit
Jokaisella widgetillä on juurielementti, joka valitaan kolmesta säiliöstä:
| Säiliö | Käyttötarkoitus |
|---|---|
Card | Itsenäinen sisältö: yhteenveto, vahvistus, lomake. Hyväksyy tilan sekä vahvistus- ja peruutuspainikkeet sisällön alapuolelle |
ListView | Vaihtoehtojen joukko: ravintolat, tiedostot, tilaukset. Sen lapsielementit ovat ListViewItem-objekteja, joissa on sisäänrakennettu ”katso lisää” -toiminto (limit) |
Basic | Varattu entiteettien esikatseluille, jotka näytetään maininnan päälle vietäessä |
Sisällä koostat komponentteja: teksti (Title, Text, Caption, Markdown), tunnisteet (Badge), asettelu (Row, Col, Box, Spacer, Divider), media (Image, Icon), komennot (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, jotka Form voi ryhmitellä), kaaviot (Chart) ja animaatiot (Transition). Widget Builderin komponenttisivu luettelee kunkin ominaisuudet ja tarjoaa editorin niiden kokeiluun.
Widgetin suunnittelu Widget Builderissa
Suositeltu työvaihe alkaa ChatKit Studion Widget Builderista. Suunnittelet asettelun siellä, täytät datapaneelin esimerkkiarvoilla arvioidaksesi renderöintiä ja viet sitten .widget-tiedoston. Tämä on JSON-tiedosto, joka yhdistää mallipohjan, odotetun datan skeeman (jsonSchema) ja esimerkkidatan. Versionoi se palvelinkoodisi rinnalla, esimerkiksi widgets/-kansiossa.
Palvelinpuolella WidgetTemplate lataa tiedoston ja build täyttää sen todellisilla tiedoilla:
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",
})
Suhteellinen polku ratkaistaan from_file-metodia kutsuvasta Python-tiedostosta käsin, ei käynnistyshakemistosta. build hyväksyy sanakirjan tai Pydantic-mallin.
Mitä mallipohja sisältää
Mallipohja on Jinja-malli, joka tuottaa widgetin JSON-kuvauksen. Tilauskortin mallipohja näyttää tältä:
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})
Et todennäköisesti kirjoita mallipohjaa käsin, sillä Widget Builder generoi sen. Mutta sen lukeminen säästää aikaa, kun ensimmäinen ongelma ilmenee. Kolme huomiota:
tojson-suodatin muuntaa jokaisen arvon kelvolliseksi JSONiksi (lainattu merkkijono, totuusarvo muodossatruetaifalse) ja pakoa erikoismerkit: tuotenimen heittomerkki tai lainausmerkki ei riko JSONia.- Jinja toimii tiukassa tilassa: puuttuvat tiedot aiheuttavat
build-metodin epäonnistumisen puolityhjän widgetin tuottamisen sijaan. buildei validoi dataajsonSchema-skeemaa vasten. Tämä skeema dokumentoi datan; jos se tulee työkalusta tai tietokannasta, validoita se etukäteen, esimerkiksi Pydantic-mallilla.
WidgetTemplate(...)-rakentaja ottaa saman sisällön kuin jo luettu .widget-tiedosto: tämä on kätevää testaukseen tai oman koodisi generoimalle mallipohjalle.
Widgetin näyttäminen respond-metodista
Lähettääksesi widgetin säikeeseen, stream_widget tuottaa vastaavat ChatKit-tapahtumat. Välität ne respond-metodistasi:
from chatkit.server import stream_widget
# ChatKitServer-luokassasi
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # datasi
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 on teksti, joka kopioidaan leikepöydälle, kun käyttäjä napsauttaa vastauksen alapuolella olevaa kopiointipainiketta. Palvelin tallentaa widgetin itse storeen kuten minkä tahansa lähetetyn elementin.
Agentin päätösvallan antaminen
Useimmiten ei koodisi päätä kortin näyttämistä, vaan agentti, kun keskustelu sitä vaatii. Anna sille työkalu, joka lähettää widgetin käyttämällä AgentContext.stream_widget-metodia: stream_agent_response, jonka näit oppitunnissa 17, välittää sen käyttöliittymään vastauksen keskellä.
from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext
@function_tool(description_override="Displays order details as a card.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
data = await get_order_data(number) # datan hakusi
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Lisää työkalu agentin tools-listaan. Työkalun palauttama merkkijono palvelee mallia, joka tietää kortin olevan näytöllä ja voi kommentoida sitä sen sijaan, että toistaisi sen.
Napsautettava lista
Tarjotaksesi valinnan mahdollisuuden, ListView esittää napsautettavia rivejä. Jokainen ListViewItem voi sisältää toiminnon, joka laukaistaan napsautettaessa ilman, että käyttäjän tarvitsee kirjoittaa mitään; seuraava oppitunti näyttää, kuinka sitä käsitellään palvelinpuolella.
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"}]})
limit-arvon ylittyessä ChatKit näyttää ”katso lisää” -linkin.
Widgetin päivittäminen näytöllä ollessa
Widgetti voi kehittyä käyttäjän silmien edessä, esimerkiksi näyttääkseen luonnoksen, jota malli kirjoittaa. Anna stream_widget-funktiolle asynkroninen generaattori, joka tuottaa widgetin peräkkäisiä tiloja: ChatKit laskee erot ja lähettää vain muuttuneen osan.
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})
# Lopputila, kun teksti on valmis
yield draft_template.build({"text": text, "in_progress": False})
Vain Text- ja Markdown-komponentit, joilla on id, näyttävät päivityksensä suoratoistona sana sanalta; muiden osalta ChatKit korvaa widgetin muuttuneen osan.
Entä Python-luokat?
Törmäät jopa OpenAI:n oppaissa widgetteihin, jotka on rakennettu luokilla: Card(children=[Text(value="…")]). Ne toimivat edelleen, mutta openai-chatkit 1.6.5 SDK julistaa ne vanhentuneiksi WidgetTemplate-luokan hyväksi: niiden käyttö tuottaa varoituksen, joka viittaa .widget-tiedostoihin. Uudessa projektissa aloita mallipohjista. Olemassa olevassa projektissa siirry omaan tahtiisi: varoitus ei estä toimintaa, mutta vanhentunut luokka voi kadota tulevassa versiossa.
Milloin käyttää widgettiä
Dokumentaatio mainitsee tyypillisiä käyttötarkoituksia:
- jäsennetyn syötteen kerääminen lomakkeella tai rikkaan tuloksen (taulukko, kortti, kaavio) esittäminen, jonka teksti renderöi huonosti;
- valinnan tarjoaminen useiden vaihtoehtojen välillä;
- widgetin yhdistäminen toimintoihin valinnan validoimiseksi, vaiheen vahvistamiseksi tai palvelinpuoleisen käsittelyn käynnistämiseksi;
- lyhyen selitystekstin seuraaminen interaktiivisella komennolla.
Älä kuitenkaan sijoita niitä kaikkialle. Widgetti, joka toistaa sanasta sanaan sen, mitä teksti sanoo, ei lisää mitään, ja korteilla kyllästetty keskustelu on yhtä vaikea lukea kuin rivimuuri.
Keskeiset asiat
- ChatKit-widgetti on palvelimesi rakentama deklaratiivinen kuvaus (JSON), ei React-komponentti: ChatKit renderöi sen itse
- Kolme säiliötä:
Card(itsenäinen sisältö),ListView(vaihtoehtolista),Basic(entiteettien esikatselut) - Suunnittele Widget Builderissa, vie
.widget-tiedosto, lataa seWidgetTemplate.from_file(...)-metodilla ja täytä sebuild(data)-metodilla;Card,Text…-luokat ovat vanhentuneita - Lähetä
stream_widget-funktiollarespond-metodista tai agentin työkalustactx.context.stream_widget-metodilla - Asynkroninen generaattori päivittää widgetin reaaliajassa; vain
Text- jaMarkdown-komponentit, joilla onid, suoratoistavat sana sanalta