Salt la conținutul principal
Română— Alege o limbă
Meniu

Widget-uri interactive

Lecția 19 din 25 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Ce este un widget ChatKit?
  2. Containere și componente
  3. Proiectarea widget-ului în Constructorul de Widget-uri
  4. Ce conține un șablon
  5. Afișarea widget-ului din respond
  6. Lăsarea agentului să decidă
  7. O listă clicabilă
  8. Actualizarea unui widget în timp ce este afișat
  9. Dar clasele Python?
  10. Când să folosiți un widget
  11. Puncte cheie

Lecție rescrisă la 3 noiembrie 2026. Versiunea anterioară descria widget-urile ca fiind componente React scrise de dezvoltator și înregistrate în interfață, folosind un modul inexistent @openai/chatkit/react. În ChatKit, un widget este o descriere declarativă pe care serverul dumneavoastră o construiește și pe care ChatKit o randează singur. Această lecție urmează SDK-ul Python openai-chatkit 1.6.5, care construiește widget-uri din șabloane .widget: clasele sale Card, Text, Badge… sunt depreciate. Exemplele au fost executate pe un server ChatKit local. Surse: Widget-uri ChatKit · Widget-uri (SDK Python) · Construirea răspunsurilor interactive cu widget-uri · Constructor de Widget-uri.

Ce este un widget ChatKit?

Un răspuns text este suficient pentru explicații. Dar pentru a prezenta o comandă, a compara trei planuri sau a confirma o programare, textul devine rapid un zid de rânduri pe care utilizatorul trebuie să le recitească. Widget-urile înlocuiesc acel text cu o interfață: un card, o listă, un formular sau un grafic, afișate direct în fluxul conversației.

Abordarea este declarativă. Serverul dumneavoastră nu livrează nici HTML, nici o componentă React: acesta descrie widget-ul în JSON, folosind un set închis de componente și proprietăți, și îl trimite în firul de discuție ca un element de sine stătător (un WidgetItem). ChatKit îl desenează cu propriile componente, folosind culorile temei din lecția anterioară. Decurg două consecințe:

  • Puteți folosi doar componente și proprietăți pe care ChatKit le cunoaște. În schimb, randarea rămâne consistentă cu restul interfeței, iar niciun HTML sau JavaScript arbitrar de la server nu ajunge pe pagină.
  • Widget-ul face parte din istoric: în turele ulterioare, acesta este convertit în intrare pentru model, care astfel „vede“ ceea ce i-a arătat utilizatorului.

Containere și componente

Fiecare widget are o rădăcină, aleasă din trei containere:

ContainerUtilizare
CardConținut de sine stătător: un rezumat, o confirmare, un formular. Acceptă o stare și butoane de confirmare/anulare sub conținut
ListViewUn set de opțiuni: restaurante, fișiere, comenzi. Copiii săi sunt ListViewItem, cu funcționalitate integrată de „vezi mai mult“ (limit)
BasicRezervat pentru previzualizările entităților afișate la trecerea mouse-ului peste o mențiune

În interior, asamblați componente: text (Title, Text, Caption, Markdown), etichete (Badge), aspect (Row, Col, Box, Spacer, Divider), media (Image, Icon), comenzi (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, pe care un Form le poate grupa), grafice (Chart) și animații (Transition). Pagina Componente din Constructorul de Widget-uri listează proprietățile fiecăreia, cu un editor pentru a le testa.

Proiectarea widget-ului în Constructorul de Widget-uri

Fluxul de lucru intenționat începe în Constructorul de Widget-uri din ChatKit Studio. Aici proiectați aspectul, completați panoul de date cu valori exemplu pentru a judeca randarea și apoi exportați un fișier .widget. Acesta este un fișier JSON care combină șablonul, schema datelor așteptate (jsonSchema) și datele exemplu. Plasați-l sub controlul versiunii alături de codul serverului dumneavoastră, de exemplu într-un folder widgets/.

Pe partea de server, WidgetTemplate încarcă fișierul, iar build îl completează cu date reale:

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",
})

O cale relativă este rezolvată din fișierul Python care apelează from_file, nu din directorul de lansare. build acceptă un dicționar sau un model Pydantic.

Ce conține un șablon

Șablonul este un model Jinja care produce JSON-ul widget-ului. Șablonul cardului de comandă arată astfel:

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})

Rareori veți scrie un șablon de mână, deoarece Constructorul de Widget-uri îl generează. Dar citirea unuia vă va economisi timp când apare prima problemă. Trei observații:

  • Filtrul tojson convertește fiecare valoare în JSON valid (un șir între ghilimele, un boolean ca true sau false) și scapă caracterele speciale: un apostrof sau o ghilimele într-un nume de produs nu vor strica JSON-ul.
  • Jinja rulează în mod strict: datele lipsă fac ca build să eșueze, în loc să producă un widget pe jumătate gol.
  • build nu validează datele față de jsonSchema. Această schemă documentează datele; dacă provin de la un instrument sau o bază de date, validați-le înainte, de exemplu cu un model Pydantic.

