Chat

使用场景

Chat 组件可用于普通会话，AI 会话等场景。

对话内容渲染基于 MarkdownRender 组件，可实现图片、表格、链接、加粗、代码区等常用富文本功能。

Chat 中的 MarkdownRender 使用 format="md"。本库的 MarkdownRender 不支持 MDX（Svelte 无 jsx-runtime，详见该组件页说明）；需要在对话内容中渲染自定义组件时，通过 markdownRenderProps 透传 components 注册标签。

附件支持通过点击上传按钮、输入框粘贴、拖拽文件至 Chat 区域上传。通过 uploadProps 设置上传参数，详情参考 Upload。

上传按钮的提示文案可通过 uploadTipProps 设置，详情参考 Tooltip。

对话是多方参与、多轮交互的场景。可通过 roleConfig 传入角色信息（包括名称、头像等），具体参数细节见 RoleConfig。

使用 align 属性可以设置对话的布局，支持左右分布（leftRight，默认）和左对齐（leftAlign）。

代码演示

如何引入

import { Chat } from '@chenzy-design/svelte';

基本用法

通过设置 chats 和 onChatsChange、onMessageSend 实现基础对话显示和交互。

消息状态

chats 类型为 Message[]，Message 包含对话的各种信息，如角色（role）、内容（content）、附件（attachment）、状态（status）、唯一标识（id）、创建时间（createAt）等，具体见 Message。其中 status 不同，会话样式不同。

动态更新数据

对于后台返回 Server-Sent Events 数据的情况，可将获取到的数据用于更新 chats，对话内容将实时更新。发送消息后先插入 loading 状态的回复，待异步内容返回后原地更新为完整内容。

showStopGenerate 参数可用于设置是否展示停止生成按钮，默认为 false，可以在 onStopGenerator 中处理停止生成逻辑。

清除上下文

通过 showClearContext 可以开启在输入框中显示清除上下文按钮，默认为 false。点击后在消息末尾追加一条分割线，可通过 onClear 感知；也可以通过 ref 调用 clearContext 方法清除上下文。

自定义渲染会话框

通过 renderChatBoxAvatar、renderChatBoxTitle、renderChatBoxContent、renderChatBoxAction 分别自定义头像、标题、内容与操作区，各 snippet 的参数类型如下（对齐 Semi ChatBoxRenderConfig 收纳的各接口；本库走扁平 prop，无需 chatBoxRenderConfig 聚合对象）：

export interface RenderTitleProps {
  message?: Message;
  role?: Metadata;
  defaultTitle?: Snippet;
}

export interface RenderAvatarProps {
  message?: Message;
  role?: Metadata;
  defaultAvatar?: Snippet;
}

export interface RenderContentProps {
  message?: Message;
  role?: Metadata;
  defaultContent?: Snippet;
  className?: string;
}

export interface DefaultActionNodeObj {
  copyNode?: Snippet;
  likeNode?: Snippet;
  dislikeNode?: Snippet;
  resetNode?: Snippet;
  deleteNode?: Snippet;
}

export interface RenderActionProps {
  message?: Message;
  defaultActions?: Snippet;
  className?: string;
  defaultActionsObj?: DefaultActionNodeObj;
}

export interface FullChatBoxNodes {
  avatar?: Snippet;
  title?: Snippet;
  content?: Snippet;
  action?: Snippet;
}

export interface RenderFullChatBoxProps {
  message?: Message;
  role?: Metadata;
  defaultNodes?: FullChatBoxNodes;
  className?: string;
}

通过 renderChatBoxAvatar、renderChatBoxTitle 自定义头像和标题：

鼠标移动到会话上，即可显示会话操作区，通过 renderChatBoxAction 自定义渲染操作区。defaultActionsObj 提供拆分好的默认操作节点（copyNode / likeNode / dislikeNode / resetNode / deleteNode），可与自定义节点（如 Dropdown 菜单）自由组合。

通过 renderChatBoxContent 自定义内容区域，可在消息正文之外叠加自定义结构（如搜索来源折叠卡片）。

完全自定义会话框

