HTML中如何使用Page Visibility API检测页面可见性-html教程-PHP中文网

document.visibilitystate 是唯一可靠的状态判断依据，其有效值仅 "visible" 和 "hidden"，需结合 visibilitychange 事件监听、初始状态检查及跨平台容错策略使用。

html中如何使用page visibility api检测页面可见性

document.visibilityState 是唯一可靠的状态判断依据

直接读 document.visibilityState 只能拿到当前快照，不能替代事件监听。它的值在现代浏览器中实际只有两个有效取值："visible" 和 "hidden"；"prerender" 和 "unloaded" 已被 Chrome 56+、Firefox 等主流引擎废弃，代码里无需处理。

常见误判场景包括：Chrome 标签页休眠、iOS Safari 锁屏后不触发事件、Electron 或某些安卓 WebView 中长期卡在 "visible"——这些都不是 API 失效，而是浏览器主动限制或机制差异。

首次加载时不会触发 visibilitychange，必须手动检查初始状态：if (document.visibilityState === 'hidden') { /* 做初始化隐藏逻辑 */ }
不要用 document.hidden 做核心判断，它只是布尔值，丢失状态细节，且已被标准标记为 legacy
SSR 渲染环境（如 Next.js、Nuxt）中 document 为 undefined，需加运行时保护：if (typeof document !== 'undefined')

必须用 visibilitychange 事件监听切换，不能轮询

visibilitychange 是唯一标准事件，绑定在 document 上，不冒泡、不可取消。它只在可见性真正变化时触发，比如切标签、最小化窗口、锁屏、系统多任务界面唤出等。

轮询 document.visibilityState 不仅浪费 CPU，还无法捕获瞬时切换（例如快速切回又切走），更会错过 iOS Safari 的部分锁屏场景。

html-ppt-to-pdf

将使用 `

` 约定的 HTML 幻灯片转换为高保真、矢量文本 PDF（使用 Playwright + Chromium 原生 PDF 功能）。

下载

监听必须在 DOM 加载完成后注册，避免放在 DOMContentLoaded 之前执行
若使用模块打包（如 Vite/webpack），确保监听逻辑不在异步 import 回调里延迟执行，否则可能漏掉首次切换
在 iframe 内监听，只能反映该 iframe 自身的可见性，无法感知父页面状态
回调内避免耗时操作（如 fetch、复杂计算），防止阻塞主线程影响页面响应

iOS Safari 和部分 WebView 下的兼容性补救

iOS Safari 对 visibilitychange 触发极其保守：App 切后台、锁屏、甚至双击 Home 键唤出多任务界面，都可能完全不发事件。这不是 bug，是 WebKit 的系统级限制。

纯前端无法绕过，只能交叉验证 + 容错兜底：

配合 document.hasFocus()：页面失焦但 visibilityState 仍为 "visible" 时，可能是 Safari 的“伪前台”
监听 pagehide 和 pageshow：虽然也存在延迟（iOS 上 pagehide 可能晚数秒），但比 visibilitychange 更稳定
强依赖场景（如答题倒计时、直播心跳）必须服务端同步：以最后一次有效心跳时间 + 客户端本地偏差作为最终判断依据
PWA 中 Service Worker 可能拦截生命周期，建议在 visibilitychange 回调后加 setTimeout(() => { /* 再 check 一次 visibilityState */ }, 100) 容错