phantom-ui 性能剖析:1000 个 DOM 元素 31ms 测完的骨架屏测量流水线与 Observer 自动重测机制

原创2026-10-26 23:14:121,657 阅读

phantom-ui 性能剖析:1000 个 DOM 元素 31ms 测完的骨架屏测量流水线与 Observer 自动重测机制

phantom-ui 是一个结构感知(Structure-aware)的骨架屏 skeleton loader,只需一个 Web Component 就能在任意框架中,基于真实 DOM 自动生成精确对齐的 shimmer 占位骨架屏。这篇文章剖析它的核心性能:DOM 测量流水线为什么能在 31ms 内测完 1000 个元素,以及 ResizeObserver + MutationObserver 驱动的自动重测机制如何让骨架屏在布局变化时始终保持同步。

phantom-ui 结构感知骨架屏 skeleton loader 效果展示

先给结论:31ms 的骨架屏测量性能数据

骨架屏库的性能瓶颈通常就在"测量"这一步:要把真实组件的每个叶子元素位置、尺寸、圆角都量出来,再画出遮罩块。phantom-ui 在 Chrome 中的基准测试结果如下:

DOM 元素数 叶子节点数 测量耗时
100 334 ~20ms
500 1,667 ~25ms
1,000 3,334 ~31ms

⚡ 1,000 个元素、3,334 个叶子节点的完整"测量 → 渲染"周期,能在单个动画帧(约 16.7ms 的渲染预算之外还有富余的帧预算)内完成,无需防抖、无需虚拟列表。对真实页面来说,1,000 个元素已经远超任何常规骨架屏的规模。

测量流水线四步拆解:从叶子遍历到遮罩渲染

整套流程的源码集中在 src/dom-measurement.ts 和 src/phantom-ui.ts,可以拆成四个阶段。

第 1 步:让内容"隐形"但保留布局

loading 置为 true 后,真实内容仍以正常方式渲染在 DOM 里,只是通过 CSS 变成不可见:

  • 文字使用 color: transparent,布局不变,量出来的骨架形状和真实内容完全一致;
  • img、svg、video、canvas 等媒体元素 opacity: 0;
  • 容器(卡片、区块)的背景和边框保留可见,骨架屏会呈现自然的"卡片轮廓";
  • 无法用 CSS 选择器命中的 mask-image 图标,则在运行时检测并打标记隐藏,相关逻辑在 src/content-visibility.ts。

第 2 步:递归遍历 DOM,识别"叶子节点"

