这篇翻译不完整。请帮忙从英语翻译这篇文章

使用选项卡式浏览,任何给定网页都有可能在后台,因此对用户不可见。页面可见性 API提供了您可以观察的事件,以便了解文档何时可见或隐藏,以及查看页面当前可见性状态的功能。

注意:页面可见性 API对于节省资源和提高性能特别有用,它使页面在文档不可见时避免执行不必要的任务。

当用户最小化窗口或切换到另一个选项卡时,API会发送visibilitychange事件,让听众知道页面状态已更改。你可以检测事件并执行某些操作或行为不同。例如,如果您的网络应用正在播放视频,则可以在用户将标签放入背景时暂停视频,并在用户返回标签时恢复播放。 用户不会在视频中丢失位置,视频的音轨不会干扰新前景选项卡中的音频,并且用户在此期间不会错过任何视频。

<iframe>的可见性状态与父文档相同。使用CSS属性(例如display: none;)隐藏<iframe>不会触发可见性事件或更改框架中包含的文档的状态。

使用情景

一些例子:

  • 网站有图片轮播效果,只有在用户观看轮播的时候,才会自动展示下一张幻灯片。
  • 显示信息仪表盘的应用程序不希望在页面不可见时轮询服务器进行更新。
  • 页面想要检测是否正在渲染,以便可以准确的计算网页浏览量
  • 当设备进入待机模式时,网站想要关闭设备声音(用户按下电源键关闭屏幕)

开发者在过去使用不完善的代理来处理这一点。比如,监听 blur 和 focus 事件来帮助你了解页面是否处于活动状态,但是它并没有告诉你页面是对用户隐藏的。页面可见性 API 解决了这个问题。

注意:虽然onbluronfocus会告诉你用户是否切换窗口,但不一定意味着它是隐藏的。当用户切换选项卡或最小化包含选项卡的浏览器窗口时,页面才会隐藏。

示例

看一个 在线的例子 (带声音的视频)

在此例中,当你切换到另一个标签时视频会暂停,当你返回到当前标签时视频会再次播放,代码如下:

// 设置隐藏属性和改变可见属性的事件的名称
var hidden, visibilityChange; 
if (typeof document.hidden !== "undefined") { // Opera 12.10 and Firefox 18 and later support 
  hidden = "hidden";
  visibilityChange = "visibilitychange";
} else if (typeof document.msHidden !== "undefined") {
  hidden = "msHidden";
  visibilityChange = "msvisibilitychange";
} else if (typeof document.webkitHidden !== "undefined") {
  hidden = "webkitHidden";
  visibilityChange = "webkitvisibilitychange";
}
 
var videoElement = document.getElementById("videoElement");

// 如果页面是隐藏状态,则暂停视频
// 如果页面是展示状态,则播放视频
function handleVisibilityChange() {
  if (document[hidden]) {
    videoElement.pause();
  } else {
    videoElement.play();
  }
}

// 如果浏览器不支持addEventListener 或 Page Visibility API 给出警告
if (typeof document.addEventListener === "undefined" || typeof document[hidden] === "undefined") {
  console.log("This demo requires a browser, such as Google Chrome or Firefox, that supports the Page Visibility API.");
} else {
  // 处理页面可见属性的改变
  document.addEventListener(visibilityChange, handleVisibilityChange, false);
    
  // 当视频暂停,设置title
  // This shows the paused
  videoElement.addEventListener("pause", function(){
    document.title = 'Paused';
  }, false);
    
  // 当视频播放,设置title
  videoElement.addEventListener("play", function(){
    document.title = 'Playing'; 
  }, false);

}

属性

Document.hidden 只读

如果页面处于被认为是对用户隐藏状态时返回true,否则返回false。

Document.visibilityState 只读

是一个用来展示文档可见性状态的字符串。可能的值:

  • visible : 页面内容至少是部分可见。 在实际中,这意味着页面是非最小化窗口的前景选项卡。
  • hidden : 页面内容对用户不可见。 在实际中,这意味着文档可以是一个后台标签,或是最小化窗口的一部分,或是在操作系统锁屏激活的状态下。
  • prerender : 页面内容正在被预渲染且对用户是不可见的(被document.hidden当做隐藏). 文档可能初始状态为prerender,但绝不会从其它值转为该值。 注释:浏览器支持是可选的。
  • unloaded : 页面正在从内存中卸载。 注释:浏览器支持是可选的。
Document.onvisibilitychange
EventListener 提供在visibilitychange 事件被触发时要调用的代码。
//startSimulation 和 pauseSimulation 在其他地方定义
function handleVisibilityChange() {
  if (document.hidden) {
    pauseSimulation();
  } else  {
    startSimulation();
  }
}

document.addEventListener("visibilitychange", handleVisibilityChange, false);

规范

Specification Status Comment
Page Visibility (Second Edition) Recommendation Initial definition.

浏览器兼容性

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 13 webkit
33
18 (18) [2] 10 12.10[1] 7
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support 4.4 webkit 18.0 (18) [2] 10 12.10[1] 7

[1]当浏览器最小化时,不会触发visibilitychange 事件,也不会设置hidden为true。

[2] 从Firefox 10 到 Firefox 51, 这个属性在加上 -moz- 前缀后可以被使用。

参考

文档标签和贡献者

此页面的贡献者: zhangchen, Gale, Wineki
最后编辑者: zhangchen,