Bubble对话气泡
Bubble
对话气泡
用于聊天的气泡组件。
使用import { Bubble } from "@ant-design/x"; |
文档 编辑此页... |
常用于聊天的时候。
通用属性参考：通用属性
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| placement | 气泡位置 | start | end | start | - |
| loading | 加载状态 | boolean | - | - |
| loadingRender | 自定义加载内容渲染 | () => React.ReactNode | - | - |
| content | 气泡内容 | ContentType | - | - |
| contentRender | 自定义内容渲染 | (content: ContentType, info: InfoType ) => React.ReactNode | - | - |
| editable | 是否可编辑 | boolean | EditableBubbleOption | false | - |
| typing | 打字动画效果 | boolean | BubbleAnimationOption | ((content: ContentType, info: InfoType) => boolean | BubbleAnimationOption) | false | - |
| streaming | 是否为流式传输 | boolean | false | - |
| variant | 气泡样式变体 | filled | outlined | shadow | borderless | filled | - |
| shape | 气泡形状 | default | round | corner | default | - |
| footerPlacement | 底部插槽位置 | outer-start | outer-end | inner-start | inner-end | outer-start | - |
| components | 扩展槽位配置 | { header?: BubbleSlot; footer?: BubbleSlot; avatar?: BubbleSlot; extra?: BubbleSlot; } | - | - |
| onTyping | 动画执行回调 | (rendererContent: string, currentContent: string) => void | - | - |
| onTypingComplete | 动画结束回调 | (content: string) => void | - | - |
| onEditing | 编辑态下内容变化时回调 | (content: string) => void | - | - |
默认类型
type ContentType = React.ReactNode | AnyObject | string | number;
自定义类型使用
type CustomContentType {...}<Bubble<CustomContentType> {...props} />
type BubbleSlot<ContentType> =| React.ReactNode| ((content: ContentType, info: InfoType) => React.ReactNode);
interface EditableBubbleOption {/*** @description 是否可编辑*/editing?: boolean;/*** @description 确认按钮*/okText?: React.ReactNode;/*** @description 取消按钮*/cancelText?: React.ReactNode;}
interface BubbleAnimationOption {/*** @description 动画效果类型，打字机，渐入* @default 'fade-in'*/effect: 'typing' | 'fade-in';/*** @description 内容步进单位，数组格式为随机区间* @default 6*/step?: number | [number, number];/*** @description 动画触发间隔* @default 100*/interval?: number;/*** @description 重新开始一段动画时是否保留文本的公共前缀* @default true*/keepPrefix?: boolean;}
streaming 用于通知 Bubble 当前的 content 是否属于流式输入的当处于流式传输模。当处于流式传输模式，无论是否启用 Bubble 输入动画，在 streaming 变为 false 之前，Bubble 不会因为把当前 content 全部输出完毕就触发 onTypingComplete 回调，只有当 streaming 变为 false，且 content 全部输出完毕后，Bubble 才会触发 onTypingComplete 回调。这样可以避免由于流式传输不稳定而导致多次触发 onTypingComplete 回调的问题，保证一次流式传输过程仅触发一次 onTypingComplete。
在这个例子中，你可以尝试强制关闭流式标志，同时
onTypingComplete。onTypingComplete。| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| items | 气泡数据列表，key，role 必填 ，当结合X SDK useXChat 使用时可传入status 帮助 Bubble 对配置进行管理 | ((BubbleProps & DividerBubbleProps) & { key: string | number, role: string , status: MessageStatus, extra?: AnyObject})[] | - | - |
| autoScroll | 是否自动滚动 | boolean | true | - |
| role | 气泡角色默认配置 | RoleType | - | - |
type MessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
配合 useXChat 使用 ，key 可做为 MessageId，extra 可作为自定义参数。
type InfoType = {status?: MessageStatus;key?: string | number;extra?: AnyObject;};
export type RoleProps = Pick<BubbleProps<any>,| 'typing'| 'variant'| 'shape'| 'placement'| 'rootClassName'| 'classNames'| 'className'| 'styles'| 'style'| 'loading'| 'loadingRender'| 'contentRender'| 'footerPlacement'| 'components'| 'editable'| 'onTyping'| 'onTypingComplete'| 'onEditConfirm'| 'onEditCancel'>;export type FuncRoleProps = (data: BubbleItemType) => RoleProps;export type DividerRoleProps = Partial<DividerBubbleProps>;export type FuncDividerRoleProps = (data: BubbleItemType) => DividerRoleProps;export type RoleType = Partial<'ai' | 'system' | 'user', RoleProps | FuncRoleProps>> & { divider: DividerRoleProps | FuncDividerRoleProps } & Record<string,RoleProps | FuncRoleProps>;
Bubble.List 滚动托管需要设置 height，否则无法滚动。
<Bubble.List items={items} style={{ height: 500 }} autoScroll />
Bubble.List 的 role 和 items 两个属性都可以配置气泡，其中 role 的配置作为默认配置使用，可缺省。item.role 用于指明该条数据的气泡角色，会与 Bubble.List.role 进行匹配。items 本身也可配置气泡属性，优先级高于 role 的配置，最终的气泡配置为：{ ...role[item.role], ...item }。
特别说明，我们为 role 提供了四个默认字段，ai、user、system、divider。其中，system、divider 是保留字段，如果 item.role 赋值为它们俩之一，Bubble.List 会把这条气泡数据渲染为 Bubble.System (role = 'system') 或 Bubble.Divider (role = 'divider')。
因此，若你想自定义渲染系统消息或分割线时，应该使用其他的命名。
自定义渲染消息，可以参考这个例子中 reference 的渲染方式。
通用属性参考：通用属性
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| content | 气泡内容 | ContentType | - | - |
| variant | 气泡样式变体 | filled | outlined | shadow | borderless | shadow | - |
| shape | 气泡形状 | default | round | corner | default | - |
通用属性参考：通用属性
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| content | 气泡内容，等效 Divider.children | ContentType | - | - |
| dividerProps | Divider 组件属性 | Divider | - | - |
| Token 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| typingAnimationDuration | 打字动画持续时间 | string | 0.8s |
| typingAnimationName | 打字动画名称 | string | cursorBlink |
| typingContent | 打字动画内容 | string | | |
基础用法。
变体与形状，无边框样式 borderless 的 Bubble 适用于渲染自定义样式的内容。
气泡边栏与位置，位置 placement 会改变主次侧栏的位置。
系统信息 Bubble。
分割线 Bubble。
气泡头部，位置 placement 会改变头部的对齐方式。
气泡尾部，不受 placement 影响，需要通过 footerPlacement 来控制尾部的渲染位置。
通过 loading 属性控制加载状态。
动画效果，仅支持 content 是字符串或 contentRender 渲染字符串的情况下生效。非字符串场景需要自定义渲染动画。生效时，如果 content 不变，而其他配置发生变化，动画不会重新执行。
流式传输。可以传递 streaming 来通知 Bubble 当前的 content 是否属于流式输入的。
自定义渲染内容。
配合 x-markdown 实现自定义渲染内容。
配合 @antv/GPT-Vis 实现大模型输出的图表渲染，支持模型流式输出。
可编辑气泡，支持 string 类型 content 的简单编辑，使用时应该在 onEditing 处进行 XSS 防护。
预设样式的气泡列表，支持自动滚动，支持使用 role 定义不同类别的气泡并设置属性。Bubble.List 是一个受控组件，内部对 Bubble 做了 memo 处理，因此推荐使用 setState 的回调形式来修改 items 属性，尽可能保证非必要渲染数据项的配置稳定，以此来保证 Bubble.List 的高性能渲染。
可以使用 ref 控制列表滚动条。
示例通过语义化以及加载定制，来调整气泡效果。
配合扩展参数实现自定义扩展能力。
