webperf-interaction

WebPerf：交互与动画

用于在 Chrome DevTools 中测量网页性能的 JavaScript 代码片段。

运行脚本

1. 使用 mcp__chrome-devtools__evaluate_script 运行脚本，并读取其返回的对象。脚本不会输出到控制台，因此返回的对象就是结果：script、status 和指标数据（value、rating、details、items、issues），具体说明见 references/schema.md。
2. 当 status 为 "tracking" 时，脚本会持续观察页面。完成交互后，使用另一次 mcp__chrome-devtools__evaluate_script 调用 getDataFn 中指定的函数（例如 getINP()），并读取其返回的对象。
3. 当 status 为 "error" 或 "unsupported" 时，请查看 error：页面可能尚未加载，或者浏览器不支持该 API。

如果没有 Chrome DevTools MCP，请使用 webperf-snippets CLI 运行同一代码片段。它会在无头 Chromium 中加载页面，并输出相同的结果对象：npx webperf-snippets <url> --snippet <Name> --json，其中 <Name> 是不带 .js 的脚本名称。它需要 Playwright 和 Chromium（先运行 npm install --save-dev webperf-snippets playwright，然后运行 npx playwright install chromium）；跟踪类代码片段还需要通过 --interact-script <file> 驱动交互。

脚本

• scripts/DOM-Size-and-Depth.js — DOM 大小和深度
• scripts/Forced-Synchronous-Layout.js — 强制同步布局检测器
• scripts/Input-Latency-Breakdown.js — 输入延迟细分
• scripts/Interactions.js — 交互
• scripts/Layout-Shift-Loading-and-Interaction.js — 布局偏移跟踪
• scripts/Long-Animation-Frames-Helpers.js — LoAF 辅助工具
• scripts/Long-Animation-Frames-Script-Attribution.js — 长动画帧脚本归因
• scripts/Long-Animation-Frames.js — 长动画帧（LoAF）
• scripts/LongTask.js — 长任务
• scripts/Scroll-Performance.js — 滚动性能分析

常见工作流

完整的交互性能审计

当用户要求分析交互或“审计响应能力”时：

1. Interactions.js — 列出所有用户交互及其耗时
2. Input-Latency-Breakdown.js — 细分交互各阶段
3. Long-Animation-Frames.js — 检测造成阻塞的动画帧
4. LongTask.js — 找出阻塞主线程的长任务
5. Scroll-Performance.js — 测量滚动流畅度

深入分析 INP

当 INP 较慢（>200ms），或用户要求“调试 INP”或“分析缓慢交互”时：

1. Interactions.js — 找出哪些交互较慢
2. Input-Latency-Breakdown.js — 细分为输入延迟、处理时间和呈现延迟
3. Long-Animation-Frames.js — 找出阻塞交互的 >50ms 动画帧
4. Long-Animation-Frames-Script-Attribution.js — 找出导致阻塞的脚本
5. Long-Animation-Frames-Helpers.js — 获取详细的计时和归因辅助信息

调查滚动卡顿

当用户反馈“滚动卡顿”或“滚动不流畅”或“滚动性能问题”时：

1. Scroll-Performance.js — 测量滚动流畅度和丢帧情况
2. Long-Animation-Frames.js — 检测造成卡顿的帧（>50ms）
3. Layout-Shift-Loading-and-Interaction.js — 检查滚动期间是否发生布局偏移
4. Long-Animation-Frames-Script-Attribution.js — 找出滚动期间运行的脚本

主线程阻塞分析

当页面感觉无响应，或用户询问“页面为什么卡住了”时：

1. LongTask.js — 列出所有阻塞主线程的 >50ms 任务
2. Long-Animation-Frames.js — 与动画帧计时进行关联
3. Long-Animation-Frames-Script-Attribution.js — 将阻塞归因到具体脚本
4. 与 webperf-loading 技能交叉参照：
   • JS-Execution-Time-Breakdown.js（脚本解析/执行时间）
   • First-And-Third-Party-Script-Info.js（找出阻塞页面的第三方脚本）

交互期间的布局偏移

当用户反馈“点击时页面元素会移动”或出现交互期间的 CLS 问题时：

1. Layout-Shift-Loading-and-Interaction.js —— 区分加载期间和交互期间的偏移
2. Interactions.js —— 将偏移与具体交互关联起来
3. CLS.js（来自 Core Web Vitals 技能）—— 测量总 CLS
4. 与 webperf-media 技能交叉参考：
   • Image-Element-Audit.js（检查是否有未设置尺寸、会导致偏移的图片）

