Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Giuirléid Idirghníomhacha

Ceacht 19 as 25 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Cad é giuirléid ChatKit?
  2. Coimeádáin agus comhpháirteanna
  3. An ghiuirléid a dhearadh sa Widget Builder
  4. Cad atá i dteimpléad
  5. An ghiuirléid a thaispeáint ó respond
  6. Ligean don ghníomhaire cinneadh a dhéanamh
  7. Liosta inchliceáilte
  8. Giuirléid a nuashonrú agus í á taispeáint
  9. Cad faoi na haicmí Python?
  10. Cathain giuirléid a úsáid
  11. Príomhphointí

An ceacht athscríofa an 3 Samhain, 2026. Sa leagan roimhe seo, rinneadh cur síos ar ghiuirléid mar chomhpháirteanna React a scríobh an forbróir agus a chláraigh sa chomhéadan, ag baint úsáide as modúl @openai/chatkit/react nach bhfuil ann. I ChatKit, is cur síos dearbhaitheach é giuirléid a thógann do fhreastalaí féin agus a renderálann ChatKit é féin. Leanann an ceacht seo SDK Python openai-chatkit 1.6.5, a thógann giuirléid ó theimpléid .widget: tá na haicmí Card, Text, Badge… díobhálta anois. Rith na samplaí ar fhreastalaí áitiúil ChatKit. Foincí: ChatKit widgets · Widgets (Python SDK) · Build interactive responses with widgets · Widget Builder.

Cad é giuirléid ChatKit?

Tá freagra téacs leordhóthanach le haghaidh míniúcháin. Ach chun ordú a chur i láthair, trí phlean a chur i gcomparáid, nó coinne a dheimhniú, éiríonn an téacs go tapa ina bhalla línte ar chóir don úsáideoir athléamh. Cuireann giuirléid comhéadan in ionad an téacs sin: cárta, liosta, foirm, nó cairt, arna thaispeáint laistigh de shreabhadh na comhrá.

Is dearbhaitheach an cur chuige. Ní sheachadann do fhreastalaí HTML ná comhpháirt React: déanann sé cur síos ar an giuirléid i JSON, ag baint úsáide as tacar dúnta comhpháirteanna agus airíonna, agus seolann sé isteach sa snáithe é mar eilimint lánfheidhmiúil (WidgetItem). Tarraingíonn ChatKit é lena chomhpháirteanna féin, ag baint úsáide as dathanna an téama ón gceacht roimhe seo. Tagann dhá thoradh as sin:

  • Ní féidir leat ach comhpháirteanna agus airíonna a úsáid atá ar eolas ag ChatKit. Mar mhalairt air sin, fanann an renderáil comhsheasmhach leis an gcuid eile den chomhéadan, agus ní shroicheann aon HTML nó JavaScript treallach ón bhfreastalaí an leathanach.
  • Is cuid den stair é an ghiuirléid: i gcásanna ina dhiaidh sin, tiontaítear ina ionchur é don mhúnla, rud a chiallaíonn go “feiceann” sé an rud a thaispeáin sé don úsáideoir.

Coimeádáin agus comhpháirteanna

Tá fréamh ag gach giuirléid, roghnaithe as trí choimeádán:

CoimeádánÚsáid
CardÁbhar neamhspleách: achoimre, deimhniú, foirm. Glacann sé le stádas agus cnaipe deimhnithe/cealaithe faoin ábhar
ListViewSraith roghanna: bialanna, comhaid, orduithe. Is iad ListViewItemí a pháistí, le feidhmiúlacht “féach níos mó” ionsuite (limit)
BasicCurtha in áirithe do réamhamhairc eintiteas a thaispeántar nuair a choinníonn tú an cúrsóir thar lua

Laistigh, cuireann tú comhpháirteanna le chéile: téacs (Title, Text, Caption, Markdown), lipéid (Badge), leagan amach (Row, Col, Box, Spacer, Divider), meáin (Image, Icon), orduithe (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, is féidir le Form iad a ghrúpáil), cairteacha (Chart), agus beochana (Transition). Liostaíonn Leathanach Comhpháirteanna an Widget Builder airíonna gach ceann acu, le eagarthóir chun iad a thriail.

An ghiuirléid a dhearadh sa Widget Builder

Tosaíonn an sreabhadh oibre beartaithe i Widget Builder ChatKit Studio. Dearann tú an leagan amach ann, líonann tú an painéal sonraí le luachanna samplacha chun an renderáil a mheas, agus ansin onnmhairíonn tú comhad .widget. Is comhad JSON é seo a chumascann an teimpléad, scéima na sonraí a bhfuiltear ag súil leo (jsonSchema), agus na sonraí samplacha. Cuir faoi rialú leagan é in éineacht le do chód freastalaí, mar shampla i bhfillteán widgets/.

Ar thaobh an fhreastalaí, lódálann WidgetTemplate an comhad agus líonann build le sonraí fíor é:

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

Réitítear cosán coibhneasta ón gcomhad Python a ghlaonn from_file, ní ón eolaire seolta. Glacann build le foclóir nó le samhail Pydantic.

Cad atá i dteimpléad

Is samhail Jinja é an teimpléad a tháirgeann JSON na giuirléide. Seo mar a bhreathnaíonn teimpléad an chárta ordaithe:

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