Constructorul WidgetTemplate(...) preia același conținut ca un fișier .widget deja citit: acest lucru este util pentru teste sau pentru un șablon generat de propriul dumneavoastră cod.

Afișarea widget-ului din respond

Pentru a trimite widget-ul în firul de discuție, stream_widget produce evenimentele ChatKit corespunzătoare. Le retransmiteți din metoda dumneavoastră respond:

from chatkit.server import stream_widget

# În clasa dumneavoastră ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # datele dumneavoastră
    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 este textul copiat în clipboard când utilizatorul face clic pe butonul de copiere de sub răspuns. Serverul salvează widget-ul în store chiar el, ca orice element de difuzare.

Lăsarea agentului să decidă

Cel mai adesea, nu codul dumneavoastră decide afișarea unui card, ci agentul, atunci când conversația o cere. Oferiți-i un instrument care difuzează widget-ul cu AgentContext.stream_widget: stream_agent_response, văzut în lecția 17, îl transmite interfeței în mijlocul răspunsului.

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


@function_tool(description_override="Afișează detaliile comenzii sub formă de card.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
    data = await get_order_data(number)  # accesul dumneavoastră la date
    await ctx.context.stream_widget(order_template.build(data))
    return f"Cardul pentru comanda {number} este afișat."

Adăugați instrumentul la lista tools a agentului. Șirul returnat de instrument servește modelului, care astfel știe că cardul este pe ecran și poate comenta despre el în loc să îl repete.

O listă clicabilă

Pentru a oferi o alegere, ListView prezintă rânduri clicabile. Fiecare ListViewItem poate purta o acțiune, declanșată la clic fără ca utilizatorul să trebuiască să tasteze ceva; lecția următoare arată cum să o gestionați pe partea de server.

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"}]})

Dincolo de limit, ChatKit afișează un link „vezi mai mult“.

Actualizarea unui widget în timp ce este afișat

Un widget poate evolua sub ochii utilizatorului, de exemplu pentru a afișa un cioran pe care modelul îl scrie. Oferiți lui stream_widget un generator asincron care produce stări successive ale widget-ului: ChatKit calculează diferențele și trimite doar ceea ce se schimbă.

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})
    # Starea finală, odată ce textul este complet
    yield draft_template.build({"text": text, "in_progress": False})

Doar componentele Text și Markdown cu un id își afișează actualizările într-un flux, cuvânt cu cuvânt; pentru altele, ChatKit înlocuiește partea modificată a widget-ului.

Dar clasele Python?

Veți întâlni, chiar și în ghidurile OpenAI, widget-uri construite cu clase: Card(children=[Text(value="…")]). Acestea funcționează încă, dar SDK-ul openai-chatkit 1.6.5 le declară depreciate în favoarea WidgetTemplate: utilizarea lor emite un avertisment care indică spre fișierele .widget. Pentru un proiect nou, începeți de la șabloane. Pentru un proiect existent, migrați în ritmul dumneavoastră: avertismentul nu blochează nimic, dar o clasă depreciată poate dispărea într-o versiune viitoare.

Când să folosiți un widget

Documentația citează utilizări tipice:

  • colectarea unei intrări structurate cu un formular sau prezentarea unui rezultat bogat (tabel, card, grafic) pe care textul îl randează slab;
  • oferirea unei alegeri între mai multe opțiuni;
  • combinarea widget-ului cu acțiuni, pentru a valida o selecție, a confirma un pas sau a lansa o procesare pe server;
  • însoțirea unui scurt text explicativ cu o comandă interactivă.

Dimpotrivă, nu le plasați peste tot. Un widget care repetă cuvânt cu cuvânt ceea ce spune textul nu adaugă nimic, iar o conversație saturată de carduri devine la fel de dificil de citit ca un zid de text.

Puncte cheie

  • Un widget ChatKit este o descriere declarativă (JSON) construită de serverul dumneavoastră, nu o componentă React: ChatKit îl randează singur
  • Trei containere: Card (conținut de sine stătător), ListView (listă de opțiuni), Basic (previzualizări de entități)
  • Proiectați în Constructorul de Widget-uri, exportați un fișier .widget, încărcați-l cu WidgetTemplate.from_file(...) și completați-l cu build(data); clasele Card, Text… sunt depreciate
  • Difuzarea se face cu stream_widget din respond sau dintr-un instrument al agentului cu ctx.context.stream_widget
  • Un generator asincron actualizează widget-ul în direct; doar Text și Markdown cu un id transmit în flux cuvânt cu cuvânt