动画性能分析

当动画显得迟缓，或用户要求“调试动画性能”时：

1. Long-Animation-Frames.js —— 找出渲染耗时过长的帧
2. Long-Animation-Frames-Helpers.js —— 详细分析帧时间
3. Long-Animation-Frames-Script-Attribution.js —— 找出导致帧延迟的脚本
4. Scroll-Performance.js —— 如果涉及滚动动画
5. DOM-Size-and-Depth.js —— 检查庞大或层级过深的 DOM 是否导致每次样式和布局计算都很耗时

第三方脚本对交互的影响

当交互缓慢且怀疑是第三方脚本导致时：

1. Long-Animation-Frames-Script-Attribution.js —— 找出长帧中的第三方脚本
2. LongTask.js —— 测量长任务发生频率
3. 与 webperf-loading 技能交叉参考：
   • First-And-Third-Party-Script-Info.js（列出所有第三方脚本）
   • First-And-Third-Party-Script-Timings.js（测量脚本加载的影响）
   • Script-Loading.js（检查是否存在阻塞脚本）

决策树

根据结果使用此决策树自动运行后续代码片段：

运行 Interactions.js 后

• 如果任何交互耗时 > 200ms → 对慢速交互运行 Input-Latency-Breakdown.js；同时运行 webperf-core-web-vitals:INP.js 测量官方 INP
• 如果有许多交互耗时 > 200ms → 主线程拥塞，运行：
  1. Long-Animation-Frames.js（阻塞帧）
  2. LongTask.js（长任务）
  3. Long-Animation-Frames-Script-Attribution.js（问题脚本）
• 如果特定交互类型较慢（例如，点击与键盘操作相比） → 聚焦于该交互类型
• 如果交互发生在页面加载期间 → 与 webperf-loading:JS-Execution-Time-Breakdown.js 交叉核对

运行 Input-Latency-Breakdown.js 后

• 如果输入延迟 > 50ms → 主线程繁忙，运行：
  1. Long-Animation-Frames.js（检查阻塞原因）
  2. LongTask.js（交互前的长任务）
• 如果处理时间 > 100ms → 事件处理程序过重，运行：
  1. Long-Animation-Frames-Script-Attribution.js（检查涉及的脚本）
  2. webperf-loading:First-And-Third-Party-Script-Info.js（检查第三方脚本是否参与）
• 如果呈现延迟 > 50ms → 渲染瓶颈，运行：
  1. Long-Animation-Frames.js（帧渲染时间）
  2. Layout-Shift-Loading-and-Interaction.js（检查布局计算）

运行 Long-Animation-Frames.js 后

• 如果许多帧耗时 > 50ms → 运行 Long-Animation-Frames-Script-Attribution.js 查明原因
• 如果帧耗时 > 100ms → 存在严重阻塞，运行：
  1. Long-Animation-Frames-Script-Attribution.js（详细归因）
  2. LongTask.js（相关长任务）
  3. webperf-loading:JS-Execution-Time-Breakdown.js（脚本执行开销）
• 如果帧出现在滚动期间 → 运行 Scroll-Performance.js 测量影响
• 如果帧出现在页面加载期间 → 与 webperf-loading:Event-Processing-Time.js 交叉核对

Long-Animation-Frames-Script-Attribution.js 之后

• 如果第三方脚本导致长帧 → 运行：
  1. webperf-loading:First-And-Third-Party-Script-Info.js（列出所有第三方脚本）
  2. webperf-loading:Script-Loading.js（检查加载策略）
  3. 建议延迟加载或移除有问题的脚本
• 如果第一方脚本导致长帧 → 建议：
  • 代码拆分
  • 对事件处理程序进行防抖/节流
  • 使用 Web Workers 进行繁重计算
• 如果检测到强制回流/布局 → 分析 DOM 操作模式
• 如果耗时集中在样式重计算或布局 → 运行 DOM-Size-and-Depth.js 检查树的大小

LongTask.js 之后

• 如果长任务较多（>5） → 主线程拥堵，运行：
  1. Long-Animation-Frames-Script-Attribution.js（详细归因）
  2. webperf-loading:JS-Execution-Time-Breakdown.js（脚本执行分析）
  3. webperf-loading:First-And-Third-Party-Script-Info.js（识别耗时较长的脚本）