核心是 extractElementInfo()(src/dom-measurement.ts#L117-L192)里的一次递归遍历。一个元素被判定为"叶子"只有两种情况:

  1. 命中固定标签集合 ALWAYS_LEAF_TAGS:img、svg、video、canvas、iframe、input、textarea、button、hr(src/dom-measurement.ts#L39-L49);
  2. 元素本身没有子元素(只有文本节点),见 isLeafElement()(src/dom-measurement.ts#L53-L65)。

容器型元素(div、section、ul 等)不会被捕获,而是继续递归深入。遍历中还会跳过两个快捷出口:

  • 宽高为 0 的元素直接剪枝(除非用 data-shimmer-width / data-shimmer-height 强制覆写);
  • 带 data-shimmer-ignore 的元素连同整棵子树跳过。

第 3 步:测量位置、尺寸与圆角

每个叶子元素调用一次 getBoundingClientRect(),坐标换算为相对宿主元素的位置,圆角从 getComputedStyle() 中读取。有一个值得注意的细节:

表格单元格 td / th 会被拉伸到整列宽度,如果直接量盒子,两个字的内容也会画出一根通栏长条。所以 phantom-ui 会临时插入一个绝对定位的 <span> 去测量真实文本宽度,测完立即移除,见 measureTextWidth()(src/dom-measurement.ts#L92-L101)。

另外,extractContainerInfo()(src/dom-measurement.ts#L194-L224)只把"有背景 / 边框 / 阴影"的容器记录下来,用于在骨架屏上保留卡片轮廓,透明容器直接忽略。

第 4 步:一次性渲染 shimmer 遮罩

测量结果交给 renderBlocks()(src/block-renderer.ts#L18-L49),按每个块的 {x, y, width, height, border-radius} 生成绝对定位的 div,CSS 动画在块上扫过渐变。整个遮罩由 Lit 一次 render() 提交,浏览器合成层只负责后续的动画,主线程几乎零开销。

列表场景还有一个纯内存的加速:replicateRows()(src/dom-measurement.ts#L231-L255)只测量一行模板,然后按 count / count-gap 在内存里做 Y 轴偏移复制,避免真实渲染 N 行再量 N 行。

31ms 的关键:requestAnimationFrame 天然节流

性能好的原因不只是测量本身快,还有调度方式。所有测量都走 _scheduleMeasure()(src/phantom-ui.ts#L320-L328):

  • 用一个 _measureScheduled 标志位去重:同一帧内任何多次触发(无论来自哪个 Observer)都只登记一次;
  • 真正的 _measure() 在 requestAnimationFrame 回调中执行,保证读到的是浏览器布局稳定后的坐标,且每帧最多测一次;
  • 测量期间 MutationObserver 会先 disconnect(),测完再 observe()(src/phantom-ui.ts#L343-L394),避免测量自身写入的属性标记触发新的重测,形成"测量 → 写标记 → 再测量"的死循环。

这套"帧内合并 + 每帧一次"的设计,等价于一个零成本的防抖,所以 1000 个元素也能稳定落在 31ms 量级——耗时几乎全部来自叶子节点的 getBoundingClientRect 调用本身,而它是浏览器里读布局最快的同步 API 之一。

Observer 自动重测机制:骨架屏如何"永远对齐"

骨架屏最大的体验风险是"错位":图片加载完撑开了布局、窗口缩放、框架异步注入了内容,占位块就和真实元素对不上了。phantom-ui 在 _setupObservers()(src/phantom-ui.ts#L397-L412)里挂载了三路监听:

触发源 监听方式 覆盖场景
ResizeObserver 观察宿主元素(src/dom-measurement.ts#L257-L272) 窗口缩放、栅格变化、容器尺寸改变
MutationObserver 观察 childList + subtree + attributes(src/phantom-ui.ts#L34-L38) 框架注入 / 移除节点、样式属性变化
load 事件 捕获阶段监听宿主上的 load(src/phantom-ui.ts#L410-L411) 图片、视频异步加载完成后撑开布局

三路事件全部汇入同一个 _scheduleMeasure(),由 rAF 合并到下一帧统一执行。

重测不是无脑触发:Shadow DOM 的属性白名单

pierce-shadow 模式下会深入第三方设计系统的 open shadow root 测量,但 MutationObserver 无法自动穿越 Shadow DOM 边界,所以每个被穿透的 root 都会被显式注册观察(src/phantom-ui.ts#L391-L393)。

这里有个很细的性能优化:被穿透的组件在 hover、focus、过渡时会频繁改 class、aria-*、data-state,如果全量监听属性,每次悬停都会调度一次完整测量。因此 pierce 模式使用带 attributeFilter 的白名单配置 PIERCED_MUTATION_OPTIONS(src/phantom-ui.ts#L46-L58),只监听真正影响测量结果的属性:

data-shimmer-width / data-shimmer-height / data-shimmer-ignore /
data-shimmer-no-children / style / hidden

交互态的抖动被彻底过滤,重测只发生在布局真正可能变化的时刻。

loading 结束:观察器完整拆除

loading 移除后,_teardownObservers()(src/phantom-ui.ts#L414-L427)会一次性断开两个 Observer 并移除 load 监听,遮罩随 reveal 淡出后销毁。元素重新插回 DOM 时又会在 connectedCallback 里恢复整套监听——观察器的生命周期和 loading 状态严格绑定,不留后台开销。

用 debug 属性亲眼验证测量流水线

怀疑某个组件的骨架块位置不对?给 <phantom-ui> 加上 debug 属性,每个测量出的块都会画出描边和序号,一眼看出 phantom-ui 是如何解读你的 DOM 的:

<phantom-ui loading debug>
  <!-- 你的卡片内容 -->
</phantom-ui>

更多细节(如零尺寸元素、SVG 只取外框等边界行为)可参考官方文档 docs/src/content/docs/reference/how-it-works.md,以及各框架示例 examples/react-app、examples/vue-app。

总结:一条"单帧完成"的骨架屏性能路径 🏁

phantom-ui 把骨架屏测量做成了一个可预测的性能闭环:

  1. 剪枝优先:零尺寸节点和 data-shimmer-ignore 子树在遍历中提前退出,量得少才能测得快;
  2. 最便宜的测量 API:getBoundingClientRect + getComputedStyle,全部同步完成、无布局抖动等待;
  3. rAF 合帧:所有触发源(Resize / Mutation / load)合并到每帧一次测量,天然防抖;
  4. 属性白名单:Shadow DOM 场景下只监听影响测量的属性,交互抖动零成本。

最终结果就是开头那张表:1,000 个元素、3,334 个叶子,31ms 测完——骨架屏的性能开销,小到几乎可以忽略。

phantom-ui 项目吉祥物 houston

登录后查看全文
phantom-ui