通过 renderFullChatBox 拿到拆分好的节点（avatar / title / content / action），自由组合整条消息的布局。

自定义渲染输入框

通过 renderInputArea 自定义输入区，参数如下：

export interface RenderInputAreaProps {
  /** 默认节点 */
  defaultNode?: Snippet;
  /** 如果自定义输入框，发送消息时需调用 */
  onSend?: (content?: string, attachment?: FileItem[]) => void;
  /** 如果自定义清除上下文按钮，点击清除上下文时需调用 */
  onClear?: () => void;
  /** 拆分节点，供自定义布局时挑选组合 */
  detailProps?: {
    /** 清除上下文按钮 */
    clearContextNode?: Snippet;
    /** 上传按钮 */
    uploadNode?: Snippet;
    /** 文本输入框 */
    inputNode?: Snippet;
    /** 发送按钮 */
    sendNode?: Snippet;
    /** 点击触发聚焦文本输入框的处理函数 */
    onClick?: () => void;
  };
}

既可包裹默认节点 defaultNode，也可用 detailProps 拆分节点自由组合，detailProps 的使用示例如下：

{#snippet inputAreaSnippet({ detailProps }: ChatRenderInputAreaProps)}
  <div
    style="margin:8px 16px;display:flex;flex-direction:row;align-items:flex-end;border-radius:16px;padding:10px;border:1px solid var(--cd-color-border);"
    onclick={detailProps?.onClick}
  >
    {@render detailProps?.uploadNode?.()}
    {@render detailProps?.inputNode?.()}
    {@render detailProps?.sendNode?.()}
  </div>
{/snippet}

其他使用示例如下：

提示信息

通过 hints 可设置提示区域内容，点击提示内容后，提示内容将成为新的用户输入内容，并触发 onHintClick 回调。

自定义提示信息渲染

通过 renderHintBox 自定义提示区域内容，参数如下：

interface RenderHintBoxProps {
  content: string;
  index: number;
  onHintClick: () => void;
}
// renderHintBox?: Snippet<[RenderHintBoxProps]>

API

属性	说明	类型	默认值
align	对话布局方式，支持 leftRight、leftAlign	string	leftRight
bottomSlot	底部插槽	Snippet	-
canSend	发送按钮是否可以发送。通常无需设置，由内部逻辑决定；如有设置，以此设置为准	boolean	-
chats	受控对话列表	Message[]	-
class	自定义类名	string	-
enableUpload	是否启用上传。传 boolean 同时控制拖拽、点击上传按钮、粘贴上传；传对象可分别设置，未设置的项默认为 true	boolean \| { pasteUpload: boolean, clickUpload: boolean, dragUpload: boolean }	true
escapeHtml	是否对用户消息中的 HTML 标签进行转义，防止被 Markdown 解析器当作 HTML 处理导致内容丢失	boolean	true
hintCls	提示区最外层样式类名	string	-
hintStyle	提示区最外层样式	string	-
hints	提示信息	string[]	-
inputBoxCls	输入框类名	string	-
inputBoxStyle	输入框样式	string	-
markdownRenderProps	透传给对话内容渲染所用的 MarkdownRender 组件，详见 MarkdownRenderProps	object	-
mode	对话模式，支持 bubble、noBubble、userBubble	string	bubble
onChatsChange	对话列表变化时触发	(chats: Message[]) => void	-
onClear	清除上下文消息时候触发	() => void	-
onHintClick	点击提示信息时触发	(hint: string) => void	-
onInputChange	输入区域信息变化时触发	(props: { value: string, attachment: FileItem[] }) => void	-
onMessageBadFeedback	消息负向反馈时触发	(message: Message) => void	-
onMessageCopy	复制消息时触发	(message: Message) => void	-
onMessageDelete	删除消息时触发	(message: Message) => void	-
onMessageGoodFeedback	消息正向反馈时触发	(message: Message) => void	-
onMessageReset	重置消息时触发	(message: Message) => void	-
onMessageSend	发送消息时触发	(content: string, attachment: FileItem[]) => void	-
onStopGenerator	点击停止生成按钮时触发	() => void	-
placeholder	输入框占位符	string	-
renderChatBoxAction	自定义渲染操作区	Snippet<[RenderActionProps]>	-
renderChatBoxAvatar	自定义渲染头像	Snippet<[RenderAvatarProps]>	-
renderChatBoxContent	自定义渲染内容	Snippet<[RenderContentProps]>	-
renderChatBoxTitle	自定义渲染标题	Snippet<[RenderTitleProps]>	-
renderDivider	自定义渲染分割线	Snippet<[Message]>	-
renderFullChatBox	完全自定义渲染会话框	Snippet<[RenderFullChatBoxProps]>	-
renderHintBox	自定义渲染提示信息	Snippet<[RenderHintBoxProps]>	-
renderInputArea	自定义渲染输入框	Snippet<[RenderInputAreaProps]>	-
roleConfig	角色信息配置，具体见 RoleConfig	RoleConfig	-
sendHotKey	发送输入内容的键盘快捷键，支持 enter、shift+enter	string	enter
showClearContext	是否展示清除上下文按钮	boolean	false
showStopGenerate	是否展示停止生成按钮	boolean	false
style	内联样式	string	-
topSlot	顶部插槽	Snippet	-
uploadProps	上传组件属性，详情参考 Upload	UploadProps	-
uploadTipProps	上传组件提示属性，详情参考 Tooltip	TooltipProps	-

与 Semi 的差异：Semi 另有 chatBoxRenderConfig（把 5 个 renderChatBox* 收进一个对象）与 customMarkDownComponents。本库统一走扁平的 renderChatBox* snippet；自定义 Markdown 组件通过 markdownRenderProps.components 传入。

RoleConfig

属性	说明	类型	默认值
assistant	助手信息	Metadata	-
system	系统信息	Metadata	-
user	用户信息	Metadata	-

Metadata

属性	说明	类型	默认值
avatar	头像，支持图片 URL	string	-
color	头像背景色，同 Avatar 组件的 color 参数	string	grey
name	名称	string	-

Message

属性	说明	类型	默认值
content	文本内容	string \| Content[]	-
createAt	创建时间	number	-
id	唯一标识	string \| number	-
name	名称	string	-
parentId	父节点 id	string	-
role	角色	string	-
status	消息状态，可选值为 loading、incomplete、complete、error	string	complete

Content

属性	说明	类型	默认值
file_url	当类型为 file_url 时的内容数据	{ url: string; name: string; size: string; type: string }	-
image_url	当类型为 image_url 时的内容数据	{ url: string }	-
text	当类型为 text 时的内容数据	string	-
type	类型，可选值 text、image_url、file_url	string	-

Methods

方法	说明
clearContext	清除上下文
resetMessage	重置消息
scrollToBottom(animation: boolean)	滚动到最底部，animation 为 true 则有动画，反之无动画
sendMessage(content: string, attachment: FileItem[])	发送消息

设计变量

color

font

height

other

radius

spacing

width

变量	默认值	用法
--cd-chat-action-content-bg	var(--cd-color-bg-0)	返回底部/停止生成按钮背景
--cd-chat-action-content-bg-hover	var(--cd-color-tertiary-light-hover)	返回底部/停止生成按钮 hover 背景
--cd-chat-action-content-border	var(--cd-color-border)	返回底部/停止生成按钮描边
--cd-chat-attachment-clear-icon	var(--cd-color-text-2)	附件清除图标颜色
--cd-chat-attachment-fail	var(--cd-color-danger)	附件上传失败提示图标颜色
--cd-chat-attachment-file-bg	var(--cd-color-fill-0)	附件文件背景
--cd-chat-attachment-file-icon	var(--cd-color-text-2)	附件文件图标颜色
--cd-chat-attachment-file-metadata-text	var(--cd-color-text-2)	附件文件元数据文字颜色
--cd-chat-attachment-file-title	var(--cd-color-text-0)	附件文件标题颜色
--cd-chat-chatBox-action-bg-hover	transparent	操作区按钮 hover 背景

显示第 1 条-第 10 条，共 38 条

• 1
• 2
• 3
• 4