HTML5页面可见性API使用详解

本文深入讲解了HTML5 Page Visibility API的核心用法与实战要点，聚焦于通过document.visibilityState精准判断页面可见状态（“visible”或“hidden”），强调必须使用visibilitychange事件进行响应式监听而非轮询，并剖析了iframe嵌套、移动端锁屏、浏览器预加载等易被误判的边界场景；同时明确指出document.hidden已被废弃，提醒开发者避免将其用于新项目，并澄清该API与页面卸载事件的本质区别——它反映的是用户感知层面的前台/后台切换，是实现视频暂停、定时器节流、资源优化等用户体验优化功能的关键工具。

PageVisibilityAPI 的核心判断依据是 document.visibilityState

这个属性返回字符串值，只有四种可能："visible"、"hidden"、"prerender"、"unloaded"。现代浏览器基本只用前两个——"visible" 表示页面在前台且内容可被用户看到；"hidden" 表示页面被切换到后台、最小化、锁屏，或被其他窗口完全遮盖。注意："prerender" 在 Chrome 早期支持过，现已废弃；"unloaded" 从未被主流实现。

监听可见性变化必须用 visibilitychange 事件，不能轮询

直接读取 document.visibilityState 只能拿到当前快照，无法捕获切换瞬间。真实场景中（比如暂停视频、暂停心跳上报、节省资源）都需要响应式监听：

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    console.log('页面不可见，可暂停定时器');
  } else if (document.visibilityState === 'visible') {
    console.log('页面恢复可见，可恢复播放或重连');
  }
});

• 该事件不冒泡，也不可取消，绑定在 document 上即可
• 不要在 visibilitychange 回调里做耗时操作（如发起网络请求），避免阻塞主线程
• 首次加载时不会触发该事件，需手动检查初始状态：if (document.visibilityState === 'hidden') { ... }

document.hidden 是兼容写法，但已不推荐单独使用

这是旧版 API 提供的布尔值，等价于 document.visibilityState !== 'visible'。虽然目前所有支持 Page Visibility 的浏览器都同时支持它，但它丢失了状态细节（比如无法区分 prerender 和 hidden），且已被标准标记为 legacy。实际项目中建议统一用 visibilityState 判断，仅在需要兼容 IE10（仅支持 hidden）时才加降级逻辑：

const isVisible = document.visibilityState ? 
  document.visibilityState === 'visible' : 
  !document.hidden;

常见误判场景：iframe、标签页预加载、移动端锁屏

这些情况容易让人以为 API 失效，其实是预期行为：

• 页面嵌在 iframe 中时，父页面不可见不影响子页面的 visibilityState；但若整个浏览器窗口被遮盖，子页面仍会收到 hidden
• Chrome 的“预加载”标签页（新标签页预渲染）会让 visibilityState 初始为 "prerender"，随后变为 "visible"，但该行为已在新版中移除，不必再处理
• iOS Safari 在锁屏后可能延迟触发 visibilitychange（最长数秒），Android 各厂商 WebView 行为也不一致；不要依赖它做精确计时类逻辑

真正要注意的是：别把 visibilitychange 当作页面卸载信号——它和 beforeunload / pagehide 完全不同，页面切走又切回时，它会反复触发，而生命周期事件只在真正离开时发生一次。

本篇关于《HTML5页面可见性API使用详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！