• 如果长任务 > 500ms → 存在严重阻塞，请调查：
  • 同步第三方脚本
  • 未使用 Web Workers 的繁重计算
  • 过多的 DOM 操作
• 如果长任务与交互相关 → 运行 Interactions.js 查看影响

DOM-Size-and-Depth.js 之后

• 如果元素总数 > 1400 → 建议对长列表进行虚拟化，并按需加载屏幕外内容
• 如果深度 > 32 → 建议扁平化组件添加的包装元素
• 如果单个父元素有 > 60 个子元素 → 建议对该容器进行分页或虚拟化
• 如果 DOM 未超出限制，但交互仍然缓慢 → 运行 Long-Animation-Frames-Script-Attribution.js 找出相关脚本

Scroll-Performance.js 之后

• 如果滚动 FPS < 30 → 存在严重卡顿，运行：
  1. Long-Animation-Frames.js（滚动期间阻塞帧的情况）
  2. Long-Animation-Frames-Script-Attribution.js（滚动期间运行的脚本）
  3. Layout-Shift-Loading-and-Interaction.js（滚动期间的布局工作）
• 如果滚动 FPS 为 30-50 → 卡顿明显，请调查：
  • 滚动事件处理程序
  • 被动事件监听器
  • CSS will-change 属性
• 如果滚动 FPS > 50 → 表现良好，但请检查滚动期间是否发生布局偏移

Layout-Shift-Loading-and-Interaction.js 之后

• 如果页面加载期间发生偏移 → 与 webperf-core-web-vitals:CLS.js 交叉比对
• 如果交互期间发生偏移 → 这会影响 INP 和 UX，请调查：
  1. 动态插入内容
  2. 未设置尺寸就加载的图片/广告
  3. 字体切换（运行 webperf-loading:Fonts-Preloaded-Loaded-and-used-above-the-fold.js）
• 如果滚动期间发生偏移 → 运行 Scroll-Performance.js 衡量影响

Long-Animation-Frames-Helpers.js 之后

这是一个实用代码片段，请使用结果来：

• 详细了解帧时序
• 精确识别脚本归因
• 衡量样式/布局/绘制阶段
• 不会自动执行后续操作，请根据数据决定下一步

性能预算阈值

使用以下阈值自动触发后续分析：

INP 阈值：

• 良好：≤ 200ms → 监控，无需采取措施
• 需要改进：200-500ms → 运行 Input-Latency-Breakdown.js
• 较差：> 500ms → 运行完整的 INP 调试工作流（5 个代码片段）

长动画帧：

• 警告：> 50ms → 运行 Long-Animation-Frames-Script-Attribution.js
• 严重：> 100ms → 运行完整的主线程阻塞工作流

长任务：

• 警告：> 50ms → 监控发生频率
• 严重：> 200ms 或每秒 >5 个任务 → 运行归因分析和脚本分析

滚动性能：

• 良好：≥ 50 FPS → 监控
• 需要改进：30-50 FPS → 运行 Long-Animation-Frames.js
• 较差：< 30 FPS → 运行完整的滚动卡顿工作流

交互频率：

• 如果每秒交互次数 >10 → 用户正在积极交互，应优先优化 INP
• 如果每 5 秒交互次数 <1 → 交互很少，应重点提升首次交互响应速度

多指标关联分析

当多个交互指标表现较差时：

• 如果同时检测到长任务和长动画帧 → 根因可能相同：

  1. 运行 Long-Animation-Frames-Script-Attribution.js
  2. 很可能是 JavaScript 执行负担过重
  3. 考虑拆分代码或使用 Web Workers

• 如果 INP 较慢且 CLS 较高 → 交互触发布局偏移：

  1. 运行 Layout-Shift-Loading-and-Interaction.js
  2. 将偏移时间与交互时间关联分析
  3. 检查是否动态插入了内容

• 如果同时出现滚动卡顿和长动画帧 → 滚动处理程序阻塞了主线程：

  1. 在滚动期间运行 Long-Animation-Frames-Script-Attribution.js
  2. 检查是否存在非被动滚动监听器
  3. 审查滚动触发的动画

参考资料

• references/snippets.md — 各脚本的说明和阈值
• references/schema.md — 用于解读脚本输出的返回值架构