如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

ChatKit 小组件

了解如何为聊天界面设计小组件。

小组件是 ChatKit 自带的容器和组件。您可以使用现成的小组件、修改模板,也可以自行设计小组件,全面定制产品中的 ChatKit 聊天界面。

小组件

快速设计小组件

在 ChatKit Studio 中使用小组件构建器尝试不同的卡片布局和列表行样式,并预览组件。选定设计后,将生成的 JSON 复制到您的集成代码中,再通过后端提供该 JSON。

上传资源

您可以上传资源,自定义 ChatKit 小组件,使其与产品风格一致。使用 ChatKit 时,需要先将上传的文件和图片托管在后端,才能在消息中引用它们。参考实现请参阅 Python SDK 上传指南。

ChatKit 小组件可以直接在对话中展示上下文信息、快捷操作和交互式卡片。用户点击小组件中的按钮时,您的应用会收到自定义操作的载荷,以便后端作出响应。

在服务器上处理操作

用户可以通过界面触发小组件操作,从而执行相应的逻辑。您可以将操作绑定到不同小组件节点上的各类事件(例如按钮点击事件),再由服务器或客户端集成代码处理这些操作。

要捕获小组件事件,请使用 onAction 回调(由 WidgetsOption 提供)或等效的 React Hook。将操作载荷转发到后端,由后端处理相应操作。

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)

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

  • 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” } per-side: { 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 (值为字典时,其结构为 { 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