主导航

推荐

开始使用

核心概念

Agents SDK

工具

运行与扩展

评估

实时与音频

模型优化

专用模型

上线

遗留 API

资源

API 控制台

ChatKit 小组件

了解如何在您的聊天体验中设计小组件。

小组件是 ChatKit 自带的容器和组件。您可以使用预构建的小组件、修改模板，或设计自己的组件，以充分定制产品中的 ChatKit。

widgets

快速设计小组件

使用 ChatKit Studio 中的小组件构建器 (Widget Builder) 来试验卡片布局、列表行和预览组件。当您拥有满意的设计后，将生成的 JSON 复制到您的集成中，并由后端提供支持。

上传资源

上传资源以自定义 ChatKit 小组件，使其与您的产品风格相匹配。ChatKit 要求上传的文件和图像在被消息引用之前，必须先由您的后端托管。请参考 Python SDK 中的上传指南以获取参考实现。

ChatKit 小组件可以直接在对话中呈现上下文、快捷方式和交互式卡片。当用户点击小组件按钮时，您的应用程序会收到一个自定义操作负载 (payload)，以便您可以从后端进行响应。

在服务器上处理操作

小组件操作允许用户从 UI 触发逻辑。操作可以绑定到各种小组件节点的事件（如按钮点击），然后由您的服务器或客户端集成进行处理。

使用 WidgetsOption 或相应的 React 钩子中的 onAction 回调来捕获小组件事件。将操作负载转发到您的后端以处理这些操作。

1
2
3
4
5
6
7
8
9
10
11
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)

支持以下小组件类型。您也可以在小组件构建器的组件部分浏览组件并使用交互式编辑器。

  • 徽章 (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) – 显示垂直的条目列表。

    • 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 (当为 dict 时: { 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
© . This website operates independently and is not affiliated with or endorsed by OpenAI, Inc. All brand names, logos, and trademarks are the property of their respective owners.