Skip to content

fix(chat): 消除消息列表的滚动抖动与大片空白 - #189

Closed
ayuanjc wants to merge 1 commit into
anyme123:mainfrom
ayuanjc:fix/chat-scroll-jitter
Closed

ayuanjc wants to merge 1 commit into
anyme123:mainfrom
ayuanjc:fix/chat-scroll-jitter

Conversation

@ayuanjc

@ayuanjc ayuanjc commented Sep 13, 2026

Copy link
Copy Markdown

聊天区在流式输出和滚动时会上下抖动,列表底部还会出现滚不到内容的空白。
根因有四个,都是"有多个写入者同时改滚动位置"或"在测量对象上做高度动画":

  1. 虚拟列表行上的 transform 入场动画 行是 motion.div,带 initial={{y:8}},外面套 AnimatePresence 的 exit。 行每次进出虚拟窗口都要从 +8px 滑入、退出时还要留在 DOM 里, 于是整列持续上下抖。另外 MessageBubble 的 scale:0.995→1 会被 getBoundingClientRect 量进高度(自定义的 measureElement 用了它), 导致每行先记一个偏小的高度、动画结束后再修正一次。 改为纯 div,不再覆盖 measureElement —— 库默认实现会用 ResizeObserver 的 borderBoxSize,不受 transform 影响。顺带删掉行组件里自挂的 ResizeObserver: 把元素交给虚拟列表的 measureElement 时它内部已经建了一个,原来是每行测两遍。

  2. 浏览器的 scroll anchoring 在背后改 scrollTop 贴底时上方一个思考块收起(高度少几百像素),浏览器为保持锚点元素的视觉位置 会自行把 scrollTop 拉走几百像素,贴底逻辑再拉回来,一缩一拉就是抖动。 实测时间线:内容高度没变而 scrollTop 单独跳了 -956px,下一帧内容才缩 959px。 给滚动容器加 overflow-anchor: none,位置由 useSmartAutoScroll 独家管理。

  3. 虚拟列表自己也在补偿滚动位置,与贴底互相拉锯 3.13 的 resizeItem 在行高变化时会补偿 scrollTop。流式输出的最后一行往往比 视口还高,它的 start 一直小于 scrollTop,于是每测量一次就补偿一次。 接上 shouldAdjustScrollPositionOnItemSizeChange:贴底时返回 false (位置由 hook 独家负责),用户翻历史时返回 true(走默认逻辑,否则上方行一变高 用户正在看的内容就会被顶走)。注意这是 Virtualizer 的实例属性,不是构造选项。

  4. 行内折叠块的高度动画 ThinkingBlock 的 max-h 过渡、SubagentMessageGroup 的 animate={{height:'auto'}}, 动画的正是虚拟列表正在测量的那个元素:连续多帧改行高,每帧都要重测并重排 后续所有行。改为一次到位,只留一次高度变化(展开/收起的时机与逻辑不变)。

另外重写了 useSmartAutoScroll。原实现有 5 个 useEffect 抢着写 scrollTop (含流式期间常驻的 100ms rAF 循环、一次性的 8 次 setInterval、两个内容哈希触发的 延迟滚动),混用 behavior:'smooth' 和 'auto',每个 chunk 都在打断上一个平滑动画; 每次渲染还要对最后一条消息做一次 JSON.stringify 求长度。
现在收敛为单一数据流:ResizeObserver 观察内容真实高度 → 瞬时贴底。

其中"用户是否离开底部"改为只认真实输入事件(wheel / touch / 滚动条拖拽 / 翻页键)。 不能用距底部的距离判断:初始加载时虚拟列表逐行把估计高度换成实测高度,rail 每帧
能变几百像素;流式输出时最后一行持续长高。这两种情况下距离每帧都会超出容差,
拿它当依据会在第一次贴底之后立刻把自己关掉、之后再也不跟随输出。

同时把 rail 高度改为 GUTTER_TOP + getTotalSize() + GUTTER_BOTTOM,让 scrollHeight 与虚拟列表的总高度处于同一坐标系(原来是滚动容器 padding 在 getTotalSize() 之外, 绝对定位的行又是相对 rail 的 padding box 定位,两套坐标对不上,底部就有一段
滚不到内容的假空白)。estimateSize 也不再按消息类型猜高度——那种猜法既不准,
又要在每次布局时遍历每组的每条消息。

实测(真实 Chromium + 真实组件 + 真实转录数据,123 个消息组,绘制后采样):
打开会话收敛 偏离底部 0px
静止 偏离底部 0px
正文流式(400字符/秒) 偏离底部 0px
thinking 流式 偏离底部 0px
展开/收起思考块 单次单调位移,0 次方向翻转,偏离底部 0px

