稚一先说结论：这个问题在 HarmonyOS 6 的 ArkTS 里做信息流、聊天记录、日志列表时很容易遇到。列表本身的数据更新逻辑没变，但用户屏幕上看到的内容却不听话地“跳”了。尤其是做即时通讯场景，用户正在往上翻历史记录，加载完更早的消息后，当前正在看的那一条直接跑出屏幕，体验非常差。这篇内容我会从 List 的渲染机制讲起，给出三种实际可落地的处理方案，从一行配置到完整的位置恢复逻辑，最后附上我整理的问题排查表，方便你直接对着改。
1. 现象和根因：为什么在可视区域外插数据会“跳一下”
1.1 一个熟悉的场景：往上翻消息记录时被拉回原位
假设你在做一个聊天页面，消息按时间正序排，用户想看历史记录就向上滑动。当列表滚动到最顶部时，客户端去请求更早的 20 条消息，拿到之后执行了一个很自然的操作：
ts复制this.messages = olderMessages.concat(this.messages)
这条代码看起来没问题，数据源也确实变成了“更早的数据 + 原有数据”。但在真机上按下拉刷新那一瞬间，你会看到整个列表先猛跳一下，原本停在屏幕中间的一条消息，要么突然被顶到视口上方，要么干脆消失。我最早遇到这个问题时，第一反应是数据拼接错了，反复检查后发现数据没问题，是 List 组件自己在“矫正”滚动位置。
这个现象在 ArkUI 里非常典型：你不希望在视口顶部的数据发生任何偏移，但 List 的默认行为是把自己重新布局后的首条可见项固定到一个规则位置，而不是维持你肉眼看到的那个位置。
1.2 List 的懒加载机制：屏幕外面其实没有“内容”
很多从 Web 前端转过来的开发者，会把 ArkUI 的 List 和网页里的普通滚动容器画上等号。网页里一个 <div> 滚动区域，不管有没有滚动到，所有子节点都在 DOM 树里，重新计算布局时浏览器能算出完整高度。但 ArkUI 的 List 完全不同，它是典型的懒加载列表，只会渲染当前视口附近的一小部分节点，屏幕外的很多数据在节点树里根本不存在。
打个比方，List 就像一条传送带，你站在一个观察窗口前，传送带上肉眼可见的几件物品是真实存在的，窗口上方和下方的物品虽然也在传送带上，但你不需要看到它们，系统就没把它们搬过来。你在数据源头部塞入 20 条新消息，相当于在传送带的上游塞进去 20 件新物品。这时候传送带本身要重新调整，而 ArkUI 为了保证滚动位置语义不变，会尝试重新计算屏幕上第一条消息所在的索引位置。
问题就出在这个“重新计算”上。如果 List 完全没有预知到上方还有多少内容，它就无法产生一个合理的偏移量补偿，视觉上就表现为内容跳动，甚至直接回弹到顶部。
1.3 数据插入触发了什么：索引前移与布局重排
要理解得更透彻，你得知道 List 内部维护的偏移量，本质上是一个“内容坐标系”里的 y 坐标。每个 ListItem 都有自己占据的高度，从第一条数据开始累加，就能得到任意一条数据在滚动内容里的绝对位置。
当你在数据源头部插入 N 条数据后，原来所有数据的索引整体后移了 N 位。假如插入前用户正看着索引为 15 的消息，这条消息之前的高度累计是 H1，插入后这条消息之前多了 N 条数据，累计高度变成了 H1 + addedHeight。如果 List 的偏移量没有同步加上 addedHeight，布局器就认为当前滚动位置已经不再指向原来的那条消息了，于是它需要重新找一个“可见首项”。
大多数情况下，它会选择新的第一项作为起始位置，或者把当前内容整体向下推一截，肉眼看到的就是跳动。如果插入的数据量比较大，且列表内容高度超过了一屏，甚至可能出现一跳几百像素的情况。
1.4 为什么底部插入不跳，顶部插入就跳
顺便说个现象：如果你是在列表底部追加数据，也就是把新数据 concat 到数组末尾，几乎不会出现跳动。因为底部追加不影响已有数据项在索引上的位置，原来可见区域对应的第一条消息还是同一个索引，累计高度也没变，List 自然不需要调整任何偏移量。
只有当你往列表头部方向插入数据时，所有现存数据的索引都会发生平移，才需要额外的“位置保持”逻辑。这篇文章后面所有方案，核心都在解决同一个问题：让 List 在索引发生平移后，仍然把用户原本看到的那个锚点留在原地。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 第一招：给 List 加缓存，让可视区外先“垫”一段
2.1 cachedCount 能解决什么问题
如果你的需求只是偶尔在顶部插入少量数据，比如下拉刷新时插入两三条推荐内容，那可以先试试设置 cachedCount。这个属性在官方文档里的定义很朴素：设置列表中屏幕可视区外缓存多少个子组件。
很多开发者不理解这跟“插入数据保持位置”有什么关系，我举个例子你就懂了。List 是懒加载的，可视区外如果没有缓存，系统就不知道顶部到底有多少内容可以“垫着”。你往头部插入数据时，它相当于在一个完全空白的位置硬塞内容，只能通过整体重排来消化。
当你设置了 cachedCount 以后，可视区外已经预先创建了一批 ListItem 节点，List 对整体内容高度有更准确的感知。在顶部插入数据时，如果插入的条数在缓存容量覆盖范围内，系统能够利用这些预创建节点平滑完成布局，不需要把当前视口内容顶部顶开太远。
简单说，cachedCount 相当于给 List 装了一段“缓冲带”，让插入操作不再直接冲击可视区域。
2.2 设置多大合适：按插入批量和性能折中取值
在使用这段缓冲带时，最常被问到的问题就是：缓存数量设多少合适。我给不出一个万能数字，但可以给你两个参考原则。
第一，从功能角度看，cachedCount 最好能覆盖你单次在头部插入的数据量，或者至少覆盖一个分页的数据量。聊天记录场景一页通常拉取 20 条，那就设 30 到 50；日志流场景一页可能 50 条，就要设得更多。因为如果插入的数据量远大于缓冲容量，List 还是需要重建大量节点，依然可能出现明显跳动。
第二，从性能角度看，cachedCount 不是越