diff --git a/files/zh-cn/web/api/document/visibilitychange_event/index.md b/files/zh-cn/web/api/document/visibilitychange_event/index.md index 1c3e9008da16f9..c785b17bb524d2 100644 --- a/files/zh-cn/web/api/document/visibilitychange_event/index.md +++ b/files/zh-cn/web/api/document/visibilitychange_event/index.md @@ -1,55 +1,45 @@ --- -title: visibilitychange +title: Document:visibilitychange 事件 slug: Web/API/Document/visibilitychange_event --- {{APIRef}} -当其选项卡的内容变得可见或被隐藏时,会在文档上触发 `visibilitychange` (能见度更改) 事件。 +当其选项卡的内容变得可见或被隐藏时,会在 document 上触发 `visibilitychange` 事件。 -## 概述 +该事件不可取消。 -- Interface - - : {{domxref("event")}} -- Bubbles - - : Yes -- Cancelable - - : No -- Target - - : {{domxref("Document")}} -- Default Action - - : None +## 语法 + +在像 {{domxref("EventTarget.addEventListener", "addEventListener()")}} 的方法中使用事件名称,或设置事件处理器属性。 + +```js +addEventListener("visibilitychange", (event) => {}); + +onvisibilitychange = (event) => {}; +``` + +## 事件类型 + +通用 {{domxref("Event")}}。 ## 使用说明 该事件不包括文档的更新的可见性状态,但是你可以从文档的 {{domxref("Document.visibilityState", "visibilityState")}} 属性中获取该信息。 -> **警告:** 当 visibleStateState 属性的值转换为 `hidden` 时,Safari 不会按预期触发 `visibilitychange`;因此,在这种情况下,你还需要包含代码以侦听 [`pagehide`](/zh-CN/docs/Web/API/Window/pagehide_event) 事件。 +当用户导航到新页面、切换标签页、关闭标签页、最小化或关闭浏览器,或者在移动设备上从浏览器切换到不同的应用程序时,该事件就会触发,其 `visibilityState` 为 `hidden`。过渡到 `hidden` 是页面能可靠观察到的最后一个事件,因此开发人员应将其视为用户会话的可能结束(例如,用于[发送分析数据](/zh-CN/docs/Web/API/Navigator/sendBeacon))。 -> **警告:** 出于兼容性原因,请确保使用 `document.addEventListener` 而不是 `window.addEventListener` 来注册回调。Safari <14.0 仅支持前者。 +向 `hidden` 过渡也是页面停止用户界面更新和停止用户不想在后台运行的任何任务的好时机。 -## 属性 +## 示例 -| Property | Type | Description | -| ------------------------------- | -------------------------- | ------------------------------------------------------ | -| `target` {{readonlyInline}} | {{domxref("EventTarget")}} | The event target (the topmost target in the DOM tree). | -| `type` {{readonlyInline}} | {{domxref("DOMString")}} | The type of event. | -| `bubbles` {{readonlyInline}} | {{jsxref("Boolean")}} | Whether the event normally bubbles or not. | -| `cancelable` {{readonlyInline}} | {{jsxref("Boolean")}} | Whether the event is cancellable or not. | - -## 例子 +### 在文档转向隐藏状态时暂停音乐 本示例在文档可见时开始播放音乐曲目,在文档不再可见时暂停音乐。 ```js -document.addEventListener("visibilitychange", function () { - console.log(document.visibilityState); -}); -``` - -``` -document.addEventListener("visibilitychange", function() { - if (document.visibilityState === 'visible') { +document.addEventListener("visibilitychange", () => { + if (document.visibilityState === "visible") { backgroundMusic.play(); } else { backgroundMusic.pause(); @@ -57,6 +47,18 @@ document.addEventListener("visibilitychange", function() { }); ``` +### 在文档转向隐藏状态时发送会话结束分析报告 + +本示例将 `hidden` 转换视为用户会话的结束,并使用 {{domxref("Navigator.sendBeacon()")}} API 发送相应的分析结果。 + +```js +document.onvisibilitychange = () => { + if (document.visibilityState === "hidden") { + navigator.sendBeacon("/log", analyticsData); + } +}; +``` + ## 规范 {{Specifications}} @@ -65,7 +67,9 @@ document.addEventListener("visibilitychange", function() { {{Compat}} -## 相关链接 +## 参见 -- [使用页面可见性 API](/zh-CN/docs/DOM/Using_the_Page_Visibility_API) +- [页面可见性 API](/zh-CN/docs/Web/API/Page_Visibility_API) - {{domxref("Document.visibilityState")}} +- [使用页面可见性,不丢失用户和应用程序状态](https://www.igvita.com/2015/11/20/dont-lose-user-and-app-state-use-page-visibility/)详细解释了为什么应该使用 `visibilitychange`,而不是 `beforeunload`/`unload`。 +- [页面生命周期 API](https://developer.chrome.com/blog/page-lifecycle-api/) 提供了在 web 应用程序中处理页面生命周期行为的最佳实践指导。