聊天区在流式输出和滚动时会上下抖动,列表底部还会出现滚不到内容的空白。
根因有四个,都是"有多个写入者同时改滚动位置"或"在测量对象上做高度动画":

1. 虚拟列表行上的 transform 入场动画
   行是 motion.div,带 initial={{y:8}},外面套 AnimatePresence 的 exit。
   行每次进出虚拟窗口都要从 +8px 滑入、退出时还要留在 DOM 里,
   于是整列持续上下抖。另外 MessageBubble 的 scale:0.995→1 会被
   getBoundingClientRect 量进高度(自定义的 measureElement 用了它),
   导致每行先记一个偏小的高度、动画结束后再修正一次。
   改为纯 div,不再覆盖 measureElement —— 库默认实现会用 ResizeObserver 的
   borderBoxSize,不受 transform 影响。顺带删掉行组件里自挂的 ResizeObserver:
   把元素交给虚拟列表的 measureElement 时它内部已经建了一个,原来是每行测两遍。

2. 浏览器的 scroll anchoring 在背后改 scrollTop
   贴底时上方一个思考块收起(高度少几百像素),浏览器为保持锚点元素的视觉位置
   会自行把 scrollTop 拉走几百像素,贴底逻辑再拉回来,一缩一拉就是抖动。
   实测时间线:内容高度没变而 scrollTop 单独跳了 -956px,下一帧内容才缩 959px。
   给滚动容器加 overflow-anchor: none,位置由 useSmartAutoScroll 独家管理。

3. 虚拟列表自己也在补偿滚动位置,与贴底互相拉锯
   3.13 的 resizeItem 在行高变化时会补偿 scrollTop。流式输出的最后一行往往比
   视口还高,它的 start 一直小于 scrollTop,于是每测量一次就补偿一次。
   接上 shouldAdjustScrollPositionOnItemSizeChange:贴底时返回 false
   (位置由 hook 独家负责),用户翻历史时返回 true(走默认逻辑,否则上方行一变高
   用户正在看的内容就会被顶走)。注意这是 Virtualizer 的实例属性,不是构造选项。

4. 行内折叠块的高度动画
   ThinkingBlock 的 max-h 过渡、SubagentMessageGroup 的 animate={{height:'auto'}},
   动画的正是虚拟列表正在测量的那个元素:连续多帧改行高,每帧都要重测并重排
   后续所有行。改为一次到位,只留一次高度变化(展开/收起的时机与逻辑不变)。

另外重写了 useSmartAutoScroll。原实现有 5 个 useEffect 抢着写 scrollTop
(含流式期间常驻的 100ms rAF 循环、一次性的 8 次 setInterval、两个内容哈希触发的
延迟滚动),混用 behavior:'smooth' 和 'auto',每个 chunk 都在打断上一个平滑动画;
每次渲染还要对最后一条消息做一次 JSON.stringify 求长度。
现在收敛为单一数据流:ResizeObserver 观察内容真实高度 → 瞬时贴底。

其中"用户是否离开底部"改为只认真实输入事件(wheel / touch / 滚动条拖拽 / 翻页键)。
不能用距底部的距离判断:初始加载时虚拟列表逐行把估计高度换成实测高度,rail 每帧
能变几百像素;流式输出时最后一行持续长高。这两种情况下距离每帧都会超出容差,
拿它当依据会在第一次贴底之后立刻把自己关掉、之后再也不跟随输出。

同时把 rail 高度改为 GUTTER_TOP + getTotalSize() + GUTTER_BOTTOM,让 scrollHeight
与虚拟列表的总高度处于同一坐标系(原来是滚动容器 padding 在 getTotalSize() 之外,
绝对定位的行又是相对 rail 的 padding box 定位,两套坐标对不上,底部就有一段
滚不到内容的假空白)。estimateSize 也不再按消息类型猜高度——那种猜法既不准,
又要在每次布局时遍历每组的每条消息。

实测(真实 Chromium + 真实组件 + 真实转录数据,123 个消息组,绘制后采样):
  打开会话收敛      偏离底部 0px
  静止             偏离底部 0px
  正文流式(400字符/秒) 偏离底部 0px
  thinking 流式      偏离底部 0px
  展开/收起思考块     单次单调位移,0 次方向翻转,偏离底部 0px

Co-Authored-By: Claude <noreply@anthropic.com>
@ayuanjc ayuanjc closed this by deleting the head repository Oct 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant