OpenAI ChatKit 组件参考

组件（widget）是ChatKit自带的容器与界面单元。可使用预制组件、修改模板或自行设计，定制产品中的ChatKit。

快速设计组件

在ChatKit Studio的Widget Builder尝试卡片布局、列表行与预览组件。满意后复制生成的JSON，放入集成并由后端提供。

上传素材

上传素材可让组件匹配产品风格。消息引用文件或图片前，应先由自己的后端托管上传内容。参考实现见Python SDK上传指南。

组件可以直接在对话中呈现上下文、快捷操作和交互卡片。用户点击按钮后，应用收到自定义动作载荷，由后端响应。

在服务器处理动作

组件动作可绑定到按钮点击等不同节点事件，再由服务器或客户端集成处理。使用WidgetsOption.onAction回调或对应React钩子捕获事件，将动作载荷转发给后端。

来源示例 1（javascript）：

// [中文] 示例1：在服务器处理动作。
// [中文] 捕获组件动作，将动作与item.id作为JSON POST给自有/api/widget-action端点。
// [中文] 此片段未实现服务端认证、授权或载荷校验；不能把客户端传入itemId直接视为访问权限。
chatkit.setOptions({
  widgets: {
    async onAction(action, item) {
      await fetch("/api/widget-action", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ action, itemId: item.id }),
      });
    },
  },
});

完整服务端流程见ChatKit Python SDK文档，更多说明见动作指南。

参考

建议先从上述可视化工具入手，下面用于了解组件工作方式与全部选项。

组件以单个容器WidgetRoot为根，内部包含多个WidgetNode。

容器（WidgetRoot）

容器可显示状态指示文字和主要操作。

• Card：带边界的组件容器，支持status、confirm和cancel，用于显示状态及底部操作按钮。
  • children: list[WidgetNode]
  • size: "sm" | "md" | "lg" | "full" (默认值： "md")
  • padding: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • background: str | { dark: str, light: str } | None
  • status: { text: str, favicon?: str } | { text: str, icon?: str } | None
  • collapsed: bool | None
  • asForm: bool | None
  • confirm: { label: str, action: ActionConfig } | None
  • cancel: { label: str, action: ActionConfig } | None
  • theme: "light" | "dark" | None
  • key: str | None

• ListView：垂直项目列表；根容器的每项为ListViewItem。
  • children: list[ListViewItem]
  • limit: int | "auto" | None
  • status: { text: str, favicon?: str } | { text: str, icon?: str } | None
  • theme: "light" | "dark" | None
  • key: str | None

组件（WidgetNode）

支持的组件类型如下，也可在Widget Builder的组件编辑器中浏览和交互编辑。字段名称、类型与枚举保留其API写法。

• Badge：用于状态或元数据的小标签。
  • label: str
  • color: "secondary" | "success" | "danger" | "warning" | "info" | "discovery" | None
  • variant: "solid" | "soft" | "outline" | None
  • pill: bool | None
  • size: "sm" | "md" | "lg" | None
  • key: str | None

