组件/Conversation Stream

Conversation Stream

虚拟滚动、自动吸底、向上加载历史的会话流

Verified自 0.3.9

用法

基础

Loading demo...

最佳实践

  • itemKey 用消息自身的 id,不用下标;虚拟化依赖稳定的 key。
  • 在 loadOlder 中自行前插数据,再 resolve { hasMore };组件不持有消息数组。
  • 确认没有历史时显式传 hasMoreInitial: false;默认的 undefined 表示未知。
  • estimatedItemHeight 贴近真实平均高度,避免首屏滚动条跳动。
  • 程序化滚动用暴露的 scrollToBottom、scrollToIndex,不要直接操作滚动容器。

API 参考

属性

属性名类型默认值说明
itemsT[]—消息数组,必填。
itemKeyConversationStreamItemKey<T>—稳定 key:字段名,或返回 key 的函数。必填。
estimatedItemHeightnumber96未测量项的假定高度,测量后自动校正。
overscannumber4可视区上下各多渲染的条数。
loadOlder() => Promise<ConversationStreamLoadResult>—接近顶部时调用;前插数据后 resolve { hasMore }。
hasMoreInitialbooleanundefined首次 loadOlder 返回前是否可能有历史。
streamingbooleanfalse驱动「回到底部」按钮的新内容状态。

事件

事件名参数说明
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。
atBottomboolean当前是否在底部,只读。

概述

  • 泛型组件: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