解决懒加载白屏问题:vue-recyclerview的Tombstone骨架屏与淡入动画完整解析
解决懒加载白屏问题:vue-recyclerview的Tombstone骨架屏与淡入动画完整解析
vue-recyclerview 是一款面向 Vue 2 的虚拟滚动长列表组件,它对抗懒加载白屏的核心武器就是 Tombstone 骨架屏占位 + 淡入动画:先用"假骨架"撑住列表高度,数据到位后再在原位置交叉淡入真实内容,从根源上消灭白屏与布局跳动。本文完整解析这套机制的原理、关键配置与调优技巧,帮你把长列表做到丝滑加载。
一、懒加载白屏是怎么来的?
vue-recyclerview 的原理是 DOM 回收:只渲染视口附近的一批 item,滚出屏幕的立即销毁,滚回来时重新生成;再配合 fetch 函数分批拉取数据,列表可以做到近乎无限长。核心滚动与布局逻辑位于 src/infinite.js。
这带来一个副作用:新位置的数据还没返回时,这里画什么?
| 方案 | 结果 |
|---|---|
| 什么都不画 | 白屏,滚动条高度瞬间缩短 |
| 画空白 item | 图片加载时再次闪烁、布局跳动 |
| 画 Tombstone 骨架屏 ✅ | 高度稳定、有"内容即将出现"的预期,体验最佳 |
所以官方方案是:数据未到位的位置,先渲染一个与真实 item 尺寸一致的 Tombstone 占位节点。它负责两件事:
- 撑起列表总高度,让用户感知"后面还有内容";
- 为
prerender/remain预渲染逻辑提供可计算尺寸的锚点。
如果你没有传
tombstone组件,vue-recyclerview 会回退到内置的一个 100px 高纯色块(见 src/recyclerview.js#L21-L33)——用户看到的就是整片空白,这正是"白屏尴尬"的常见来源之一。
二、Tombstone 骨架屏:一个"假 item"的正确写法
2.1 组件接入方式
在模板中通过 :tombstone 属性传入骨架屏组件即可,官方示例见 examples/component/App.vue:
<RecyclerView
:prerender="30"
:fetch="MiFetch"
:item="MiItem"
:tombstone="MiTomstone"
></RecyclerView>
组件内部由 ContentSource 统一创建骨架实例,入口在 src/content-source.js#L95-L101 的 createTombstone 方法:
createTombstone (el) {
const vm = new this.Vue({
el: el,
render: h => h(this.TombstoneRender)
})
return vm.$el
}
2.2 骨架屏怎么写才像"骨架"
官方示例 examples/component/Tombstone.vue 是标准模板:外层结构与真实 item 完全一致(图片区 + 标题区 + 价格区),内容替换成灰色占位条:
.mi-item.tombstone p {
width: 100%;
height: 0.5em;
background-color: #ccc;
margin: 0.5em 0;
}
新手避坑清单 👇
- 骨架屏的宽高结构必须与真实 item 对齐,否则淡入瞬间布局跳动;
- 占位条用
#ccc这类浅灰,模拟"内容即将出现"的预期; - 骨架节点会被打上
tombstoneclass(tombstone_class配置项),可据此写 CSS; - 骨架与真实 item 使用同一套外层 class(示例中都是
mi-item),保证结构无缝衔接。
三、淡入动画:骨架与真实 item 的"交叉替换"
这是全文的重点。vue-recyclerview 不是"删掉骨架再插入 item",而是让两者短暂重叠,通过 CSS 过渡完成无缝交接。整个过程在 src/infinite.js 中分四步:
第 1 步:登记需要替换的位置(renderItems,src/infinite.js#L397-L464)
fetch 返回数据后,组件发现某位置"已有 tombstone 节点、且 data 已到位",就把旧节点登记进 tombstoneAnimations,并设置 zIndex = 1 使其叠放在骨架上方。
第 2 步:锁定骨架位置(tombstoneLayout)
骨架节点被设置 transform(translate3d + scale)与 transition: transform 200ms,防止它跟随后面的布局变化。
第 3 步:真实 item 淡入(itemLayout,src/infinite.js#L355-L390)
this.setStyle(anim[0], 'transition',
'transform ' + this.ANIMATION_DURATION_MS + 'ms, opacity ' + this.ANIMATION_DURATION_MS + 'ms')
this.setStyle(anim[0], 'transform', 'translate3d(' + x + 'px,' + y + 'px, 0) scale(...)')
anim[0].style.opacity = 0
新 item 从 opacity: 0 过渡到 1,同时尺寸从骨架比例 scale 到真实比例——视觉上就是骨架"融化"成了真实内容。
第 4 步:延迟回收骨架(tombstoneAnimation)
if (this.ANIMATION_DURATION_MS) {
setTimeout(() => {
this.tombstoneAnimation(tombstoneAnimations)
}, this.ANIMATION_DURATION_MS)
}
动画时长到期后,旧骨架被加上 invisible class 并压入回收池。如果将 animation_duration_ms 设为 0,则跳过交叉动画直接替换——适合对性能极致敏感的场景。
四、骨架节点回收池:滚动为什么不卡顿?
每次数据到达都新建再销毁 Vue 实例,开销巨大。vue-recyclerview 用两个池子化解了它:
tombstones_骨架回收池:getTombstone()优先pop()一个旧骨架复用,并重置其opacity、transform、transition(见 src/infinite.js#L208-L218);没有可用节点时才走createTombstone新建;unusedNodesDOM 节点池:已销毁的 item 节点缓存起来,下次渲染直接复用。
再配合 options 里的 cacheVM(实例缓存上限)与 reuseVM(Vue 实例复用队列,见 src/content-source.js),长列表快速回滚也能保持流畅。
五、关键配置清单:一分钟调优动画参数
以下参数默认值定义在 src/recyclerview.js#L35-L50,也可通过 options prop 整体覆盖(完整说明见 README.md 的 Props Options 一节):
| 参数 | 默认值 | 作用 |
|---|---|---|
animation_duration_ms |
200 | 骨架→item 淡入时长(ms),设 0 关闭动画 |
tombstone_class |
tombstone |
骨架节点 class,便于自定义样式 |
invisible_class |
invisible |
回收隐藏骨架用的 class |
prerender |
20 | 滚动方向外额外实例化的 item 数 |
remain |
10 | 反向保留的 item 数,回滚时更快 |
fetch |
— | 数据拉取函数,返回 { list, count } 的 Promise |
fetch 标准写法(参考 examples/component/mi-fetch.js):
function fetch (limit, skip) {
return Promise.resolve({
list: list, // Array,本批数据
count: count // Number,数据总条数
})
}
调优建议 ⚡
- 网络较慢时把
prerender调大(如 30),让骨架更早出现、数据更早就位; - 追求丝滑感可将
animation_duration_ms调到 200~400; - 瀑布流布局(
waterflow: true)下同样生效,多列位置计算见 src/infinite.js 的posList逻辑。
六、一次完整的懒加载流程复盘
把上面所有环节串起来,滚动到底部时依次发生:
onScroll_检测到滚近尾部 →fill()计算需渲染的范围;renderItems()为缺口位置创建 Tombstone 骨架屏,撑住滚动轨道;maybeRequestContent()发现缺口 → 调用你的fetch(limit, skip);- Promise 返回 →
addContent()写入 data → 再次attachContent(); - 命中
tombstoneAnimations→ 执行 200ms 交叉淡入动画; - 动画结束 → 骨架节点打
invisibleclass 进入回收池,等待下次复用。
结语
Tombstone 骨架屏 + 淡入动画是 vue-recyclerview 对抗懒加载白屏的核心武器:骨架占位解决"高度塌陷",交叉淡入解决"内容突现",回收池解决"性能开销"。只要按官方示例对齐骨架与 item 结构,再微调 animation_duration_ms 与 prerender 两个参数,就能让你的 Vue 长列表从"白屏尴尬"进化到"丝滑加载"。
相关源码速查 📚
- 滚动与动画核心:src/infinite.js
- 组件入口与默认配置:src/recyclerview.js
- 骨架/实例创建与回收:src/content-source.js
- 完整示例(App / Item / Tombstone / fetch):examples/component/
- 内置样式:src/recyclerview.css