• Box：灵活布局容器，支持方向、间距与样式。
  • children: list[WidgetNode] | None
  • direction: "row" | "column" | None
  • align: "start" | "center" | "end" | "baseline" | "stretch" | None
  • justify: "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly" | None
  • wrap: "nowrap" | "wrap" | "wrap-reverse" | None
  • flex: int | str | None
  • height: float | str | None
  • width: float | str | None
  • minHeight: int | str | None
  • minWidth: int | str | None
  • maxHeight: int | str | None
  • maxWidth: int | str | None
  • size: float | str | None
  • minSize: int | str | None
  • maxSize: int | str | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • margin: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • border: int | dict[str, Any] | None
  • 单一边框：{ size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" }
  • 逐边配置：{ top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }
  • radius: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "100%" | "none" | None
  • background: str | { dark: str, light: str } | None
  • aspectRatio: float | str | None
  • key: str | None

• Row：横向排列子节点。
  • children: list[WidgetNode] | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • align: "start" | "center" | "end" | "baseline" | "stretch" | None
  • justify: "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly" | None
  • flex: int | str | None
  • height: float | str | None
  • width: float | str | None
  • minHeight: int | str | None
  • minWidth: int | str | None
  • maxHeight: int | str | None
  • maxWidth: int | str | None
  • size: float | str | None
  • minSize: int | str | None
  • maxSize: int | str | None
  • margin: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • border: int | dict[str, Any] | None
  • 单一边框：{ size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" }
  • 逐边配置：{ top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }
  • radius: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "100%" | "none" | None
  • background: str | { dark: str, light: str } | None
  • aspectRatio: float | str | None
  • key: str | None

• Col：纵向排列子节点。
  • children: list[WidgetNode] | None
  • gap: int | str | None
  • padding: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • align: "start" | "center" | "end" | "baseline" | "stretch" | None
  • justify: "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly" | None
  • wrap: "nowrap" | "wrap" | "wrap-reverse" | None
  • flex: int | str | None
  • height: float | str | None
  • width: float | str | None
  • minHeight: int | str | None
  • minWidth: int | str | None
  • maxHeight: int | str | None
  • maxWidth: int | str | None
  • size: float | str | None
  • minSize: int | str | None
  • maxSize: int | str | None
  • margin: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • border: int | dict[str, Any] | None
  • 单一边框：{ size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" }
  • 逐边配置：{ top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }
  • radius: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "100%" | "none" | None
  • background: str | { dark: str, light: str }| None
  • aspectRatio: float | str | None
  • key: str | None

• Button：可灵活配置的动作按钮。
  • submit: bool | None
  • style: "primary" | "secondary" | None
  • label: str
  • onClickAction: ActionConfig
  • iconStart: str | None
  • iconEnd: str | None
  • color: "primary" | "secondary" | "info" | "discovery" | "success" | "caution" | "warning" | "danger" | None
  • variant: "solid" | "soft" | "outline" | "ghost" | None
  • size: "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | None
  • pill: bool | None
  • block: bool | None
  • uniform: bool | None
  • iconSize: "sm" | "md" | "lg" | "xl" | "2xl" | None
  • key: str | None

• Caption：较小的辅助文字。
  • value: str
  • size: "sm" | "md" | "lg" | None
  • weight: "normal" | "medium" | "semibold" | "bold" | None
  • textAlign: "start" | "center" | "end" | None
  • color: str | { dark: str, light: str } | None
  • truncate: bool | None
  • maxLines: int | None
  • key: str | None

• DatePicker：带下拉日历的日期输入。
  • onChangeAction: ActionConfig | None
  • name: str
  • min: datetime | None
  • max: datetime | None
  • side: "top" | "bottom" | "left" | "right" | None
  • align: "start" | "center" | "end" | None
  • placeholder: str | None
  • defaultValue: datetime | None
  • variant: "solid" | "soft" | "outline" | "ghost" | None
  • size: "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | None
  • pill: bool | None
  • block: bool | None
  • clearable: bool | None
  • disabled: bool | None
  • key: str | None

• Divider：横向或纵向分隔线。
  • spacing: int | str | None
  • color: str | { dark: str, light: str } | None
  • size: int | str | None
  • flush: bool | None
  • key: str | None

• Icon：按名称显示图标。
  • name: str
  • color: str | { dark: str, light: str } | None
  • size: "xs" | "sm" | "md" | "lg" | "xl" | None
  • key: str | None

• Image：显示图像，可配置样式、适配方式与位置。
  • size: int | str | None
  • height: int | str | None
  • width: int | str | None
  • minHeight: int | str | None
  • minWidth: int | str | None
  • maxHeight: int | str | None
  • maxWidth: int | str | None
  • minSize: int | str | None
  • maxSize: int | str | None
  • radius: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "100%" | "none" | None
  • background: str | { dark: str, light: str } | None
  • margin: int | str | dict[str, int | str] | None （可用键： top, right, bottom, left, x, y）
  • aspectRatio: float | str | None
  • flex: int | str | None
  • src: str
  • alt: str | None
  • fit: "none" | "cover" | "contain" | "fill" | "scale-down" | None
  • position: "center" | "top" | "bottom" | "left" | "right" | "top left" | "top right" | "bottom left" | "bottom right" | None
  • frame: bool | None
  • flush: bool | None
  • key: str | None

• ListView：垂直项目列表；根容器的每项为ListViewItem。
  • children: list[ListViewItem] | None
  • limit: int | "auto" | None
  • status: dict[str, Any] | None （结构： { text: str, favicon?: str }）
  • theme: "light" | "dark" | None
  • key: str | None

• ListViewItem：ListView中的项目，可带操作。
  • children: list[WidgetNode] | None
  • onClickAction: ActionConfig | None
  • gap: int | str | None
  • align: "start" | "center" | "end" | "baseline" | "stretch" | None
  • key: str | None

• Markdown：渲染Markdown文字，支持流式更新。
  • value: str
  • streaming: bool | None
  • key: str | None

• Select：下拉单选输入。
  • options: list[dict[str, str]] （每个选项： { label: str, value: str }）
  • onChangeAction: ActionConfig | None
  • name: str
  • placeholder: str | None
  • defaultValue: str | None
  • variant: "solid" | "soft" | "outline" | "ghost" | None
  • size: "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | None
  • pill: bool | None
  • block: bool | None
  • clearable: bool | None
  • disabled: bool | None
  • key: str | None

• Spacer：布局中的弹性空白。
  • minSize: int | str | None
  • key: str | None

• Text：显示纯文本；Markdown内容使用Markdown组件，支持流式更新。
  • value: str
  • color: str | { dark: str, light: str } | None
  • width: float | str | None
  • size: "xs" | "sm" | "md" | "lg" | "xl" | None
  • weight: "normal" | "medium" | "semibold" | "bold" | None
  • textAlign: "start" | "center" | "end" | None
  • italic: bool | None
  • lineThrough: bool | None
  • truncate: bool | None
  • minLines: int | None
  • maxLines: int | None
  • streaming: bool | None
  • editable: bool | dict[str, Any] | None （为字典时： { name: str, autoComplete?: str, autoFocus?: bool, autoSelect?: bool, allowAutofillExtensions?: bool, required?: bool, placeholder?: str, pattern?: str }）
  • key: str | None

• Title：突出的标题文字。
  • value: str
  • size: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | None
  • weight: "normal" | "medium" | "semibold" | "bold" | None
  • textAlign: "start" | "center" | "end" | None
  • color: str | { dark: str, light: str } | None
  • truncate: bool | None
  • maxLines: int | None
  • key: str | None

• Form：能够提交动作的布局容器。
  • onSubmitAction: ActionConfig
  • children: list[WidgetNode] | None
  • align: "start" | "center" | "end" | "baseline" | "stretch" | None
  • justify: "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly" | None
  • flex: int | str | None
  • gap: int | str | None
  • height: float | str | None
  • width: float | str | None
  • minHeight: int | str | None
  • minWidth: int | str | None
  • maxHeight: int | str | None
  • maxWidth: int | str | None
  • size: float | str | None
  • minSize: int | str | None
  • maxSize: int | str | None
  • padding: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • margin: float | str | dict[str, float | str] | None （可用键： top, right, bottom, left, x, y）
  • border: int | dict[str, Any] | None
  • 单一边框：{ size: int, color?: str | { dark: str, light: str }, style?: "solid" | "dashed" | "dotted" | "double" | "groove" | "ridge" | "inset" | "outset" }
  • 逐边配置：{ top?: int|dict, right?: int|dict, bottom?: int|dict, left?: int|dict, x?: int|dict, y?: int|dict }
  • radius: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "100%" | "none" | None
  • background: str | { dark: str, light: str } | None
  • key: str | None

• Transition：包裹可能带动画的内容。
  • children: WidgetNode | None
  • key: str | None