Is annamh a scríobhfaidh tú teimpléad de láimh, ós rud é go ngineann an Widget Builder é. Ach sábhálfaidh ceann a léamh am ort nuair a thagann an chéad fhadhb chun cinn. Trí nóta:

  • Tiontaíonn an scagaire tojson gach luach go JSON bailí (teanga faoi chomharthaí, boole mar true nó false) agus éalaíonn sé carachtair speisialta: ní bhrisfidh ascamh nó comhartha luachana in ainm táirge an JSON.
  • Rithtear Jinja i mód dian: cúisíonn sonraí in easnamh teip ar build, in ionad giuirléid leathfholamh a tháirgeadh.
  • Ní dhéanann build bailíochtú ar shonraí i gcoinne an jsonSchema. Doiciméadaíonn an scéima seo na sonraí; má thagann sé ó uirlis nó ó bhunachar sonraí, bailíochtigh é roimh ré, mar shampla le samhail Pydantic.

Glacann an tógálaí WidgetTemplate(...) an t-ábhar céanna le comhad .widget léite cheana féin: tá sé seo áisiúil do thástálacha, nó do theimpléad arna ghiniúint ag do chód féin.

An ghiuirléid a thaispeáint ó respond

Chun an ghiuirléid a sheoladh isteach sa snáithe, táirgeann stream_widget na himeachtaí ChatKit comhfhreagracha. Seolann tú iad ar aghaidh ó do mhodh respond:

from chatkit.server import stream_widget

# I do rang ChatKitServer
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # do chuid sonraí
    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

Is é copy_text an téacs a chóipeáiltear chuig an ngearrthaisce nuair a chliceálann an t-úsáideoir an cnaipe cóipeála faoin bhfreagra. Sábhálann an freastalaí an ghiuirléid sa siopa féin, cosúil le haon eilimint chraolta.

Ligean don ghníomhaire cinneadh a dhéanamh

Is minic gurb é an gníomhaire, seachas do chód, a chinneann cárta a thaispeáint, nuair a éilíonn an comhrá é. Tabhair uirlis dó a chraolann an ghiuirléid le AgentContext.stream_widget: tarchuireann stream_agent_response, a chonaiceamar i gceacht 17, é chuig an gcomhéadan i lár an fhreagra.

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)  # do rochtain ar shonraí
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Cuir an uirlis le liosta tools an ghníomhaire. Freastalaíonn an teanga a thugtar ar ais ag an uirlis ar an múnla, rud a chiallaíonn go bhfuil a fhios aige go bhfuil an cárta ar an scáileán agus gur féidir leis trácht a dhéanamh air in ionad é a athrá.

Liosta inchliceáilte

Chun rogha a thairiscint, cuireann ListView sraitheanna inchliceáilte i láthair. Is féidir le gach ListViewItem gníomh a iompar, a spreagtar ar chliceáil gan don úsáideoir aon rud a chlóscríobh; taispeánfaidh an chéad cheacht conas é a láimhseáil ar thaobh an fhreastalaí.

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

Thar an limit, taispeánann ChatKit nasc “féach níos mó”.

Giuirléid a nuashonrú agus í á taispeáint

Is féidir le giuirléid forbairt os comhair súile an úsáideora, mar shampla chun dréacht a scríobhann an múnla a thaispeáint. Tabhair gineadóir asynchronous do stream_widget a tháirgeann stáit leantacha na giuirléide: ríomhann ChatKit na difríochtaí agus seolann sé ach an rud a athraíonn.

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})
    # Stád deiridh, nuair atá an téacs críochnaithe
    yield draft_template.build({"text": text, "in_progress": False})

Ní thaispeánann ach comhpháirteanna Text agus Markdown le id a nuashonruithe i sruth, focal ar fhocal; do chinn eile, athsholáthraíonn ChatKit an chuid mhodhnaithe den ghiuirléid.

Cad faoi na haicmí Python?

Buaileann tú le giuirléid arna dtógáil le haicmí fiú i dtreoracha OpenAI: Card(children=[Text(value="…")]). Oibríonn siad fós, ach dearbhaíonn SDK openai-chatkit 1.6.5 go bhfuil siad díobhálta i bhfabhar WidgetTemplate: scaoileann a n-úsáid rabhadh a dhíríonn ar chomhaid .widget. Do thionscadal nua, tosú ó theimpléid. Do thionscadal atá ann cheana, imircigh de réir do chuid ama: ní chuireann an rabhadh bac ar rud ar bith, ach d’fhéadfadh aicme dhíobhálta imeacht i leagan amach anseo.

Cathain giuirléid a úsáid

Luaann an doiciméadacht úsáidí tipiciúla:

  • ionchur struchtúrtha a bhailiú le foirm, nó toradh saibhir (tábla, cárta, cairt) a chur i láthair nach ndéanann téacs go maith leis;
  • rogha idir roghanna éagsúla a thairiscint;
  • an ghiuirléid a chomhcheangal le gníomhartha, chun roghnú a bhailíochtú, céim a dheimhniú, nó próiseáil taobh freastalaí a sheoladh;
  • téacs míniúcháin gairid a chur le hordú idirghníomhach.

Os a choinne sin, ná cuir i ngach áit iad. Ní chuireann giuirléid a athránn focal ar fhocal an rud a deir an téacs aon rud leis, agus éiríonn comhrá atá sáithithe le cártaí chomh deacair le léamh le balla téacs.

Príomhphointí

  • Is cur síos dearbhaitheach (JSON) é giuirléid ChatKit arna thógáil ag do fhreastalaí, ní comhpháirt React: renderálann ChatKit é féin é
  • Trí choimeádán: Card (ábhar neamhspleách), ListView (liosta roghanna), Basic (réamhamhairc eintiteas)
  • Dearadh sa Widget Builder, onnmhairigh comhad .widget, lódáil le WidgetTemplate.from_file(...), agus líon le build(data); tá na haicmí Card, Text… díobhálta
  • Craol le stream_widget ó respond, nó ó uirlis gníomhaire le ctx.context.stream_widget
  • Nuashonraíonn gineadóir asynchronous an ghiuirléid beo; ní sruthaíonn ach Text agus Markdown le id focal ar fhocal