Conversation Stream
虚拟滚动、自动吸底、向上加载历史的会话流
用法
基础
Loading demo...
最佳实践
itemKey用消息自身的 id,不用下标;虚拟化依赖稳定的 key。- 在
loadOlder中自行前插数据,再 resolve{ hasMore };组件不持有消息数组。 - 确认没有历史时显式传
hasMoreInitial: false;默认的undefined表示未知。 estimatedItemHeight贴近真实平均高度,避免首屏滚动条跳动。- 程序化滚动用暴露的
scrollToBottom、scrollToIndex,不要直接操作滚动容器。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | T[] | — | 消息数组,必填。 |
itemKey | ConversationStreamItemKey<T> | — | 稳定 key:字段名,或返回 key 的函数。必填。 |
estimatedItemHeight | number | 96 | 未测量项的假定高度,测量后自动校正。 |
overscan | number | 4 | 可视区上下各多渲染的条数。 |
loadOlder | () => Promise<ConversationStreamLoadResult> | — | 接近顶部时调用;前插数据后 resolve { hasMore }。 |
hasMoreInitial | boolean | undefined | 首次 loadOlder 返回前是否可能有历史。 |
streaming | boolean | false | 驱动「回到底部」按钮的新内容状态。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
at-bottom-change | (atBottom: boolean) | 吸底状态变化时触发。 |
load-error | (error: unknown) | loadOlder 抛错时触发。 |
插槽
| 插槽名 | 作用域参数 | 说明 |
|---|---|---|
item | { item: T, index: number } | 渲染单条消息。 |
empty | — | items 为空时的占位。 |
top-loading | — | 加载更早消息时显示。 |
top-error | { retry: () => void } | 加载失败时显示,带重试回调。 |
top-done | — | 没有更早消息时显示。 |
scroll-to-bottom | { streaming: boolean } | 替换「回到底部」按钮的内容。 |
暴露方法
| 名称 | 类型 | 说明 |
|---|---|---|
scrollToBottom | (behavior?: ScrollBehavior) => void | 滚动到底部。 |
scrollToIndex | (index: number) => void | 滚动到指定索引。 |
tweenToBottom | (duration?: number) => Promise<boolean> | 以固定时长滑到底部;被打断时 resolve false。 |
atBottom | boolean | 当前是否在底部,只读。 |
概述
- 泛型组件:
items的元素类型直接传到item插槽的作用域,无需断言。 - 停在底部时新内容自动跟随;用户向上滚动后不再拉回,改为显示「回到底部」按钮。
streaming只影响按钮的新内容状态,不决定是否吸底。- 组件自己滑向底部时(发送后、程序化滚动),不显示「回到底部」按钮。
- 前插历史后保持视口锚点。
hasMoreInitial的默认值是显式的undefined而非false,以区分「未知」与「没有历史」。
技术实现
- 可视窗口从位置缓存(按 key 记录测得高度的前缀和)取
{ start, end };未跨过行边界的滚动帧沿用上一窗口,不重新调用item插槽。 - 源码:
packages/tuffex/packages/components/src/conversation-stream/。
查看源码
packages/tuffex/packages/components/src/conversation-stream/index.ts