#配置参考
<Chatkit> 的属性与嵌套字段参考。说明和默认值来自当前版本的类型声明。较长的类型显示摘要，完整签名以安装包的 TypeScript 声明为准。
独立使用时提供 sessions 或 runtime；位于 ChatkitProvider 内时可继承。表中的“必填”指对应对象内部的字段要求；默认值可能受到其他设置或后端能力影响，详见说明。
#sessions
会话层：useChatSessions 的返回值。与 runtime 二选一；会话列表由独立的 SessionList 显示
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
sessions | ChatSessions | 完整应用：useChatSessions 的返回值。与 runtime 二选一。会话列表是单独的组件 SessionList，用同一个返回值。 | ||
sessions.runtime | ChatkitRuntime | 是 | 当前受控 ID 对应的运行时；未选择、初始化前或已释放时为空。 | |
sessions.runtime.session | ChatkitControlledSessionActions | 外部会话 Registry 的界面状态回写与会话命令。 | ||
sessions.runtime.updateContent | (changes: ContentChange | readonly ContentChange[]) => Promise<ContentUpdateResult> | 是 | 更新此会话的内容；异步请求应捕获原 runtime，不能改用当前会话。 | |
sessions.runtime.store | ChatkitControlledStore | 是 | 对话的最新状态。 | |
sessions.runtime.actions | ChatkitRuntimeActions | 是 | 界面能发起的操作。 | |
sessions.runtime.events | ChatkitRuntimeEvents | 发送与运行事件。 | ||
sessions.runtime.errors | ChatkitErrorChannel | hook 上没给 onError 时的错误来源，Chatkit 订阅后交给自己的 onError。 | ||
sessions.runtime.capabilities | ChatkitCapabilities | 是 | 后端支持哪些功能。 | |
sessions.store | { getSnapshot: () => ChatSessionsSnapshot; subscribe: (callback: () => void) => () => v… | 是 | 已打开运行时的资源与运行状态，不包含业务目录。 | |
sessions.store.getSnapshot | () => ChatSessionsSnapshot | 是 | 获取稳定的只读资源快照。 | |
sessions.store.subscribe | (callback: () => void) => () => void | 是 | 监听资源或运行状态变化，返回退订函数。 | |
sessions.actions | ChatSessionsActions | 是 | 打开、复用与释放本地运行时。 | |
sessions.actions.open | (sessionId: string) => Promise<ChatkitRuntime> | 是 | 打开或复用 runtime，等待历史初始化；不改变外部选择。释放或卸载时拒绝。 | |
sessions.actions.release | (sessionId: string) => boolean | 是 | 释放本地 runtime 与监听；不删除会话，不请求远端停止。 | |
sessions.events | ChatkitRuntimeEvents | 汇总全部已打开会话的事件，保留各自 sessionId。 | ||
sessions.events.subscribe | (listener: (event: ChatkitEvent) => void) => () => void | 是 | 订阅事件，返回退订函数。 | |
sessions.events.reportPageHidden | () => void | 页面被隐藏或关闭时调用，让还在运行的一轮报成被放弃；Chatkit 会自动调。 | ||
sessions.events.reportFirstPaint | (runId: string) => number | 这一轮的正文第一次画到屏幕上时调用，返回受理到此刻的毫秒数；Chatkit 会自动调。 | ||
sessions.errors | ChatkitErrorChannel | hook 上没给 onError 时，全部已打开会话的错误从这里出，Chatkit 订阅后交给自己的 onError。 | ||
sessions.errors.subscribe | (handler: ChatkitErrorHandler) => () => void | 是 | 订阅错误，返回退订函数。只有最近一个订阅方收到，内层的 <Chatkit> 优先于外层的 Provider。 | |
sessions.capabilities | ChatkitCapabilities | 是 | 当前适配器支持的执行与历史能力。 | |
sessions.capabilities.abort | boolean | 是 | 能通知后端停止。为 false 时不显示停止按钮。 | |
sessions.capabilities.history | boolean | 是 | 能拉取会话历史。 | |
sessions.capabilities.historyPaging | boolean | 是 | 能向前翻页加载更早的历史。 | |
sessions.capabilities.resume | boolean | 是 | 断线后能续接仍在运行的一轮。 | |
sessions.capabilities.steer | boolean | 是 | 运行中能插话。 | |
sessions.capabilities.regenerate | boolean | 是 | 能重新生成。 | |
sessions.capabilities.edit | boolean | 是 | 能编辑后重发。 | |
sessions.capabilities.acceptedFileTypes | readonly string[] | 支持的附件类型（同 <input accept> 的写法）；不给表示不限制。 | ||
sessions.capabilities.attachmentCapabilities | readonly AttachmentCapability[] | 支持的 MIME 与存储来源组合；最终资源必须匹配一项，避免把类型与来源当作任意组合。 |
#runtime
单个对话：useChatRuntime 的返回值。与 sessions 二选一
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
runtime | ChatkitExternalRuntime | 单个对话：useChatRuntime 的返回值。与 sessions 二选一。 | ||
runtime.updateContent | (changes: ContentChange | readonly ContentChange[]) => Promise<ContentUpdateResult> | 接入方可选的内容更新命令；UI 不调用，自建运行时始终提供。 | ||
runtime.session | ChatkitControlledSessionActions | 外部会话 Registry 的界面状态回写与会话命令。 | ||
runtime.session.create | () => Promise<boolean> | 是 | Session 生命周期归宿主 Registry，不归 Chat UI。 | |
runtime.session.select | (sessionId: string) => Promise<boolean> | 是 | 切换到指定会话。 | |
runtime.session.clear | () => Promise<boolean> | 是 | 清空当前会话。 | |
runtime.session.updateUiState | (patch: Partial<ChatkitSessionState>) => void | 保存会话级界面状态（草稿、消息定位），切回来时经快照的 sessionUiState 还原。 | ||
runtime.store | ChatkitControlledStore | 是 | 对话的最新状态。 | |
runtime.store.getSnapshot | () => ChatkitControlledSnapshot | 是 | 返回当前快照；内容没变时必须返回同一个引用（useSyncExternalStore 的要求）。 | |
runtime.store.subscribe | (callback: () => void) => () => void | 是 | 订阅快照变化，返回退订函数。 | |
runtime.actions | ChatkitRuntimeActions | 是 | 界面能发起的操作。 | |
runtime.actions.recover | (runId: string) => Promise<boolean> | 查询或续接已有轮次，不重新发送输入。 | ||
runtime.actions.regenerate | (messageId?: string) => Promise<ChatkitControlledCommandResult> | 重新生成；不给 messageId 时针对最后一条回答。 | ||
runtime.actions.edit | (messageId: string, input: ChatkitControlledSendInput) => Promise<ChatkitControlledComm… | 编辑某条用户消息后重发。 | ||
runtime.actions.send | (input: ChatkitControlledSendInput) => Promise<ChatkitControlledCommandResult> | 是 | 发送。返回 { accepted }：受理后输入框清空草稿，不受理时草稿保留。 | |
runtime.actions.abort | () => Promise<boolean> | 是 | 停止正在进行的一轮。 | |
runtime.actions.loadMoreHistory | () => Promise<boolean> | 是 | 向前加载更早的历史（滚到顶部时调用）。 | |
runtime.actions.steer | (input: ChatkitControlledSendInput) => Promise<ChatkitControlledCommandResult> | 回答进行中追加输入（插话）。不提供时运行中只能排队或停止。 | ||
runtime.events | ChatkitRuntimeEvents | 发送与运行事件。 | ||
runtime.events.subscribe | (listener: (event: ChatkitEvent) => void) => () => void | 是 | 订阅事件，返回退订函数。 | |
runtime.events.reportPageHidden | () => void | 页面被隐藏或关闭时调用，让还在运行的一轮报成被放弃；Chatkit 会自动调。 | ||
runtime.events.reportFirstPaint | (runId: string) => number | 这一轮的正文第一次画到屏幕上时调用，返回受理到此刻的毫秒数；Chatkit 会自动调。 | ||
runtime.errors | ChatkitErrorChannel | hook 上没给 onError 时的错误来源，Chatkit 订阅后交给自己的 onError。 | ||
runtime.errors.subscribe | (handler: ChatkitErrorHandler) => () => void | 是 | 订阅错误，返回退订函数。只有最近一个订阅方收到，内层的 <Chatkit> 优先于外层的 Provider。 | |
runtime.capabilities | ChatkitCapabilities | 是 | 后端支持哪些功能。 | |
runtime.capabilities.abort | boolean | 是 | 能通知后端停止。为 false 时不显示停止按钮。 | |
runtime.capabilities.history | boolean | 是 | 能拉取会话历史。 | |
runtime.capabilities.historyPaging | boolean | 是 | 能向前翻页加载更早的历史。 | |
runtime.capabilities.resume | boolean | 是 | 断线后能续接仍在运行的一轮。 | |
runtime.capabilities.steer | boolean | 是 | 运行中能插话。 | |
runtime.capabilities.regenerate | boolean | 是 | 能重新生成。 | |
runtime.capabilities.edit | boolean | 是 | 能编辑后重发。 | |
runtime.capabilities.acceptedFileTypes | readonly string[] | 支持的附件类型（同 <input accept> 的写法）；不给表示不限制。 | ||
runtime.capabilities.attachmentCapabilities | readonly AttachmentCapability[] | 支持的 MIME 与存储来源组合；最终资源必须匹配一项，避免把类型与来源当作任意组合。 |
#root
实例根节点的类名与样式
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
root | ChatkitRootConfig | 实例根节点 .chatkit-wrapper 的类名与内联样式，可在此覆盖公开 CSS token。 | ||
root.className | string | 追加到 .chatkit-wrapper 的类名。 | ||
root.style | CSSProperties & { [key: `--${string}`]: string | number; } | 根节点样式；默认高度为 100%，可在此覆盖。 |
#theme
实例明暗模式
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
theme | ChatkitThemeConfig | 实例明暗模式；未传时继承最近有效宿主主题。 | ||
theme.appearance | "light" | "dark" | "inherit" | inherit 跟随最近的主题祖先，没有有效祖先时使用浅色。 |
#settings
设置：只填值（文字、数字、开关），不放函数和界面内容
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
settings | ChatkitSettings | 设置：只放值（文字、数字、开关），不放函数和界面内容。 | ||
settings.locale | "zh-CN" | "en-US" | 'zh-CN' | 界面语言。 | |
settings.placeholder | string | 随 locale | 输入框占位文字。 | |
settings.welcome | string | 空会话的欢迎语。 | ||
settings.recommendations | readonly string[] | 推荐问题，点一条直接发出。 | ||
settings.maxWidth | number | 800 | 消息区与输入框的最大宽度（像素）。 | |
settings.conversationNavigation | boolean | true | 左侧对话轮次导航；对话满三轮才显示。 | |
settings.composer | ChatkitComposerSettings | 输入框。 | ||
settings.composer.sendTip | string | 发送按钮的提示文字；空草稿禁用时仍可悬停显示。 | ||
settings.composer.hidden | boolean | false | 隐藏输入框（只读回放）。 | |
settings.composer.disabled | boolean | false | 禁用输入框：不能输入也不能发送。 | |
settings.composer.disabledReason | string | 禁用时替换占位文字显示的原因，比如「网络已断开，恢复后可继续发送」。 | ||
settings.composer.allowSendWhileSending | boolean | true | 回答生成中是否允许继续发送。发送队列由 ChatKit 管理；设为 false 时，生成中按钮固定为停止，回车变成换行。 | |
settings.toolFlow | "group" | "step" | "none" | 'group' | 执行过程的显示方式：group 合并成可折叠的执行流；step 逐个工具一行；none 不显示。 | |
settings.tools | ChatkitToolsSettings | 工具调用。 | ||
settings.tools.groupDefaultExpanded | boolean | false | 执行流默认是否展开。没有设置时跟着 reasoning.defaultExpanded 走。 | |
settings.tools.detailDefaultExpanded | boolean | false | 单个工具的详情（入参 / 结果）默认是否展开。 | |
settings.reasoning | ChatkitReasoningSettings | 思考过程。 | ||
settings.reasoning.visible | boolean | true | 是否显示思考过程。 | |
settings.reasoning.defaultExpanded | boolean | false | 思考结束后是否保持展开（输出中始终展开）。打开后，这一轮完成时执行过程不再收起、执行流默认展开； 单独设置了 runStatus.collapseOnComplete 或 tools.groupDefaultExpanded 的，以单独设置为准。 | |
settings.runStatus | ChatkitRunStatusSettings | 每一轮回答顶部的状态行。 | ||
settings.runStatus.visible | boolean | true | 是否显示状态行。关掉后执行过程也不再随它收起。 | |
settings.runStatus.collapseOnComplete | boolean | true | 完成后是否收起这一轮的执行过程，只留最终回答。没有设置时，reasoning.defaultExpanded 打开则不收起。 | |
settings.runStatus.longWaitThresholdMs | number | 15000 | 迟迟没有首个产出时，把「正在思考」换成「等待模型响应」的等待阈值（毫秒）；设为 0 关闭这个提示。 | |
settings.answerPending | { visible?: boolean; text?: string; } | 回答正文首字出现前的提示；只控制这条提示，不改变运行状态或业务卡片。 | ||
settings.answerPending.visible | boolean | true | 是否显示提示；纯业务卡片可关闭，由宿主自行提供等待反馈。 | |
settings.answerPending.text | string | 当前语言的内置文案 | 提示文字；不传时随 locale 使用内置中英文。 | |
settings.linkFavicon | boolean | true | 正文外链前显示站点图标。 | |
settings.userMessages | { contentAsMarkdown?: boolean; actions?: { copy?: boolean; }; } | 用户消息的 Markdown 与复制策略。 | ||
settings.userMessages.contentAsMarkdown | boolean | 用户消息正文按 Markdown 展示。默认 false。 | ||
settings.userMessages.actions | { copy?: boolean; } | 用户消息操作。 | ||
settings.initialScrollPosition | "top" | "bottom" | 首次挂载时的滚动位置。 | ||
settings.emptyState | { composerPlacement?: "bottom" | "embedded"; renderWhenLoading?: boolean; } | 空会话中输入框的位置与加载期显示策略。 | ||
settings.emptyState.composerPlacement | "bottom" | "embedded" | 自定义空态插槽可嵌入原生输入框；默认 bottom。 | ||
settings.emptyState.renderWhenLoading | boolean | 加载历史时继续渲染自定义空态；默认 false。 |
#bindings
bindings
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
bindings | ChatkitComposerBindings | 输入框与宿主编辑器的绑定；不持有运行状态。 | ||
bindings.ref | { current: ComposerRef; } | 命令式操作输入框：setText / insertText / setContent / getContent / focus / submit / undo / redo / 追加已上传附件。 | ||
bindings.ref.current | ComposerRef | 是 | 由 Chatkit 在挂载后赋值。 | |
bindings.onKeyDown | (event: KeyboardEvent, context: ChatkitComposerRenderContext) => void | 输入框的键盘事件，用来加自定义快捷键。 | ||
bindings.beforeSubmit | (context: ChatkitComposerBeforeSubmitContext) => ChatkitComposerBeforeSubmitResult | Pr… | 结构化内容编码前的异步提交门禁；拒绝时保留草稿。 | ||
bindings.senderProps | ChatkitSenderPassthroughProps | 透传给底层输入组件的属性；@ 提及与 / 指令在 richTextAreaProps.mentionConfig / slashCommandConfig 里配。 | ||
bindings.richText | { messageCodec?: RichTextMessageCodec; tagRenderer?: ChatkitRichTextTagRenderer; scopeK… | 富文本（标签、引用）的编解码与渲染。 | ||
bindings.richText.messageCodec | RichTextMessageCodec | 正文与标签、引用之间的编解码：发送时怎么编码成消息内容，回填草稿时怎么还原。 | ||
bindings.richText.tagRenderer | ChatkitRichTextTagRenderer | 自定义正文里标签（提及、文件、技能）的画法。 | ||
bindings.richText.scopeKey | string | 当前输入框的数据作用域（如实例 ID）；写入上传标签，供跨作用域粘贴时判断身份是否仍然有效。 | ||
bindings.richText.transformPastedTag | (attrs: ChatkitRichTextTagAttrs) => RichTextValue[] | 粘贴时逐个处理标签：返回 undefined 保留原标签，返回内容数组替换该标签（空数组表示移除）。 用于把目标输入框中无法使用的标签降级为文本，或转换为可用引用。 | ||
bindings.richText.onPastedTagsReplaced | (attrs: readonly ChatkitRichTextTagAttrs[]) => void | 本次粘贴有标签被替换时回调一次，参数为被替换标签的原始属性。 |
#transformParts
transformParts
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
transformParts | ChatkitRenderPartsTransform | 渲染前的纯消息片段变换；不写回运行时 Store。 |
#features
内置功能：条件满足就显示，每一项都可以用 false 关掉；带控件的功能可以用 slot 换位置
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
features | ChatkitFeatures | 内置功能的开关与参数。 | ||
features.promptCompletion | false | ChatkitPromptCompletionFeature | 输入框补全建议；默认关闭。 | ||
features.promptCompletion.items | readonly ChatkitPromptCompletionItem[] | 是 | 按显示顺序提供候选；空白候选会被忽略。 | |
features.promptCompletion.rotateIntervalMs | number | false | 自动轮换间隔（毫秒）；false 关闭轮换，默认 5000。聚焦输入区或系统要求减少动态效果时停止轮换。 | ||
features.promptCompletion.renderChip | (props: ChatkitPromptCompletionChipProps) => ReactNode | 自定义 chip 的非交互视觉内容，可传 React 组件或渲染函数。 返回值会放在 Chatkit 的原生按钮内；不得包含 button、link、input、其他可聚焦后代或设计系统 Button。 点击、键盘与焦点行为由 Chatkit 的外层按钮负责。ReactNode 类型无法静态检查后代的 DOM 语义。 | ||
features.promptCompletion.chipLayout | "auto" | "new-line" | chip 与候选的排布；new-line 让 chip 独占下一行，默认 auto。 | ||
features.promptCompletion.onAccept | (item: ChatkitPromptCompletionItem, context: { trigger: "tab" | "click"; action: "fill"… | 草稿成功写入后通知宿主；编辑器拒绝写入（如超过长度限制）时不调用，返回值不能取消写入。 trigger: 'tab' 表示输入区的 Tab 快捷键；trigger: 'click' 表示 chip 按钮激活， 包括鼠标／触摸点击以及聚焦按钮后按 Enter 或 Space，不代表输入设备一定是鼠标。 action: 'fill' 表示首次填入空草稿，action: 'replace' 表示切换本功能填入且未编辑的草稿。 | ||
features.attachments | false | ChatkitAttachmentsFeature | 附件。 | ||
features.attachments.renderIcon | (attachment: ChatkitMessageAttachment) => ReactNode | 消息文件的图标。 | ||
features.attachments.composerEnabled | boolean | 只配置历史附件展示时可关闭输入框上传。 | ||
features.attachments.upload | (file: File, context?: ChatkitAttachmentUploadContext) => Promise<UploadResult> | 上传实现。 | ||
features.attachments.maxTotalSize | number | 5242880 | 单次发送的附件总大小上限（字节）。 | |
features.attachments.accept | UploadAccept | 允许选择的文件类型，同 <input accept> 的写法；不给时用后端声明支持的类型。 | ||
features.attachments.onPreview | (attachment: ChatkitMessageAttachment) => void | 点了消息或输入框里的附件时调用，由接入方打开自己的预览。 | ||
features.attachments.slot | false | ChatkitToolbarSlotName | 'composer.toolbarStart' | 附件按钮的位置；false 表示不自动放，由接入方自己摆。 | |
features.attachments.actions | ChatkitAttachmentAction[] | 附件菜单里的快捷操作（标题 + 预设提示词）：点了把提示词填进输入框，并触发 onEvent 的 prompt_click。 | ||
features.attachments.onFileAccepted | (file: File) => void | 最终转换及校验通过后、请求开始前调用。 | ||
features.attachments.onReject | (file: File, reason: string) => void | 文件被类型、转换或上传准入校验拒绝时调用。 | ||
features.attachments.tips | string | 上传按钮的悬停提示。 | ||
features.attachments.multiple | boolean | 是否允许一次选多个文件。 | ||
features.attachments.autoUpload | boolean | true | 选完文件立即上传。 | |
features.attachments.onProgress | (file: UploadItem, params: { percent: number; e?: ProgressEvent<EventTarget>; fileList:… | 上传进度。 | ||
features.attachments.onError | (file: UploadItem, params: { response?: FileResponse; fileList: UploadItem[]; }) => void | 单个文件上传失败。 | ||
features.attachments.onReupload | (file: UploadItem) => void | 用户点了重新上传。 | ||
features.attachments.onRemove | (file: UploadItem, params: { fileList: UploadItem[]; }) => boolean | Promise<boolean> | 用户移除了一个文件；返回 false 阻止移除。 | ||
features.attachments.transformFile | (file: File) => File | Promise<File> | 选文件后、发起上传前对文件做转换（例如 HEIC → JPEG）。返回新的 File 或原文件。 | ||
features.attachments.dragAndDropEnabled | boolean | 是否允许把文件拖进上传区域直接上传，默认 true。 | ||
features.attachments.limit | number | 最多几个文件。 | ||
features.attachments.onExceedLimit | (file: File, fileList: UploadItem[]) => void | 超过 limit 时调用。 | ||
features.attachments.style | CSSProperties | 上传入口的内联样式。 | ||
features.attachments.children | ReactNode | 自定义上传入口的内容。 | ||
features.attachments.uploaderProps | ChatkitAttachmentUploaderProps | 透传给上传组件的属性。 | ||
features.attachments.mode | "strip" | "inline" | 'strip' | 附件交互模式：strip 使用附件栏并在编辑消息时锁定附件；inline 在光标处插入附件， 发送后保持混排，编辑消息时可移动或删除附件。 | |
features.attachments.allowUploaded | boolean | 允许程序化添加已上传资源，无需本地上传实现。 | ||
features.attachments.unavailableReason | string | 上传不可用时向用户显示的原因。 | ||
features.attachments.resolvePreviewUrl | ChatkitResolveAttachmentPreviewUrl | 按需解析消息或已恢复 composer 附件的预览 URL。 1. attachment.url 可能是工作区路径或容器内路径，浏览器无法直接作为 <img src> 加载。 2. 接入方可在这里异步换成可访问 URL，例如经自己的文件服务读取后返回 Blob URL。 3. 返回 revoke 时 Chat UI 会在图片或附件卡片卸载、地址切换时调用，避免 Blob URL 泄漏。 | ||
features.attachments.onMaxTotalSizeExceeded | (message: string) => void | 超过总大小上限时调用，参数是给用户看的提示文案。 | ||
features.attachments.onEvent | (event: ChatkitAttachmentEvent) => void | 附件入口的交互事件：点了上传（upload_click）、点了快捷操作（prompt_click）。 | ||
features.feedback | false | ChatkitFeedbackFeature | 赞踩。 | ||
features.feedback.onRate | (rating: "like" | "dislike", message: ChatkitRenderMessage) => void | 是 | 点了赞或踩时调用。 | |
features.feedback.getKey | (message: ChatkitRenderMessage) => string | 从消息取反馈键；返回 undefined 时该消息不显示反馈。 | ||
features.feedback.ratings | Record<string, "like" | "dislike"> | 每条回答的选中态，按 getKey 的结果索引；未提供 getKey 时用消息 id。 | ||
features.mentions | false | ChatkitMentionsFeature | @ 提及与 / 指令。 | ||
features.mentions.mention | ChatkitMentionConfig | @ 提及的候选项。 | ||
features.mentions.slash | ChatkitSlashCommandConfig | / 指令的候选项。 | ||
features.voice | false | ChatkitVoiceFeature | 语音输入。 | ||
features.voice.recognize | ChatkitSpeechRecognizer | 是 | 语音识别实现。 | |
features.voice.slot | false | ChatkitToolbarSlotName | 'composer.toolbarEnd' | 语音按钮的位置；false 表示不自动放，由接入方自己摆。 | |
features.copy | boolean | true | 复制回答。 | |
features.regenerate | boolean | true | 重新生成；需要后端支持。 | |
features.edit | boolean | true | 编辑后重发；需要后端支持。 | |
features.selectionAsk | boolean | true | 划词追问。 |
#slots
插槽：在界面的固定位置放业务组件
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
slots | ChatkitSlots | 插槽：在界面的固定位置放自己的内容。 | ||
slots.header | ChatkitStackSlot<ChatkitHeaderSlotContext> | 顶栏，在消息区上方；默认没有内容。 | ||
slots.header.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.header.render | ChatkitSlotRender<ChatkitHeaderSlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.header.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.session.top | ChatkitStackSlot<ChatkitEmptySlotContext> | 消息列表上方，比如公告。 | ||
slots.session.top.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.session.top.render | ChatkitSlotRender<ChatkitEmptySlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.session.top.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.session.bottom | ChatkitStackSlot<ChatkitEmptySlotContext> | 消息列表下方、输入框上方。 | ||
slots.session.bottom.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.session.bottom.render | ChatkitSlotRender<ChatkitEmptySlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.session.bottom.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.session.empty | ChatkitSlotItem<ChatkitSessionEmptySlotContext> | 空会话时显示的内容；只放一项，替换默认的欢迎语与推荐问题。 | ||
slots.session.empty.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.session.empty.render | ChatkitSlotRender<ChatkitSessionEmptySlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.session.empty.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.message.header | ChatkitStackSlot<ChatkitMessageSlotContext> | 每条回答的头部，在正文之前。 | ||
slots.message.header.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.message.header.render | ChatkitSlotRender<ChatkitMessageSlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.message.header.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.message.footer | ChatkitStackSlot<ChatkitMessageSlotContext> | 每条消息的尾部，在消息之后。 | ||
slots.message.footer.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.message.footer.render | ChatkitSlotRender<ChatkitMessageSlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.message.footer.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.message.actions | ChatkitStackSlot<ChatkitMessageSlotContext> | 回答下方的操作栏，排在复制、赞踩之后。 | ||
slots.message.actions.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.message.actions.render | ChatkitSlotRender<ChatkitMessageSlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.message.actions.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.message.selection | ChatkitStackSlot<ChatkitMessageSelectionSlotContext> | 选中回答里的文字时出现的浮条。 | ||
slots.message.selection.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.message.selection.render | ChatkitSlotRender<ChatkitMessageSelectionSlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.message.selection.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.top | ChatkitStackSlot<ChatkitComposerRenderContext> | 输入框上方（输入框外）。 | ||
slots.composer.top.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.top.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.top.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.bottom | ChatkitStackSlot<ChatkitComposerRenderContext> | 输入框下方（输入框外），比如免责声明。 | ||
slots.composer.bottom.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.bottom.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.bottom.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.bodyTop | ChatkitStackSlot<ChatkitComposerRenderContext> | 输入框内、正文上方。 | ||
slots.composer.bodyTop.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.bodyTop.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.bodyTop.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.bodyBottom | ChatkitStackSlot<ChatkitComposerRenderContext> | 输入框内、正文下方。 | ||
slots.composer.bodyBottom.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.bodyBottom.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.bodyBottom.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.overlay | ChatkitStackSlot<ChatkitComposerRenderContext> | 盖在正文输入区上的一层，和文字起点对齐。 | ||
slots.composer.overlay.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.overlay.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.overlay.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.toolbarStart | ChatkitStackSlot<ChatkitComposerRenderContext> | 输入框工具栏左侧；放不下时靠后的项收进「更多」。 | ||
slots.composer.toolbarStart.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.toolbarStart.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.toolbarStart.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.toolbarEnd | ChatkitStackSlot<ChatkitComposerRenderContext> | 输入框工具栏右侧，发送按钮之前；放不下时靠后的项收进「更多」。 | ||
slots.composer.toolbarEnd.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.toolbarEnd.render | ChatkitSlotRender<ChatkitComposerRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.toolbarEnd.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.composer.sendButton | ChatkitSlotItem<ChatkitComposerSendButtonRenderContext> | 发送按钮；只放一项，替换默认按钮。 | ||
slots.composer.sendButton.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.composer.sendButton.render | ChatkitSlotRender<ChatkitComposerSendButtonRenderContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.composer.sendButton.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 | ||
slots.panel | ChatkitStackSlot<ChatkitPanelSlotContext> | 右侧面板；放了内容就显示，也可以用 openPanel 打开。 | ||
slots.panel.key | string | 这一项的标识；同一个位置放多项、且会增减时给出，避免界面状态串位。 | ||
slots.panel.render | ChatkitSlotRender<ChatkitPanelSlotContext> | 是 | 要放的内容：节点，或拿到这个位置上下文的函数。 | |
slots.panel.order | number | 负数排在内置功能之前；不写排在内置功能之后；正数排在最后，小的在前。 |
#renderers
渲染器：按类型登记业务卡片、工具、失败卡片、Markdown 元素、系统提示的显示方式
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
renderers | ChatkitRenderers | 渲染器：按类型登记业务卡片、工具、失败卡片、Markdown 元素、系统提示的画法。 | ||
renderers.message | ChatkitMessageRenderer | 包装单条消息的默认节点。 | ||
renderers.part | ChatkitMessagePartRenderer | 包装片段的默认节点，包含正文与业务片段。 | ||
renderers.customParts | Record<string, CustomPartRenderer> | 字符串载荷的业务片段，按 customComponentId 登记。 | ||
renderers.assistantActions | false | AssistantMessageActionsConfig | 回答操作栏，可复用默认操作节点。 | ||
renderers.assistantActions.copy | boolean | 是否展示默认复制按钮。默认 true。 | ||
renderers.assistantActions.feedback | boolean | 是否展示默认点赞/点踩按钮。默认 true，但仍需要传入 onLikeMessage / onDislikeMessage 才会显示。 | ||
renderers.assistantActions.className | string | 操作条容器 className。 | ||
renderers.assistantActions.render | (context: AssistantMessageActionsRenderContext) => ReactNode | 完全自定义 assistant 消息操作条。返回 undefined 时使用默认操作条，返回 null 时隐藏。 | ||
renderers.identity | { team?: TeamConfig; avatars?: AvatarConfig; } | 团队和头像的展示规则。 | ||
renderers.identity.team | TeamConfig | 团队成员展示。 | ||
renderers.identity.avatars | AvatarConfig | 消息头像展示。 | ||
renderers.loading | ReactNode | (() => ReactNode) | 加载历史时的空态占位。 | ||
renderers.linkFavicon | (url: URL) => string | 外链图标的解析规则。 | ||
renderers.parts | Record<string, ChatkitDataPartRenderer> | 业务卡片：按数据类型（产品名.类型）登记；登记成 null 表示不显示。 | ||
renderers.tools | Record<string, ChatkitToolRenderer> | 工具：按工具名登记。 | ||
renderers.errors | Record<string, ChatkitErrorRenderer> | 失败卡片：按错误码登记，* 兜底。 | ||
renderers.markdown | Record<string, ComponentType<any>> | Markdown 元素：按标签名登记组件。 | ||
renderers.events | Record<string, ConversationEventRenderer> | 系统提示：按类型登记；登记成 null 表示不显示。 |
#onSend
发送前处理：改写输入，或拦下这次发送
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
onSend | ChatkitSendHandler | 发送前处理：可以改写输入，返回 false 拦下这次发送（草稿保留），不返回表示原样发送。 |
#onEvent
事件出口
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
onEvent | (event: ChatkitEvent) => void | 组件事件回调：发送、运行、工具、历史、每轮汇总与界面事件。SDK 不主动将遥测发送到监控服务；是否上报及上报目的地由接入方决定。 事件的扩充属性在 useChatSessions / useChatRuntime 的 eventAttributes 里给。 |
#onError
错误出口
| 配置项 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
onError | ChatkitErrorHandler | 非致命错误的出口，建议接到错误监控。第二个参数是来源（render、history、dispatch…）、所属会话与轮次、能否自愈。 会话 hook 上没给 onError 时，那边的错误（拉历史、续接、派发、事件订阅方抛错…）也交到这里。 |