@sentry-tools/blank-screen

白屏检测工具，用于自动检测网页中白屏和骨架屏长时间显示问题。

功能特性

1. 白屏检测（Fatal）

检测页面是否出现白屏问题。当检测到指定元素（默认 body）在超过配置的超时时间后仍然为空时，会触发错误回调。

2. 骨架屏检测（Skeleton）

检测骨架屏是否长时间显示。当检测到骨架屏元素（如 [class*=skeleton]、[class*=loading] 等）在超过配置的超时时间后仍然可见时，会触发错误回调。

3. 检测时机

• 页面加载时（OnLoad）：在 DOM 内容加载完成后自动检测
• 路由导航时（OnNavigate）：监听 pushState、replaceState 和 popstate 事件，在路由切换时自动检测。

4. 检测方法

像素分析

使用 WebGL 进行像素分析，通过对比像素颜色差异来判断元素是否为空。支持在 Web Worker 中异步执行，避免阻塞主线程。

子节点检测

使用米字形采样方法，在元素的多个关键位置检测是否存在有效的子节点。

可见性检测

检查元素的 CSS 属性（display、visibility、opacity、zIndex）和尺寸，确保元素真正可见。

使用场景

• 监控页面加载异常：及时发现页面加载失败导致的白屏问题。
• 监控路由切换异常：检测SPA应用路由切换时的渲染问题。
• 监控骨架屏异常：发现骨架屏长时间显示的问题，可能是接口请求失败或渲染逻辑错误。
• 性能监控：结合Sentry等监控工具，收集白屏相关的错误信息。

配置选项

interface BlankScreenOptions {
  // 白屏检测延时（毫秒），默认 5000
  checkTimeout?: number;
  // 白屏检测间隔（毫秒），默认 1000
  checkInterval?: number;
  // 白屏元素选择器，默认 ['body']
  blankScreenSelectors?: string[];
  // 骨架元素选择器，默认 ['[class*=skeleton]', '[class*=loading]', '[class*=spinning]']
  skeletonSelectors?: string[];
  // 错误回调
  onError?: (info: {
    type: BlankScreenType; // 'fatal' | 'skeleton'
    timing: BlankScreenTiming; // 'onLoad' | 'onNavigate' | 'onError'
    startTime: number; // 开始检测时间
    endTime: number; // 检测到错误时间
  }) => void;
}

跳过检测

如果某些元素需要跳过白屏检测，可以在元素上添加 data-blank-screen-ignore 属性：

• data-blank-screen-ignore="fatal"：跳过视图崩溃检测。
• data-blank-screen-ignore="skeleton"：跳过骨架遮罩检测。
• data-blank-screen-ignore="all"：跳过全部检测。

技术实现

• 使用 requestIdleCallback 在浏览器空闲时执行检测，避免影响页面性能。
• 使用WebWorker进行像素分析，避免阻塞主线程。
• 使用WebGL进行高效的像素颜色对比计算。
• 支持动态查找元素，对于延迟渲染的元素会自动重试。

注意事项

• 元素尺寸小于200x200像素时不会进行像素检测。
• 需要浏览器支持WebWorker和WebGL。
• 像素分析采样点数量默认为10000（100x100）。