如何检测浏览器标签页变为非活动状态

你有一个每十秒触发一次的轮询定时器、一个在后台播放的视频，或者一个不停运行的动画循环——它们都在为五分钟前就已切换到其他标签页的用户消耗资源。一旦你了解了应该调用哪个 API，解决这个问题就轻而易举。

正确的工具：Page Visibility API

旧的解决方案依赖于 window 的 focus 和 blur 事件——即 window.onfocus 和 window.onblur。它们检测的是浏览器窗口是否拥有键盘焦点，而不是标签页是否真的可见。在分屏模式或多窗口工作流中，一个标签页可能完全可见但没有焦点，反之亦然。它们在不同浏览器中对标签页切换的处理也表现得不一致。

Page Visibility API 妥善地解决了这个问题。它能准确告诉你页面是否对用户可见，与焦点状态无关。

两个属性可以告诉你当前状态：

• document.visibilityState —— 返回 "visible" 或 "hidden"
• document.hidden —— 标签页隐藏时返回 true，可见时返回 false

现代浏览器不再需要厂商前缀。该 API 已被广泛支持，覆盖 Chrome、Firefox、Safari 和 Edge 的桌面端及移动端。

监听 visibilitychange 事件

visibilitychange 事件 会在标签页变为隐藏或重新可见时在 document 上触发。以下是基本模式：

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    console.log("Tab is hidden — pause or reduce work");
  } else {
    console.log("Tab is visible — resume work");
  }
});

如果你需要字符串值而非布尔值，也可以直接读取 document.visibilityState。

实际应用场景

暂停和恢复轮询

与其在用户切换到其他标签页时仍发起 API 请求，不如暂停定时器，并在用户返回时恢复它：

let intervalId = null;

function startPolling() {
  if (intervalId !== null) return;
  intervalId = setInterval(fetchData, 10000);
}

function stopPolling() {
  clearInterval(intervalId);
  intervalId = null;
}

document.addEventListener("visibilitychange", () => {
  document.hidden ? stopPolling() : startPolling();
});

startPolling();

注意：浏览器会节流后台标签页中的 setInterval，而不是完全停止它，因此在隐藏标签页中依赖时间精度本身就是不可靠的。显式地暂停会更清晰。防止重复创建定时器还能避免在 startPolling 被调用两次时多个定时器叠加。

暂停媒体播放

const video = document.querySelector("video");

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    video.pause();
  } else {
    video.play().catch(() => {
      // Autoplay may be blocked by the browser; handle silently
    });
  }
});

.catch() 处理程序非常重要，因为 video.play() 返回一个 promise，当浏览器阻止自动播放时它可能会被拒绝，否则会抛出未捕获的错误。

自动保存表单草稿

在用户离开标签页时触发保存，而不是依赖固定的定时器：

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    saveDraft();
  }
});

在用户离开前发送分析数据

对于会话结束数据，可以将 visibilitychange 事件 与 pagehide 结合使用，并通过 navigator.sendBeacon() 在不阻塞导航的情况下可靠地发送数据：

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon(
      "/analytics",
      JSON.stringify({ event: "tab_hidden" })
    );
  }
});

window.addEventListener("pagehide", () => {
  navigator.sendBeacon(
    "/analytics",
    JSON.stringify({ event: "page_unload" })
  );
});

避免在这种场景下使用 unload 事件——在现代浏览器中它不可靠，且会破坏前进/后退缓存（bfcache），从而降低导航性能。在移动浏览器上，状态为 "hidden" 的 visibilitychange 通常是判定会话结束的唯一可靠信号，因为 pagehide 和 beforeunload 并不总是会触发。

清理事件监听器

当监听器不再需要时一定要移除它们，特别是在单页应用中：

function handleVisibility() {
  console.log(document.visibilityState);
}

document.addEventListener("visibilitychange", handleVisibility);

// Later, when tearing down:
document.removeEventListener("visibilitychange", handleVisibility);

请记住，传递给 removeEventListener 的引用必须与 addEventListener 中使用的函数引用完全相同。内联的箭头函数无法被移除，因为每次都会创建一个新的引用。

结语

Page Visibility API——具体来说是 document.hidden、document.visibilityState 以及 visibilitychange 事件——是检测浏览器标签页变为非活动状态的正确且现代的方法。它在所有当前浏览器中都能可靠工作，在 window 焦点和失焦事件处理不到位的标签页切换场景中表现准确，并能与 navigator.sendBeacon() 和 pagehide 事件良好配合，处理会话结束逻辑。用它来停止不必要的工作、保存状态或追踪用户参与度，并在用完后清理你的监听器。

常见问题

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.