Document：visibilitychange 事件

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

当其选项卡的内容变得可见或被隐藏时，会在 document 上触发 visibilitychange 事件。

该事件不可取消。

语法

在像 addEventListener() 的方法中使用事件名称，或设置事件处理器属性。

js
addEventListener("visibilitychange", (event) => {});

onvisibilitychange = (event) => {};

事件类型

通用 Event。

使用说明

该事件不包括文档的更新可见性状态，但是你可以从文档的 visibilityState 属性中获取该信息。

当用户导航到新页面、切换标签页、关闭标签页、最小化或关闭浏览器，或者在移动设备上从浏览器切换到不同的应用程序时，该事件就以 visibilityState 为 hidden 的状态触发。过渡到 hidden 是页面能可靠观察到的最后一个事件，因此开发人员应将其视为用户会话的可能结束（例如，用于发送分析数据）。

向 hidden 过渡也是页面停止用户界面更新和停止用户不想在后台运行的任何任务的好时机。

示例

在文档转向隐藏状态时暂停音乐

本示例的音频在页面隐藏时暂停播放，在页面再次可见时恢复播放。

有关完整示例，参见页面可见性 API：在页面隐藏时暂停音频文档。

js
document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else {
    // 如果音频处于“隐藏播放”，则恢复播放。
    if (playingOnHide) {
      audio.play();
    }
  }
});

在文档转向隐藏状态时发送会话结束分析报告

本示例将 hidden 转换视为用户会话的结束，并使用 Navigator.sendBeacon() API 发送相应的分析结果。

js
document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
};

规范

Specification
HTML Standard
# event-visibilitychange
HTML Standard
# handler-onvisibilitychange

浏览器兼容性

BCD tables only load in the browser

参见