WindowEventHandlers.onpopstate - Web API 接口参考

WindowEventHandlers.onpopstate
==============================

`WindowEventHandlers` 混入（mixin）中的 `onpopstate` 属性是用于处理 window 对象上的 `popstate` 事件的事件处理程序。

每当激活同一文档中不同的历史记录条目时，`popstate` 事件就会在对应的 `window` 对象上触发。如果当前处于激活状态的历史记录条目是由 `history.pushState()` 方法创建的或者是由 `history.replaceState()` 方法修改的，则 `popstate` 事件的 `state` 属性包含了这个历史记录条目的 `state` 对象的一个拷贝。

**备注：** 调用 `history.pushState()` 或者 `history.replaceState()` 不会触发 `popstate` 事件。`popstate` 事件只会在浏览器某些行为下触发，比如点击后退按钮（或者在 JavaScript 中调用 `history.back()` 方法）。即，在同一文档的两个历史记录条目之间导航会触发该事件。

语法
--

```js
window.onpopstate = funcRef;
```

* `funcRef` 是一个处理函数。
示例
--

假如当前网页地址为 `http://example.com/example.html`，则运行下述代码将触发警告对话框：

```js
window.onpopstate = function (event) {
  alert(
    "location: " +
      document.location +
      ", state: " +
      JSON.stringify(event.state),
  );
};

history.pushState({ page: 1 }, "title 1", "?page=1");
history.pushState({ page: 2 }, "title 2", "?page=2");
history.replaceState({ page: 3 }, "title 3", "?page=3");
history.back(); // 弹出 "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // 弹出 "location: http://example.com/example.html, state: null
history.go(2); // 弹出 "location: http://example.com/example.html?page=3, state: {"page":3}
```

注意，即便是没有关联 `state` 对象的原始的历史条目（比如 `http://example.com/example.html`），`popstate` 事件也仍会在我们第二次调用 `history.back()`，激活这一历史条目后触发。

规范
--

| Specification |
| --- |
| HTML Standard # event-popstate |
| HTML Standard # handler-window-onpopstate |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `window.history`
* Manipulating the browser history


Window.sessionStorage - Web API 接口参考

Window.sessionStorage
=====================

`sessionStorage` 属性允许你访问一个，对应当前源的 session `Storage` 对象。它与 `localStorage` 相似，不同之处在于 `localStorage` 里面存储的数据没有过期时间设置，而存储在 `sessionStorage` 里面的数据在页面会话结束时会被清除。

* 页面会话在浏览器打开期间一直保持，并且重新加载或恢复页面仍会保持原来的页面会话。
* **在新标签或窗口打开一个页面时会复制顶级浏览会话的上下文作为新会话的上下文，这点和 session cookie 的运行方式不同。**
* 打开多个相同的 URL 的 Tabs 页面，会创建各自的 `sessionStorage`。
* 关闭对应浏览器标签或窗口，会清除对应的 `sessionStorage`。

**备注：** 应该注意，存储在 sessionStorage 或 localStorage 中的数据**特定于页面的协议**。也就
 是说 `http://example.com` 与 `https://example.com` 的 sessionStorage 相互隔离。

被存储的键值对总是以 UTF-16 DOMString 的格式所存储，其使用两个字节来表示一个字符。对于对象、整数 key 值会自动转换成字符串形式。

语法
--

```js
// 保存数据到 sessionStorage
sessionStorage.setItem("key", "value");

// 从 sessionStorage 获取数据
let data = sessionStorage.getItem("key");

// 从 sessionStorage 删除保存的数据
sessionStorage.removeItem("key");

// 从 sessionStorage 删除所有保存的数据
sessionStorage.clear();
```

### 返回值

一个 `Storage` 对象。

示例
--

下面的代码访问当前域名的 session `Storage` 对象，并使用 `Storage.setItem()` 访问往里面添加一个数据条目。

```js
sessionStorage.setItem("myCat", "Tom");
```

下面的示例会自动保存一个文本输入框的内容，如果浏览器因偶然因素被刷新了，文本输入框里面的内容会被恢复，因此写入的内容不会丢失。

```js
// 获取文本输入框
let field = document.getElementById("field");

// 检测是否存在 autosave 键值
// (这个会在页面偶然被刷新的情况下存在)
if (sessionStorage.getItem("autosave")) {
  // 恢复文本输入框的内容
  field.value = sessionStorage.getItem("autosave");
}

// 监听文本输入框的 change 事件
field.addEventListener("change", function () {
  // 保存结果到 sessionStorage 对象中
  sessionStorage.setItem("autosave", field.value);
});
```

**备注：** 完整的使用示例可以查看使用 Web Storage API 一文。

规范
--

| Specification |
| --- |
| HTML Standard # dom-sessionstorage-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

 各浏览器支持的 localStorage 和 sessionStorage 容量上限不同。测试页面 detailed rundown of all the storage capacities for various browsers。

**备注：** 从 iOS 5.1 之后，移动端的 Safari 将 localStorage 数据存储在 cache 文件中，在操作系统的要求下，会偶尔进行清除，特别是空间不足时。

相关链接
----

* 使用 Web Storage API
* `Window.localStorage`


Window.external - Web API 接口参考

Window.external
===============

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

`Window` API 的 `external` 属性返回一个 `External` 接口的实例，这个接口本来用于包含一些用来向浏览器添加外部搜索提供者（external search providers）的函数，但是，现在这个属性已被废弃，其中的函数现在都是空函数，无任何功能，仅为了符合规范而存在。

方法
--

`External` 对象有以下方法：

| 方法 | 描述 |
| --- | --- |
| `AddSearchProvider(descriptionURL)` | 空函数，无任何作用。参见 Autodiscovery of search plugins (en-US)。 |
| `IsSearchProviderInstalled()` | 空函数，无任何作用。 |

规范
--

| Specification |
| --- |
| HTML Standard # external |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window: blur event - Web API 接口参考

Window: blur event
==================

当元素失去焦点时，\*\*`blur`\*\*事件将触发。

与 `blur` 相反的是`focus`。

|  |  |
| --- | --- |
| Bubbles（是否支持冒泡） | No |
| Cancelable（可撤销） | No |
| Interface（接口） | `FocusEvent` |
| Event handler property（事件处理程序属性） | `onblur` |
| Sync / Async（同步/异步） | Sync |
| Composed | Yes |

示例
--

### 在线示例

此示例当文档失去焦点时，更改其外观。它使用`addEventListener()` 去监听`focus`和 `blur` 事件。

#### HTML

```html
<p id="log">Click on this document to give it focus.</p>
```

#### CSS

```css
.paused {
  background: #ddd;
  color: #555;
}
```

#### JavaScript

```js
function pause() {
  document.body.classList.add("paused");
  log.textContent = "FOCUS LOST!";
}

function play() {
  document.body.classList.remove("paused");
  log.textContent =
    "This document has focus. Click outside the document to lose focus.";
}

const log = document.getElementById("log");

window.addEventListener("blur", pause);
window.addEventListener("focus", play);
```

#### 结果

规范
--

| Specification |
| --- |
| UI Events # event-type-blur |
| HTML Standard # handler-onblur |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

`document. activeelement` 的值在处理时因浏览器而异（Firefox bug 452307）：IE10 将其设置为焦点将移动到的元素，而 Firefox 和 Chrome 通常将其设置为文档的 body。

参见
--

* 相关联事件：`focus`
* Element 目标上的这个事件:`blur` 事件


Window.stop() - Web API 接口参考

Window.stop()
=============

**`window.stop()`** 方法的效果相当于点击了浏览器的停止按钮。由于脚本的加载顺序，该方法不能阻止已经包含在加载中的文档，但是它能够阻止图片、新窗口、和一些会延迟加载的对象的加载。

语法
--
```

window.stop()
```

示例
--

```js
window.stop();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-stop-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.customElements - Web API 接口参考

Window.customElements
=====================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**`customElements`** 是 `Window` 对象上的一个只读属性，接口返回一个 `CustomElementRegistry` 对象的引用，可用于注册新的 custom element，或者获取之前定义过的自定义元素的信息。

例子
--

这个属性最常用的例子是用来获取使用`CustomElementRegistry.define()`方法定义和注册的自定义元素，例如：

```js
let customElementRegistry = window.customElements;
customElementRegistry.define("my-custom-element", MyCustomElement);
```

However, it is usually shortened to something like the following:

```js
customElements.define(
  "element-details",
  class extends HTMLElement {
    constructor() {
      super();
      const template = document.getElementById(
        "element-details-template",
      ).content;
      const shadowRoot = this.attachShadow({ mode: "open" }).appendChild(
        template.cloneNode(true),
      );
    }
  },
);
```

参阅我们的 web-components-examples 获取更多有用的例子。

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-customelements |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


window.scrollByPages - Web API 接口参考

window.scrollByPages
====================

### 概述

在当前文档页面按照指定的页数翻页。

### 语法
```

window.scrollByPages(pages)
```

### 参数

* `pages` 翻页数，正数向下翻，负数向上翻`.`
### `例子`
```

// 当前文档向下翻一页
window.scrollByPages(1);

// 当前文档向上翻一页
window.scrollByPages(-1);
```

### `备注`

`查看 window.scrollBy, window.scrollByLines, window.scroll, window.scrollTo.`

### `规范`

`DOM Level 0 不属于任何标准`


Window.scrollMaxX - Web API 接口参考

Window.scrollMaxX
=================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**`Window.scrollMaxX`** 只读属性，返回有关文档可水平滚动的最大像素数。

语法
--
```

xMax = window.scrollMaxX
```

* `xMax` 是像素数。
示例
--

```js
// 滚动到页面的右边缘
let maxX = window.scrollMaxX;

window.scrollTo(maxX, 0);
```

提示
--

不要用这个属性来获得文档总宽度，文档总宽度不等于window.innerWidth (en-US) + window.scrollMaxX。因为 `window.innerWidth`包含所有可见的垂直滚动条的宽度，所以结果会超出文档总宽度，多出所有可见的垂直滚动条的宽度。作为替代，可使用`document.body.scrollWidth`。查看相关：`window.scrollMaxY`。

规范
--

不属于任何规范。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


window.cancelIdleCallback() - Web API 接口参考

window.cancelIdleCallback()
===========================

**`window.cancelIdleCallback()`** 方法用于取消之前调用`window.requestIdleCallback()` 的回调。

语法
--

```js
cancelIdleCallback(handle)
```

### 参数

`handle`

调用 `window.requestIdleCallback()` 时返回的 ID.

### 返回值

无（`undefined`）。

示例
--

在文章 Cooperative Scheduling of Background Tasks API 中可以查看 完整示例 。

规范
--

| Specification |
| --- |
| requestIdleCallback() Cooperative Scheduling of Background Tasks # the-cancelidlecallback-method |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.outerHeight - Web API 接口参考

Window.outerHeight
==================

**`Window.outerHeight`** 只读属性返回整个浏览器窗口的高度（以像素为单位），包括侧边栏（如果存在）、窗口镶边（window chrome）和窗口调正边框（window resizing border/handle）。

备注
--

要改变窗口的大小，请查看 `window.resizeBy()` 和 `window.resizeTo()`。

要获取窗口的内层高度，即页面被显示区域的高度，可查看 `window.innerHeight`。

### 图像示例

下面的示意图展示了 `outerHeight` 和 `innerHeight` 两者的不同。

![innerHeight 和 outerHeight](/zh-CN/docs/Web/API/Window/outerHeight/firefoxinnervsouterheight2.png)

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-outerheight |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `window.innerHeight`
* `window.innerWidth`
* `window.outerWidth`
* `window.resizeBy()`
* `window.resizeTo()`


Window.scrollBy() - Web API 接口参考

Window.scrollBy()
=================

**`Window.scrollBy()`** 方法在窗口中按指定的偏移量滚动文档。

语法
--

```js
scrollBy(x-coord, y-coord)
scrollBy(options)
```

### 参数

* `x-coord` 是你想滚动的水平像素值。
* `y-coord` 是你想滚动的垂直像素值。

- 或：

`options`

包含以下参数的字典

`top`

指定沿 Y 轴滚动窗口或元素的像素数。

`left`

指定沿 X 轴滚动窗口或元素的像素数。

`behavior`

指定滚动是否应该平滑（`smooth`）、瞬时运动到该位置（`instant`）、或者让浏览器选择（`auto`，默认）。

### 返回值

无（`undefined`）。

示例
--

向下滚动一页：

```js
window.scrollBy(0, window.innerHeight);
```

向上滚动一页：

```js
window.scrollBy(0, -window.innerHeight);
```

使用 `options`：

```js
window.scrollBy({
  top: 100,
  left: 100,
  behavior: "smooth",
});
```

备注
--

`window.scrollBy()` 滚动指定的距离，而 `window.scroll()` 滚动至文档中的绝对位置。参见 `window.scrollByLines()` 和 `window.scrollByPages()`。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-scrollby |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window：showDirectoryPicker() 方法 - Web API 接口参考

Window：showDirectoryPicker() 方法
===============================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Window` 接口的 **`showDirectoryPicker()`** 方法用于显示一个目录选择器，以允许用户选择一个目录。

语法
--

```js
showDirectoryPicker()
```

### 参数

`options` 可选

选项对象，包含以下属性：

`id`

通过指定 ID，浏览器能够记住不同 ID 所对应的目录。当使用相同的 ID 打开另一个目录选择器时，选择器会打开相同的目录。

`mode`

字符串，默认为 `"read"`，可对目录进行只读访问。设为 `"readwrite"` 可对目录进行读写访问。

`startIn`

一个 `FileSystemHandle` 对象或者代表某个众所周知的目录的字符串（如：`"desktop"`、`"documents"`、`"downloads"`、`"music"`、`"pictures"`、`"videos"`）。用于指定选择器的起始目录。

### 返回值

一个 `Promise` 对象，会兑现一个 `FileSystemDirectoryHandle` 对象。

### 异常

`AbortError`

当用户直接关闭了目录选择器或选择的目录是敏感目录时将会抛出 AbortError。

安全性
---

要求发生临时性用户活动 (en-US)。用户必须与页面或 UI 元素进行交互才能使该特性正常运行。

示例
--

以下异步函数可以显示一个目录选择器并在用户选择后返回一个 `FileSystemDirectoryHandle` 对象。

```js
async function getDir() {
  const dirHandle = await window.showDirectoryPicker();

  // 操作 dirHandle 的后续代码
}
```

规范
--

| Specification |
| --- |
| File System Access # api-showdirectorypicker |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 文件系统 API
* 文件系统访问 API：简化对本地文件的访问


Window.locationbar - Web API 接口参考

Window.locationbar
==================

概要
--

返回一个可以检查 visibility 属性的 `locationbar` 对象。

语法
--
```

objRef = window.locationbar
```

示例
--

以下完整的 HTML 示例显示了使用 locationbar 对象的 visible 属性的方式。

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Various DOM Tests</title>

    <script>
 var visible = window.locationbar.visible;
 </script>
  </head>
  <body>
    <p>Various DOM Tests</p>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-locationbar-dev |

相关链接
----

* `window.locationbar`, `window.menubar`, `window.personalbar` (en-US), `window.scrollbars`, `window.statusbar` (en-US), `window.toolbar` (en-US)


Window.innerHeight - Web API 接口参考

Window.innerHeight
==================

概述
--

浏览器窗口的视口（viewport）高度（以像素为单位）；如果有水平滚动条，也包括滚动条高度。

**备注：** If you use `nsIDOMWindowUtils.setCSSViewport()` to set the virtual window size for page layout purposes, the value returned by this property corresponds to the viewport height set using that method.

语法
--
```

var intViewportHeight = window.innerHeight;
```

### 值

`intViewportHeight` 为浏览器窗口的视口的高度。

`window.innerHeight` 属性为只读，且没有默认值。

备注
--

任何窗口对象，如 `window`、frame、frameset 或 secondary window 都支持 `innerHeight` 属性。

有一个算法用来获取不包括水平滚动条的视口高度。

例子
--

### 假设有一个 frameset

```js
var intFrameHeight = window.innerHeight; // or

var intFrameHeight = self.innerHeight;
// 返回 frameset 里面的 frame 视口的高度

var intFramesetHeight = parent.innerHeight;
// 返回上一级 frameset 的视口的高度

var intOuterFramesetHeight = top.innerHeight;
// 返回最外部 frameset 的视口的高度
```

{{todo("link to an interactive demo here")}}
改变一个窗口的大小，可以查看 `window.resizeBy()` 和 `window.resizeTo()`。

想获取窗口的外层高度（outer height），即整个浏览器窗口的高度，请查看 `window.outerHeight`。

### 图像示例

下面的示意图展示了 `outerHeight` 和 `innerHeight` 两者的区别。

![innerHeight vs outerHeight illustration](/zh-CN/docs/Web/API/Window/innerHeight/firefoxinnervsouterheight2.png)

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

标准相关信息
------

DOM Level 0。不属于任何 W3C 技术规范或推荐。

相关链接
----

* `window.innerWidth`
* `window.outerHeight`
* `window.outerWidth`


Window：beforeunload 事件 - Web API 接口参考

Window：beforeunload 事件
======================

当浏览器窗口关闭或者刷新时，会触发 **`beforeunload`** 事件。当前页面不会直接关闭，可以点击确定按钮关闭或刷新，也可以取消关闭或刷新。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | Yes |
| Interface | `Event` |
| Event handler property | `onbeforeunload` |

事件使网页能够触发一个确认对话框，询问用户是否真的要离开该页面。如果用户确认，浏览器将导航到新页面，否则导航将会取消。

根据规范，要显示确认对话框，事件处理程序需要在事件上调用`preventDefault()`。

但是请注意，并非所有浏览器都支持此方法，而有些浏览器需要事件处理程序实现两个遗留方法中的一个作为代替：

* 将字符串分配给事件的`returnValue`属性
* 从事件处理程序返回一个字符串。

某些浏览器过去在确认对话框中显示返回的字符串，从而使事件处理程序能够向用户显示自定义消息。但是，此方法已被弃用，并且在大多数浏览器中不再支持。

为避免意外弹出窗口，除非页面已与之交互，否则浏览器可能不会显示在`beforeunload`事件中创建的提示，甚至根本不会显示它们。

将事件处理程序/监听器加到`window`或 `document`的`beforeunload`事件后，将阻止浏览器使用内存中的页面导航缓存，例如Firefox 的 Back-Forward 缓存或WebKit 的 Page Cache。

HTML 规范指出在此事件中调用`window.alert()`，`window.confirm()`以及`window.prompt()`方法，可能会失效。更多详细信息，请参见HTML 规范。

示例
--

HTML 规范指出作者应该使用 `Event.preventDefault()` 而非 `Event.returnValue`，然而，不是所有浏览器都支持这么做。

```js
window.addEventListener("beforeunload", (event) => {
  // Cancel the event as stated by the standard.
  event.preventDefault();
  // Chrome requires returnValue to be set.
  event.returnValue = "";
});
```

规范
--

| Specification |
| --- |
| HTML Standard # event-beforeunload |
| HTML Standard # handler-window-onbeforeunload |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关事件：`DOMContentLoaded`、`readystatechange`、`load`、`unload`
* Unloading Documents — Prompt to unload a document
* Remove Custom Messages in onbeforeload Dialogs after Chrome 51


Window.scrollX - Web API 接口参考

Window.scrollX
==============

概述
--

返回文档/页面水平方向滚动的像素值。

语法
--
```

var x = window.scrollX;
```

### 参数

* x 为该文档从左侧开始滚动的像素值。
示例
--

```js
// 如果 scrollX 大于 400，则把文档重新滚动到左上角。
if (window.scrollX > 400) {
  window.scroll(0, 0);
}
```

备注
--

`pageXOffset` 属性是 `scrollX` 属性的别名：
```

window.pageXOffset == window.scrollX; // 总是 true
```

为了跨浏览器兼容性，请使用 `window.pageXOffset` 代替 `window.scrollX`。另外，旧版本的 IE（<9）两个属性都不支持，必须通过其他的非标准属性来解决此问题。完整的兼容性代码如下：

```js
var x =
  window.pageXOffset !== undefined
    ? window.pageXOffset
    : (document.documentElement || document.body.parentNode || document.body)
        .scrollLeft;
var y =
  window.pageYOffset !== undefined
    ? window.pageYOffset
    : (document.documentElement || document.body.parentNode || document.body)
        .scrollTop;
```

规范
--

* CSSOM View Module: window.scrollX (Editor's Draft)
相关链接
----

* `window.scrollY`


Window.resizeTo - Web API 接口参考

Window.resizeTo
===============

概述
--

动态调整窗口的大小。

语法
--
```

window.resizeTo(aWidth, aHeight)
```

### 参数

* `aWidth` 是一个整数，表示新的 `outerWidth`（单位：像素）（包括滚动条、窗口边框等）。
* `aHeight` 是一个整数，表示新的 `outerHeight`（单位：像素）（包括滚动条、标题栏、窗口边框等）。
示例
--

```js
// 将窗口设置为整个屏幕的 1/4 大小（面积）
function quarter() {
  window.resizeTo(window.screen.availWidth / 2, window.screen.availHeight / 2);
}
```

备注
--

从 Firefox 7 开始，不能改变浏览器窗口的大小了，要依据下面的规则：

1. 不能设置那些不是通过 window.open 创建的窗口或 Tab 的大小。
2. 当一个窗口里面含有一个以上的 Tab 时，无法设置窗口的大小。
规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-resizeto |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `window.resizeBy()`


Window.screen - Web API 接口参考

Window.screen
=============

返回当前 window 的 screen 对象。screen 对象实现了`Screen`接口，它是个特殊的对象，返回当前渲染窗口中和屏幕有关的属性。

语法
--
```

screenObj = window.screen;
```

示例
--

```js
if (screen.pixelDepth < 8) {
  // use low-color version of page
} else {
  // use regular, colorful page
}
```

Specification
-------------

TBD


Window.blur() - Web API 接口参考

Window.blur()
=============

总结
--

将焦点移出顶层窗口。

语法
--
```

window.blur()
```

示例
--

```js
window.blur();
```

注意
--

使用 window.blur() 方法与用户主动将焦点移出顶层窗口本质上是一样的。

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-blur |


Window.showModalDialog() - Web API 接口参考

Window.showModalDialog()
========================

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

**`Window.showModalDialog()`** 用于创建和展示一个指向特定网页的模态对话框。

语法
--
```

returnVal = window.showModalDialog(uri[, arguments][, options]);
```

其中

* `returnVal` 集合类型 (Set) 返回值。由`uri`指定的页面返回。
* `uri` 要在模态对话框中打开的页面 URI。
* `arguments` 可选变量。可以通过该参数将需要的值传入对话框。
* `options` 可选字符串参数。用于设置对话框打开的样式，使用一个或多个逗号分隔。

| Syntax | Description |
| --- | --- |
| `center: {on | off | yes | no | 1 | 0 }` | If this argument's value is `on`, `yes`, or 1, the dialog window is centered on the desktop; otherwise it's hidden. The default value is `yes`. |
| `dialogheight: height` | Specifies the height of the dialog box; by default, the size is specified in pixels. |
| `dialogleft: left` | Specifies the horizontal position of the dialog box in relation to the upper-left corner of the desktop. |
| `dialogwidth: width` | Specifies the width of the dialog box; by default, the size is specified in pixels. |
| `dialogtop: top` | Specifies the vertical position of the dialog box in relation to the upper-left corner of the desktop. |
| `resizable: {on | off | yes | no | 1 | 0 }` | If this argument's value is `on`, `yes`, or 1, the dialog window can be resized by the user; otherwise its size is fixed. The default value is `no`. |
| `scroll: {on | off | yes | no | 1 | 0 }` | If this argument's value is `on`, `yes`, or 1, the dialog window has scroll bars; otherwise its size is fixed. The default value is `no`. |

**备注：** Firefox does not implement the `dialogHide`, `edge`, `status`, or `unadorned` arguments.

Compatibility
-------------

Introduced by Microsoft Internet Explorer 4. Support added to Firefox in Firefox 3 (deprectated in Fx 28), and to Safari in Safari 5.1.

Examples
--------

Try out `showModalDialog()`.

Notes
-----

`showModalDialog()` is currently being standardized as part of HTML5. The third argument (for additional options) is not present in the HTML5 version, and is (safely) ignored by both Safari and Chrome.

Specification
-------------

* `showModalDialog()`
* HTML5 Dialogs implemented using separate documents


Window.scrollY - Web API 接口参考

Window.scrollY
==============

概述
--

返回文档在垂直方向已滚动的像素值。

语法
--
```

var y = window.scrollY;
```

* `y` 是文档从顶部开始滚动过的像素值。
示例
--

```js
// 保证刚好滚动到第二页
if (window.scrollY) {
  window.scroll(0, 0); // 重置滚动位置为文档的左上角
}

window.scrollByPages(1);
```

备注
--

如果正在使用相对滚动函数，如 `window.scrollBy`、`window.scrollByLines` 或 `window.scrollByPages`，则需要使用该属性来检测文档是否已被滚动了某段距离。

`pageYOffset` 属性是 `scrollY` 属性的别名：
```

window.pageYOffset == window.scrollY; // 总是返回 true
```

为了跨浏览器兼容，请使用 `window.pageYOffset` 代替 `window.scrollY`。另外，旧版本 IE（<9）两个属性都不支持，必须使用其他的非标准属性。完整的兼容性代码如下：

```js
var supportPageOffset = window.pageXOffset !== undefined;
var isCSS1Compat = (document.compatMode || "") === "CSS1Compat";

var x = supportPageOffset
  ? window.pageXOffset
  : isCSS1Compat
    ? document.documentElement.scrollLeft
    : document.body.scrollLeft;
var y = supportPageOffset
  ? window.pageYOffset
  : isCSS1Compat
    ? document.documentElement.scrollTop
    : document.body.scrollTop;
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-scrolly |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关链接
----

* `window.scrollX`


Window.scrollbars - Web API 接口参考

Window.scrollbars
=================

### 概要

返回可以检查其可见性的滚动条对象。

### 语法
```

objRef = window.scrollbars
```

### 示例

下面的 HTML 示例展示了如何使用 window.scrollbars 对象的 visible 属性。
```

<!doctype html>
<html>
<head>
  <title>Various DOM Tests</title>
  <script>
    var visibleScrollbars = window.scrollbars.visible;
  </script>
</head>
<body>
  <p>Various DOM Tests</p>
</body>
</html>
```

### 规范

| Specification |
| --- |
| HTML Standard # dom-window-scrollbars-dev |

### 参见

* window.locationbar
* window.menubar
* window.personalbar
* window.statusbar
* window.toolbar


window.moveTo - Web API 接口参考

window.moveTo
=============

概述
--

将当前窗口移动到指定的坐标位置。

语法
--
```

window.moveTo(x, y)
```

### 参数

* `x` 是要移动到的位置横坐标
* `y` 是要移动到的位置纵坐标
示例
--

```js
function origin() {
  // 把窗口移动到左上角
  window.moveTo(0, 0);
}
```

附注
--

本函数按照指定的绝对位置移动当前窗口，而`window.moveBy`函数按照与当前位置相对的距离移动当前窗口。

从 Firefox 7 开始，如果符合下列情况,则普通网页中的 JavaScript 无法通过调用该函数来移动浏览器窗口

1. 当前窗口或标签页不是由`window.open`方法创建的
2. 当前标签页所在的窗口包含有多个标签页
规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-moveto |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

从 Firefox 7 开始，网站在以下情况下将不能再移动浏览器窗口。

1. 不能移动不是由 `Window.open()` 创建的窗口或标签页。
2. 当一个窗口里有多于一个标签页时，不能移动该窗口或其中的标签页。
参见
--

* `window.moveBy()`


Window：print() 方法 - Web API 接口参考

Window：print() 方法
=================

打开打印对话框，以打印当前文档。

如果调用此函数时文档仍在加载中，那么文档将在打开打印对话框之前完成加载。

当打印对话框打开时，此方法将阻塞。

语法
--

```js
print()
```

### 参数

无

### 返回值

无（`undefined`）。

规范
--

| Specification |
| --- |
| HTML Standard # printing |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

1. 打印
2. `beforeprint` 事件
3. `afterprint` 事件


onmessage - Web API 接口参考

onmessage
=========

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

**`message`** 事件是在窗口接受到消息（例如，从另一个浏览器上下文中调用 `Window.postMessage()`）时，在 `Window` 对象上触发的事件。

语法
--
```

window.addEventListener('message', function(event) { ... })
window.onmessage = function(event) { ... }
```

规范
--

| Specification |
| --- |
| HTML Standard # event-message |
| HTML Standard # handler-window-onmessage |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window：beforeprint 事件 - Web API 接口参考

Window：beforeprint 事件
=====================

当相关联的文档即将打印或关闭打印预览时，将触发 **`beforeprint`** 事件。

`afterprint` 和 `beforeprint` 事件允许页面在打印开始之前更改其内容（例如，也许是移除 banner）然后在打印完成后还原这些更改。一般来说，你应该更倾向于使用 `@media print` CSS at 规则，但在某些情况下可能有必要使用这些事件。

语法
--

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

```js
addEventListener("beforeprint", (event) => {});
onbeforeprint = (event) => {};
```

事件类型
----

一个通用的 `Event`。

示例
--

使用 `addEventListener()`：

```js
window.addEventListener("beforeprint", (event) => {
  console.log("打印前");
});
```

使用 `onbeforeprint` 事件处理属性：

```js
window.onbeforeprint = (event) => {
  console.log("打印前");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-beforeprint |
| HTML Standard # handler-window-onbeforeprint |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关事件：`afterprint`


window.find - Web API 接口参考

window.find
===========

**备注：** `window.find()` 可能会在未来版本的 Gecko 中被废弃。查看 Firefox bug 672395

### 概述

在一个页面中搜索指定的字符串。

### 语法
```

window.find(aString, aCaseSensitive, aBackwards, aWrapAround,
            aWholeWord, aSearchInFrames, aShowDialog);
```

`aString`

将要搜索的字符串

`aCaseSensitive`

布尔值，如果为`true`,表示搜索是区分大小写的。

`aBackwards`

布尔值。如果为`true`, 表示搜索方向为向上搜索。

`aWrapAround`

布尔值。如果为`true`, 表示为循环搜索。

`aWholeWord` 未实现

布尔值。如果为`true`,表示采用全字匹配搜索。该参数无效; 查看 Firefox bug 481513.

`aSearchInFrames`

布尔值。如果为`true`, 表示会搜索框架内的文本。

`aShowDialog`

布尔值。如果为`true`, 则会弹出一个搜索对话框。

### 返回值

`如果搜索到指定的字符串，则返回 true，否则`返回 false.

规范
--

不属于任何规范。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.console - Web API 接口参考

Window.console
==============

只读属性 **`Window.console`** 返回一个对`Console`对象的引用，Window.console 提供了向浏览器控制台输出日志信息的方法。这些方法仅应该用于调试，并不应该用来给最终用户呈现信息。

语法
--
```

var consoleObj = window.console;
```

示例
--

### 输出信息

第一个例子向控制台输出文字。

```js
console.log("An error occurred while loading the content");
```

下边这个例子向控制台打印一个对象，可以通过点击展开组件查看对象的各项属性。

```js
console.dir(someObject);
```

更多示例参考 `console` 文章中的示例部分。

规范
--

| Specification |
| --- |
| Console Standard  |

**备注：** 当前各种浏览器之间的实现还有很多差异，推动一致的工作也在进行当中。


Window：prompt() 方法 - Web API 接口参考

Window：prompt() 方法
==================

`window.prompt()` 指示浏览器显示一个对话框，其中有一个可选的信息，提示用户输入一些文本，并等待用户提交文本或取消对话框。

在某些情况下（例如，当用户切换标签时）浏览器可能不会实际显示一个对话框，或者不等待用户提交文本或取消对话框。

语法
--

```js
prompt()
prompt(message)
prompt(message, defaultValue)
```

### 参数

`message` 可选

向用户显示的一串文本。如果在提示窗口中没有什么可显示的，可以省略。

`defaultValue` 可选

一个字符串，包含文本输入字段中显示的默认值。

### 返回值

一个包含用户输入文本的字符串，或 `null`。

示例
--

```js
let sign = prompt("你是什么星座的？");

if (sign == "天蝎座") {
  alert("哇！我也是天蝎座的耶！");
}

// 有多种使用 prompt 方法的方式
sign = window.prompt(); // 打开空的提示窗口
sign = prompt(); // 打开空的提示窗口
sign = window.prompt("你觉得很幸运吗？"); // 打开显示提示文本为"你觉得很幸运吗？"的提示窗口
sign = window.prompt("你觉得很幸运吗？", "是的"); // 打开显示提示文本为"你觉得很幸运吗？"并且输入框默认值为"是的"的提示窗口
```

当用户点击“确定”按钮时，在输入框中输入的文本被返回。如果用户在没有输入任何文本的情况下点击确定，则返回一个空字符串。如果用户点击“取消”按钮，该函数返回 `null`。

以上提示框显示如下（在 macOS 的 Chrome 浏览器上）：

![macOS 上 Chrome 中的 prompt() 对话框](/zh-CN/docs/Web/API/Window/prompt/prompt.png)

注意事项
----

一个提示对话框包含一个单行文本框、一个取消按钮和一个确定按钮，并返回用户在该文本框中输入的（可能是空的）文本。

请注意，结果是一个字符串。这意味着你有时应该对用户给出的值进行转换。例如，如果他们的答案应该是一个数字，你应该把这个值转换为数字。

```js
const aNumber = Number(window.prompt("输入一个数字", ""));
```

对话框是模态窗口——它们阻止用户访问程序界面的其他部分，直到对话框被关闭。出于这个原因，你不应该过度使用任何创建对话框（或模态窗口）的函数。

另外，`<dialog>` 元素也可用于获取用户输入。

规范
--

| Specification |
| --- |
| HTML Standard # dom-prompt-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `<dialog>` 元素
* `alert`
* `confirm`


Window.event - Web API 接口参考

Window.event
============

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**`window.event`** 是一个由微软 IE 引入的属性，只有当 DOM 事件处理程序被调用的时候会被用到。它的值是当前正在处理的事件对象。

规范
--

没有任何规范。

微软在 MSDN 上有相关介绍。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

更多资料
----

* `Event.srcElement`


Window.top - Web API 接口参考

Window.top
==========

返回窗口层级最顶层窗口的引用。

语法
--
```

var topWindow = window.top;
```

备注
--

`window.parent` 返回当前窗口的直接父对象，而 `window.top` 返回最顶层的窗口对象。

当你在处理父窗口的子框架（subframe），而你想获取顶层框架时，这个属性相当有用。

规范
--

| Specification |
| --- |
| HTML Standard # dom-top-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


window.postMessage - Web API 接口参考

window.postMessage
==================

**window.postMessage()** 方法可以安全地实现跨源通信。通常，对于两个不同页面的脚本，只有当执行它们的页面位于具有相同的协议（通常为 https），端口号（443 为 https 的默认值），以及主机 (两个页面的模数 `Document.domain`设置为相同的值) 时，这两个脚本才能相互通信。**window.postMessage()** 方法提供了一种受控机制来规避此限制，只要正确的使用，这种方法就很安全。

从广义上讲，一个窗口可以获得对另一个窗口的引用（比如 `targetWindow = window.opener`），然后在窗口上调用 `targetWindow.postMessage()` 方法分发一个 `MessageEvent` 消息。接收消息的窗口可以根据需要自由处理此事件 (en-US)。传递给 window.postMessage() 的参数（比如 message）将通过消息事件对象暴露给接收消息的窗口。

语法
--
```

otherWindow.postMessage(message, targetOrigin, [transfer]);
```

`otherWindow`

其他窗口的一个引用，比如 iframe 的 contentWindow 属性、执行window.open返回的窗口对象、或者是命名过或数值索引的window.frames (en-US)。

`message`

将要发送到其他 window 的数据。它将会被结构化克隆算法 (en-US)序列化。这意味着你可以不受什么限制的将数据对象安全的传送给目标窗口而无需自己序列化。[1]

`targetOrigin`

通过窗口的 origin 属性来指定哪些窗口能接收到消息事件，其值可以是字符串"\*"（表示无限制）或者一个 URI。在发送消息的时候，如果目标窗口的协议、主机地址或端口这三者的任意一项不匹配 targetOrigin 提供的值，那么消息就不会被发送；只有三者完全匹配，消息才会被发送。这个机制用来控制消息可以发送到哪些窗口；例如，当用 postMessage 传送密码时，这个参数就显得尤为重要，必须保证它的值与这条包含密码的信息的预期接受者的 origin 属性完全一致，来防止密码被恶意的第三方截获。**如果你明确的知道消息应该发送到哪个窗口，那么请始终提供一个有确切值的 targetOrigin，而不是 \*。不提供确切的目标将导致数据泄露到任何对数据感兴趣的恶意站点。**

`transfer` 可选

是一串和 message 同时传递的 `Transferable` 对象。这些对象的所有权将被转移给消息的接收方，而发送一方将不再保有所有权。

The dispatched event
--------------------

执行如下代码，其他 window 可以监听分发的 message:

```js
window.addEventListener("message", receiveMessage, false);

function receiveMessage(event) {
  // For Chrome, the origin property is in the event.originalEvent
  // object.
  // 这里不准确，chrome 没有这个属性
  // var origin = event.origin || event.originalEvent.origin;
  var origin = event.origin;
  if (origin !== "http://example.org:8080") return;

  // ...
}
```

message 的属性有：

`data`

从其他 window 中传递过来的对象。

`origin`

调用 `postMessage` 时消息发送方窗口的 origin . 这个字符串由 协议、“://“、域名、“ : 端口号”拼接而成。例如“`https://example.org` (隐含端口 `443`)”、“`http://example.net` (隐含端口 `80`)”、“`http://example.com:8080`”。请注意，这个 origin 不能保证是该窗口的当前或未来 origin，因为 postMessage 被调用后可能被导航到不同的位置。

`source`

对发送消息的窗口对象的引用; 你可以使用此来在具有不同 origin 的两个窗口之间建立双向通信。

安全问题
----

**如果你不希望从其他网站接收 message，请不要为 message 事件添加任何事件侦听器。** 这是一个完全万无一失的方式来避免安全问题。

如果你确实希望从其他网站接收 message，请**始终使用 origin 和 source 属性验证发件人的身份**。任何窗口（包括例如 `http://evil.example.com`）都可以向任何其他窗口发送消息，并且你不能保证未知发件人不会发送恶意消息。但是，验证身份后，你仍然应该**始终验证接收到的消息的语法**。否则，你信任只发送受信任邮件的网站中的安全漏洞可能会在你的网站中打开跨网站脚本漏洞。

**当你使用 postMessage 将数据发送到其他窗口时，始终指定精确的目标 origin，而不是 \*。** 恶意网站可以在你不知情的情况下更改窗口的位置，因此它可以拦截使用 postMessage 发送的数据。

示例
--

```js
/\*
 \* A 窗口的域名是<http://example.com:8080>，以下是 A 窗口的 script 标签下的代码：
 \*/

var popup = window.open(...popup details...);

// 如果弹出框没有被阻止且加载完成

// 这行语句没有发送信息出去，即使假设当前页面没有改变 location（因为 targetOrigin 设置不对）
popup.postMessage("The user is 'bob' and the password is 'secret'",
                  "https://secure.example.net");

// 假设当前页面没有改变 location，这条语句会成功添加 message 到发送队列中去（targetOrigin 设置对了）
popup.postMessage("hello there!", "http://example.com");

function receiveMessage(event)
{
  // 我们能相信信息的发送者吗？(也许这个发送者和我们最初打开的不是同一个页面).
  if (event.origin !== "http://example.com")
    return;

  // event.source 是我们通过 window.open 打开的弹出页面 popup
  // event.data 是 popup 发送给当前页面的消息 "hi there yourself! the secret response is: rheeeeet!"
}
window.addEventListener("message", receiveMessage, false);
```

```js
/\*
 \* 弹出页 popup 域名是 http://example.com，以下是 script 标签中的代码：
 \*/

//当 A 页面 postMessage 被调用后，这个 function 被 addEventListener 调用
function receiveMessage(event) {
  // 我们能信任信息来源吗？
  if (event.origin !== "http://example.com:8080") return;

  // event.source 就当前弹出页的来源页面
  // event.data 是 "hello there!"

  // 假设你已经验证了所受到信息的 origin (任何时候你都应该这样做), 一个很方便的方式就是把 event.source
  // 作为回信的对象，并且把 event.origin 作为 targetOrigin
  event.source.postMessage(
    "hi there yourself! the secret response " + "is: rheeeeet!",
    event.origin,
  );
}

window.addEventListener("message", receiveMessage, false);
```

### 注意

任何窗口可以在任何其他窗口访问此方法，在任何时间，无论文档在窗口中的位置，向其发送消息。因此，用于接收消息的任何事件监听器**必须**首先使用 `origin` 和 `source` 属性来检查消息的发送者的身份。**无法检查 `origin` 和 `source` 属性会导致跨站点脚本攻击。**

与任何异步调度的脚本（超时，用户生成的事件）一样，postMessage 的调用者不可能检测到侦听由 postMessage 发送的事件的事件处理程序何时抛出异常。

分派事件的 origin 属性的值不受调用窗口中 document.domain 的当前值的影响。

仅对于 IDN 主机名，origin 属性的值不是始终为 Unicode 或 punycode; 在使用此属性时，如果你期望来自 IDN 网站的消息，则最大程度地兼容性检查 IDN 和 punycode 值。这个值最终将始终是 IDN，但现在你应该同时处理 IDN 和 punycode 表单。

当发送窗口包含 `javascript:` 或 `data:` URL 时，origin 属性的值是加载 URL 的脚本的

### 在扩展中使用 window.postMessage
非标准

`window.postMessage` 可用于以 chrome 代码运行的 JavaScript（例如，在扩展和特权代码中），但是分派事件的 source 属性总是为空作为安全限制。（其他属性具有其期望值。）发送到位于 chrome：URL 的窗口的消息的 `targetOrigin` 参数当前被错误解释，使得将导致发送消息的唯一值为 `"*"`。由于此值是不安全的，当目标窗口可以导航到其他地方的恶意网站，建议 postMessage 不用于与 chrome：页面的沟通; 使用不同的方法（如打开窗口时的查询字符串）与 chrome 窗口进行通信。最后，在文件中向页面发布消息：URL 当前要求 `targetOrigin` 参数为 `"*"`。`file://`不能用作安全限制; 这个限制可能会在将来被修改。

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-postmessage-options-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Document.domain`
* `CustomEvent`


Window.focus() - Web API 接口参考

Window.focus()
==============

概述
--

请求将窗口显示在前（靠近屏幕），这可能由于用户设置而失败，并且该窗口在方法返回之前不能保证会显示在最前。

语法
--

```js
focus()
```

示例
--

```js
if (clicked) {
  window.focus();
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-focus-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.screenLeft - Web API 接口参考

Window.screenLeft
=================

**`Window.screenLeft`** 是一个只读属性，它返回浏览器左边框到左边屏幕边缘的 CSS 像素数。

**备注：** `screenLeft` 只是 `Window.screenX` 属性的别名，最初只被 IE 浏览器所支持。现在主流的浏览器都已支持该属性。

值
-

返回浏览器窗口到屏幕左边缘的 CSS 像素距离数值。

示例
--

在 screenleft-screentop 项目中，展示了一个监听浏览器窗口位置变化，动态更新 canvas 的例子。在这个例子中，当你移动浏览器窗口位置，绘制在 canvas 上的圆也会对应移动。我们通过监听 `screenLeft`/`screenTop` 的变化，并使用 `Window.requestAnimationFrame()` 来对 canvas 实时重绘，保证了浏览器窗口移动时，canvas 内部圆的位置也会发生对应的移动。

```js
initialLeft = window.screenLeft + canvasElem.offsetLeft;
initialTop = window.screenTop + canvasElem.offsetTop;

function positionElem() {
  let newLeft = window.screenLeft + canvasElem.offsetLeft;
  let newTop = window.screenTop + canvasElem.offsetTop;

  let leftUpdate = initialLeft - newLeft;
  let topUpdate = initialTop - newTop;

  ctx.fillStyle = "rgb(0, 0, 0)";
  ctx.fillRect(0, 0, width, height);
  ctx.fillStyle = "rgb(0, 0, 255)";
  ctx.beginPath();
  ctx.arc(
    leftUpdate + width / 2,
    topUpdate + height / 2 + 35,
    50,
    degToRad(0),
    degToRad(360),
    false,
  );
  ctx.fill();

  pElem.textContent =
    "Window.screenLeft: " +
    window.screenLeft +
    ", Window.screenTop: " +
    window.screenTop;

  window.requestAnimationFrame(positionElem);
}

window.requestAnimationFrame(positionElem);
```

如果浏览器不支持 `screenLeft` 属性，我们还在代码中使用了一个 polyfill 来保证演示效果。通过设置 `Window.screenX`/`Window.screenY` 为对应别名来实现一样的功能。

```js
if (!window.screenLeft) {
  window.screenLeft = window.screenX;
  window.screenTop = window.screenY;
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-screenleft |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参考
--

* `window.screenTop`
* `Window.screenX`


Window.self - Web API 接口参考

Window.self
===========

概述
--

返回一个指向当前 window 对象的引用。

语法
--
```

objRef = window.self
```

示例
--
```

 if (window.parent.frames[0] != window.self) {
    // 当前对象不是 frames 列表中的第一个时
 }
```

备注
--

**window.self** 几乎总是用于上面示例那样的比较，用来判断当前 window 是不是父 frameset 中的第一个 frame。

规范
--

HTML5


Window：showOpenFilePicker() 方法 - Web API 接口参考

Window：showOpenFilePicker() 方法
==============================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Window` 接口的 **`showOpenFilePicker()`** 方法用于显示一个文件选择器，以允许用户选择一个或多个文件并返回这些文件的句柄。

语法
--

```js
showOpenFilePicker()
```

### 参数

`options` 可选

选项对象，包含以下属性：

`multiple`

布尔值，默认为 `false`。设为 `true` 时允许用户选择多个文件。

`excludeAcceptAllOption`

布尔值，默认为 `false`。默认情况下，文件选择器带有一个允许用户选择所有类型文件的过滤选项（展开于文件类型选项中）。设置此选项为 `true` 以使该过滤选项不可用。

`types`

表示允许选择的文件类型的 `Array` 数组，其中的元素为包含以下选项的对象：

`description`

可选，对此允许文件类型集合的描述。

`accept`

`Object` 对象，带有键名为 MIME 类型、键值为包含文件扩展名的 `Array` 数组的键值对（参考下方的示例）。

### 返回值

一个 `Promise` 对象，会兑现一个包含 `FileSystemFileHandle` 对象的 `Array` 数组。

### 异常

`AbortError`

当用户直接关闭了文件选择器或选择的文件是不宜暴露给网站的敏感文件时将会抛出 AbortError。

安全性
---

要求发生临时性用户活动 (en-US)。用户必须与页面或 UI 元素进行交互才能使该特性正常运行。

示例
--

在此处我们设置一个用于传递给方法的选项对象。我们将允许选择图片类型、不允许使用所有类型，也不能选择多个文件。

```js
const pickerOpts = {
  types: [
    {
      description: "Images",
      accept: {
        "image/\*": [".png", ".gif", ".jpeg", ".jpg"],
      },
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false,
};
```

接下来我们创建一个异步函数来显示文件选择器并返回选择的文件。

```js
// 创建用于存放文件句柄的变量。
let fileHandle;

async function getFile() {
  // 打开文件选择器，解构返回的数组中的第一个元素
  [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // 操作 fileHandle 的后续代码
}
```

规范
--

| Specification |
| --- |
| File System Access # api-showopenfilepicker |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 文件系统 API
* 文件系统访问 API：简化对本地文件的访问


Window.menubar - Web API 接口参考

Window.menubar
==============

概要
--

返回一个可以检测 visibility 属性的 `menubar` 对象。

语法
--
```

objRef = window.menubar
```

示例
--

以下完整的 HTML 示例显示了使用 locationbar 对象的 visible 属性的方式。

```html
<html>
  <head>
    <title>Various DOM Tests</title>
    <script>
 var visible = window.menubar.visible;
 </script>
  </head>
  <body>
    <p>Various DOM Tests</p>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-menubar-dev |

相关链接：
-----

window.locationbar, window.personalbar, window.scrollbars, window.statusbar, window.toolbar


Window.scrollMaxY - Web API 接口参考

Window.scrollMaxY
=================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

只读属性 **`Window.scrollMaxY`** 返回`document`可以纵向滚动的最大像素数目

语法
--
```

yMax = window.scrollMaxY
```

* `yMax` 是像素数。
例子
--

```js
// 滚动到页面的底部
let maxY = window.scrollMaxY;

window.scrollTo(0, maxY);
```

备注
--

不要用 `window.innerHeight` + window.scrollMaxY 来计算 document 的总高度，因为 `window.innerHeight` 也包括了可见的水平滚动条的高度。正确的做法是使用 `document.body.scrollHeight` 。

参见`window.scrollMaxX` 和 `window.scrollTo` 。

规范
--

这不属于任何规范中的一部分。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


pageshow - Web API 接口参考

pageshow
========

当一条会话历史记录被执行的时候将会触发页面显示 (pageshow) 事件。(这包括了后退/前进按钮操作，同时也会在 onload 事件触发后初始化页面时触发)

基本信息
----

规范

HTML5

接口

PageTransitionEvent

事件冒泡

No

事件取消

No

事件源

Document (dispatched on Window)

默认操作

None

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` 只读  | `DOMString` | The type of event. |
| `bubbles` 只读  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` 只读  | `Boolean` | Whether the event is cancellable or not. |
| `persisted` 只读  | `boolean` | 表示网页是否是来自缓存。 |

示例
--

以下示例将会在控制台打印由前进/后退按钮以及 load 事件触发后引起的 pageshow 事件：
```

window.addEventListener('pageshow', function(event) {
    console.log('after , pageshow :',event);
});

window.addEventListener('load', function() {
    console.log('before');
});
```

不规范的写法，你同样可以将这个事件当做一个属性添加到 body 标签，类似于 onload
```

<body onload="myonload()" onpageshow="mypageshowcode()">
```

规范
--

| Specification |
| --- |
| HTML Standard # event-pageshow |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关事件
----

* `pagehide` (en-US)
* Using Firefox 1.5 caching — pageshow event (en-US)


unhandledrejection - Web API 接口参考

unhandledrejection
==================

当 `Promise` 被 reject 且没有 reject 处理器的时候，会触发 **`unhandledrejection`** 事件；这可能发生在 `window` 下，但也可能发生在 `Worker` 中。这对于调试和为意外情况提供后备错误处理非常有用。

|  |  |
| --- | --- |
| 是否冒泡 | No |
| 是否可取消 | Yes |
| 接口 | `PromiseRejectionEvent` |
| 事件处理器属性 | `onunhandledrejection` (en-US) |

事件属性
----

`unhandledrejection` 继承自 `PromiseRejectionEvent`，而 `PromiseRejectionEvent` 又继承自 `Event`。因此`unhandledrejection` 含有 `PromiseRejectionEvent` 和 `Event` 的属性和方法。主要包含两个有用的属性：

`promise`

特定的被 reject 且没有 reject 处理器的 `Promise`

`reason`

将会传入异常处理方法中的错误原因（如果存在），查看 `catch()` 相关以获取更多细节。

使用说明
----

允许 `unhandlejection` 事件冒泡将最终导致向控制台输出错误消息。可以通过调用 `PromiseRejectionEvent` 上的 `preventDefault()` 来阻止这种情况；请参阅下面的阻止默认处理示例。

例子
--

我们将通过几个例子来展示 `unhandledrejection` 事件的使用方式。

### 基本的异常上报

此示例只是将有关未处理的 Promise rejection 信息打印到控制台。

```js
window.addEventListener("unhandledrejection", (event) => {
  console.warn(`UNHANDLED PROMISE REJECTION: ${event.reason}`);
});
```

你还可以使用 `onunhandledrejection` (en-US) 事件处理程序属性来设置事件侦听器：

```js
window.onunhandledrejection = (event) => {
  console.warn(`UNHANDLED PROMISE REJECTION: ${event.reason}`);
};
```

### 阻止默认处理

许多环境 (例如 Node.js ) 默认情况下会向控制台打印未处理的 Promise rejections。你可以通过为 `unhandledrejection` 事件添加一个处理程序来避免这种情况的发生，该处理程序除了执行你希望执行的任何其他任务之外，还可以调用 `preventDefault()` 来取消该事件，从而阻止该事件冒泡并由运行时的日志代码处理。这种方法之所以有效，是因为 `unhandledrejection` 事件是可以取消的。

```js
window.addEventListener("unhandledrejection", function (event) {
  // ...你的代码可以处理未处理的 rejection...

  // 阻止默认处理（例如将错误输出到控制台）

  event.preventDefault();
});
```

规范
--

| Specification |
| --- |
| HTML Standard # event-unhandledrejection |
| HTML Standard # handler-window-onunhandledrejection |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Promise 拒绝事件
* `rejectionhandled` 事件
* `Promise` (en-US)


Window.back() - Web API 接口参考

Window.back()
=============

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

总结
--

跳转窗口到 history 中的前一个地址，这曾是 Gecko 的方法。请使用标准的 history.back 替代它。

Syntax
------
```

window.back()
```

Example
-------

```js
function goBack() {
  if (canGoBack) window.back();
}
```


orientationchange - Web API 接口参考

orientationchange
=================

`orientationchange`事件在设备的纵横方向改变时触发。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `Event` |
| Event handler | `onorientationchange` |

示例
--

你可以在`addEventListener` 方法中使用 `orientationchange` 事件：

```js
window.addEventListener("orientationchange", function () {
  console.log(
    "the orientation of the device is now " + screen.orientation.angle,
  );
});
```

或者使用 `onorientationchange` 事件处理程序属性：

```js
window.onorientationchange = function () {
  console.log(
    "the orientation of the device is now " + screen.orientation.angle,
  );
};
```

规范
--

| Specification |
| --- |
| Compatibility Standard # event-orientationchange |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.matchMedia() - Web API 接口参考

Window.matchMedia()
===================

`Window` 的 **`matchMedia()`** 方法返回一个新的 `MediaQueryList` 对象，表示指定的媒体查询 (en-US)字符串解析后的结果。返回的 `MediaQueryList` 可被用于判定 `Document` 是否匹配媒体查询，或者监控一个 `document` 来判定它匹配了或者停止匹配了此媒体查询。

语法
--
```

mqList = window.matchMedia(mediaQueryString)
```

### 参数

`mediaQueryString`

一个被用于媒体查询解析的字符串。

### 返回值

一个用来媒体查询的新的`MediaQueryList`对象

使用说明
----

你可以使用返回的媒体查询来执行即时检查和事件驱动检查，以查看文档是否与媒体查询匹配。

要执行一次瞬时检查以查看文档是否与媒体查询匹配，请查看`matches`属性的值，当 document 满足媒体查询条件的时候将会返回`true`。

如果你需要始终了解 document 是否与媒体查询匹配，则可以查看将要传递给对象的`change` 事件。`Window.devicePixelRatio`上的文章中有一个很好的例子。

示例
--

此示例运行媒体查询`(max-width: 600px)`并在`<span>`;中显示`MediaQueryList`的`matches`属性值。如果视口的宽度小于或等于 600 像素，则输出将为 true，而如果窗口的宽度大于此宽度，则将输出 false。

### JavaScript
```

let mql = window.matchMedia('(max-width: 600px)');

document.querySelector(".mq-value").innerText = mql.matches;
```

JavaScript 代码只需将要匹配的媒体查询字符串传递到`matchMedia()`进行编译，然后设置`<span>`的`innerText`为`matches` (en-US)属性结果的值，以便它表明此 document 在此刻页面加载完成时是否与媒体查询所匹配。

### HTML

```html
<span class="mq-value"></span>
```

一个简单的 `<span>` 来接收输出。
```

.mq-value {
  font:
    18px arial,
    sans-serif;
  font-weight: bold;
  color: #88f;
  padding: 0.4em;
  border: 1px solid #dde;
}
```

### 结果

参考更多的例子来 通过代码使用媒体查询 (en-US) 。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-matchmedia |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 媒体查询 (en-US)
* 通过代码使用媒体查询 (en-US)
* `MediaQueryList`
* `MediaQueryListListener` (en-US)


targetElement - Web API 接口参考

targetElement
=============

**`SVGAnimationElement.targetElement`** 属性是指完成动画的元素。如果没有目标元素在执行动画（例如：因为 `href (en-US)` 属性指定了一个未知的元素），这个值将返回 `null`。

语法
--
```

var targetElement = someElement.targetElement;
```

规范
--

| Specification |
| --- |
| SVG Animations Level 2 # \_\_svg\_\_SVGAnimationElement\_\_targetElement |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


全屏指南 - Web API 接口参考

全屏指南
====

本文主要说明如何使用全屏 API 将给定元素设置为全屏模式，以及如何检测浏览器何时进入或退出全屏模式。

激活全屏模式
------

对于一个你想要以全屏模式展示的元素（例如 `<video>`），你通过调用它的 `Element.requestFullscreen()` 方法就能简单地激活它的全屏模式。

我们来看看 `<video>` 这个元素：

```html
<video controls id="myvideo">
  <source src="somevideo.webm"></source>
  <source src="somevideo.mp4"></source>
</video>
```

我们可以用下面的代码让视频进入全屏模式：

```js
var elem = document.getElementById("myvideo");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}
```

这段代码会在调用 `requestFullscreen()` 方法之前先检验它是否存在。

### 显示差异

值得留意的是，目前 Gecko 和 WebKit 的实现之间的关键差异：Gecko 自动为元素添加了 CSS 规则，使其拉伸以填满屏幕： "`width: 100%; height: 100%`"。WebKit 没有这样做，相反地，它将全屏元素居中，不改变大小，而屏幕的其他部分为黑色。为了在 Webkit 中获得相同的全屏行为，你需要自行为元素添加 CSS "`width: 100%; height: 100%;`"：

```css
#myvideo:-webkit-full-screen {
  width: 100%;
  height: 100%;
}
```

另一方面，如果你尝试在在 Gecko 上模拟 WebKit 的行为，你需要把你想要呈现的元素放在另一个实际调整为全屏幕的元素中，并使用 CSS 规则调整内部的元素，从而达到你想要的样式。

### 通知

当成功进入全屏模式时，包含该元素的文档会收到一个 `fullscreenchange` 事件。当退出全屏模式时，文档会再一次收到 `fullscreenchange` 事件。注意此 `fullscreenchange` 事件，不管在文档进入和退出全屏模式时，都不会提供任何信息，但如果文档的 `fullscreenElement` 为非空（`null`），即处于全屏模式中。

### 当全屏请求失败时

你并不总是可以进入全屏模式。例如 `<iframe>` 元素具有 `allowfullscreen` 属性，可选择是否将其内容以全屏模式显示。另外，几种特定的内容，比如窗体插件（windowed plug-ins），不能以全屏模式显示。尝试将不能以全屏模式显示的元素（或者此元素的父元素和后代元素）的时候，全屏请求是无效的。而相应元素会收到一个 `mozfullscreenerror` 事件。当全屏请求失败时，Firefox 会在 Web 控制台上打一条错误信息解释请求为什么失败。但是在 Chrome 和新版的 Opera 中，不会生成这样的警告。

**备注：** 全屏请求必须在事件处理函数中调用，否则将会被拒绝。

退出全屏模式
------

用户总是可以自行退出全屏模式；详见 Things your users want to know。你也可以以编程方式通过调用 `Document.exitFullscreen()` 方法来做到这点。

其他信息
----

`Document` 提供了一些额外的信息，在开发全屏网络应用时会很有用：

`DocumentOrShadowRoot.fullscreenElement`

`fullscreenElement` 属性可以告诉你当前以全屏模式显示的元素 `Element` 。若此项非空，文档处于全屏模式中，否则不在。

`Document.fullscreenEnabled`

`fullscreenEnabled` 属性可以告诉你文档当前是否为允许请求进入全屏幕模式的状态。

你的用户想了解的信息
----------

你可能想确保使你的用户得知他可以按 `ESC` 键 (或 `F11`) 退出全屏模式。

此外，当处在全屏模式中，浏览其他页面、切换标签页、或者切换到其他应用 (例如使用 `Alt`-`Tab`) 也会导致退出全屏模式。

示例
--

在这个例子中，网页中显示了一个视频。按下 `Return` 或 `Enter` 键让用户在视频的窗口显示和全屏显示之间切换。

View Live Examples

### 监听 `Enter` 键

当页面加载完成时，这段代码可以设置一个事件监听器以监听 `Enter` 键。

```js
document.addEventListener(
  "keydown",
  function (e) {
    if (e.keyCode == 13) {
      toggleFullScreen();
    }
  },
  false,
);
```

### 切换全屏模式

当用户按下 `Enter` 键时，这段代码会被调用，像上面示例看到的那样。

```js
function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}
```

这段代码首先检查 `document` 的`fullscreenElement` 属性的值（亦要检查带有前缀 `moz`、`ms`、`webkit`）。如果其为 `null`，文档当前处于窗口模式中，所以我们需要切换到全屏模式。通过调用`element.requestFullscreen()`，可以切换到全屏模式。

如果全屏模式已经激活 (`fullscreenElement` 不为 `null`)，我们可以调用 `document.exitFullscreen()`（或其前缀化的版本，这取决于你使用的浏览器）。

前缀
--

**备注：** 现在，只有 Firefox 64 和 Chrome 71 支持无前缀。

目前并不是所有的浏览器都实现了 API 的无前缀版本（你可以使用 Fscreen 获取跨浏览器全屏 API），这里有一份表格总结了前缀和它们之间的命名区别：

| Standard | WebKit (Safari) / Blink (Chrome & Opera) / Edge | Gecko (Firefox) | Internet Explorer |
| --- | --- | --- | --- |
| `Document.fullscreen`
已弃用
 | `webkitIsFullScreen` | `mozFullScreen` | - |
| `Document.fullscreenEnabled` | `webkitFullscreenEnabled` | `mozFullScreenEnabled` | `msFullscreenEnabled` |
| `DocumentOrShadowRoot.fullscreenElement` | `webkitFullscreenElement` | `mozFullScreenElement` | `msFullscreenElement` |
| `Document.onfullscreenchange` | `onwebkitfullscreenchange` | `onmozfullscreenchange` | `onMSFullscreenChange` |
| `Document.onfullscreenerror` | `onwebkitfullscreenerror` | `onmozfullscreenerror` | `onMSFullscreenError` |
| `Document.exitFullscreen()` | `webkitExitFullscreen()` | `mozCancelFullScreen()` | `msExitFullscreen()` |
| `Element.requestFullscreen()` | `webkitRequestFullscreen()` | `mozRequestFullScreen()` | `msRequestFullscreen()` |

规范
--

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # dom-document-fullscreen |

浏览器兼容性
------

### api.Document.fullscreenEnabled

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.fullscreen

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

扩展链接
----

* 全屏 API
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`, `::backdrop`
* `allowfullscreen`


HTMLSlotElement.name - Web API 接口参考

HTMLSlotElement.name
====================

元素`HTMLSlotElement`的**name**属性，可以获取和设置属性值。插槽提供了 web 组件的摆放位置，辅助用户布局。

语法
--
```

var name = htmlSlotElement.name
htmlSlotElement.name = name
```

### 值

一个 `DOMString`.

例子
--

下面的片段来自 slotchange example (see it live also).

```js
let slots = this.shadowRoot.querySelectorAll("slot");
slots[1].addEventListener("slotchange", function (e) {
  let nodes = slots[1].assignedNodes();
  console.log(
    'Element in Slot "' +
      slots[1].name +
      '" changed to "' +
      nodes[0].outerHTML +
      '".',
  );
});
```

这里我们获取所有插槽的引用，然后给模板里的第二个插槽增加事件— 跟踪内容变化。

每当附加在插槽中的内容变化，我们都记录插槽相关的内容。

规范
--

| Specification |
| --- |
| HTML Standard # dom-slot-name-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Position.coords - Web API 接口参考

Position.coords
===============

**`Position.coords`** 是一个`Coordinates` 对象的只读属性 , 表示地理状态：它包括位置，地球上的经度和纬度，相关的海拔和速度，可以重新组合内部返回的这些值，它还包含有关这些值的准确信息。

语法
--
```

coord = position.coords
```

规范
--

| Specification |
| --- |
| Geolocation API # coords-attribute |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Using geolocation
* The `Position` interface it belongs to.


Encoding API 编码 - Web API 接口参考

Encoding API 编码
===============

`TextDecoder` 和 `TextDecoderStream` 构造函数可以传递一个可选的 `label`，表示使用的编码。默认是 `UTF-8`。

以下表格列出了用户代理一定支持的所有编码的名称和 label，这是在编码规范中定义的。这些编码通常适用于需要使用字符编码的任何地方。

| Label | 编码 |
| --- | --- |
| "`unicode-1-1-utf-8`"、"`utf-8`"、"`utf8`" | `'utf-8'` |
| "`866`"、"`cp866`"、"`csibm866`"、"`ibm866`" | `'ibm866'` |
| "`csisolatin2`"、"`iso-8859-2`"、"`iso-ir-101`"、"`iso8859-2`"、"`iso88592`"、"`iso_8859-2`"、"`iso_8859-2:1987`"、"`l2`"、"`latin2`" | `'iso-8859-2'` |
| "`csisolatin3`"、"`iso-8859-3`"、"`iso-ir-109`"、"`iso8859-3`"、"`iso88593`"、"`iso_8859-3`"、"`iso_8859-3:1988`"、"`l3`"、"`latin3`" | `'iso-8859-3'` |
| "`csisolatin4`"、"`iso-8859-4`"、"`iso-ir-110`"、"`iso8859-4`"、"`iso88594`"、"`iso_8859-4`"、"`iso_8859-4:1988`"、"`l4`"、"`latin4`" | `'iso-8859-4'` |
| "`csisolatincyrillic`"、"`cyrillic`"、"`iso-8859-5`"、"`iso-ir-144`"、"`iso88595`"、"`iso_8859-5`"、"`iso_8859-5:1988`" | `'iso-8859-5'` |
| "`arabic`"、"`asmo-708`"、"`csiso88596e`"、"`csiso88596i`"、"`csisolatinarabic`"、"`ecma-114`"、"`iso-8859-6`"、"`iso-8859-6-e`"、"`iso-8859-6-i`"、"`iso-ir-127`"、"`iso8859-6`"、"`iso88596`"、"`iso_8859-6`"、"`iso_8859-6:1987`" | `'iso-8859-6'` |
| "`csisolatingreek`"、"`ecma-118`"、"`elot_928`"、"`greek`"、"`greek8`"、"`iso-8859-7`"、"`iso-ir-126`"、"`iso8859-7`"、"`iso88597`"、"`iso_8859-7`"、"`iso_8859-7:1987`"、"`sun_eu_greek`" | `'iso-8859-7'` |
| "`csiso88598e`"、"`csisolatinhebrew`"、"`hebrew`"、"`iso-8859-8`"、"`iso-8859-8-e`"、"`iso-ir-138`"、"`iso8859-8`"、"`iso88598`"、"`iso_8859-8`"、"`iso_8859-8:1988`"、"`visual`" | `'iso-8859-8'` |
| "`csiso88598i`"、"`iso-8859-8-i`"、"`logical`" | `'iso-8859-8i'` |
| "`csisolatin6`"、"`iso-8859-10`"、"`iso-ir-157`"、"`iso8859-10`"、"`iso885910`"、"`l6`"、"`latin6`" | `'iso-8859-10'` |
| "`iso-8859-13`"、"`iso8859-13`"、"`iso885913`" | `'iso-8859-13'` |
| "`iso-8859-14`"、"`iso8859-14`"、"`iso885914`" | `'iso-8859-14'` |
| "`csisolatin9`"、"`iso-8859-15`"、"`iso8859-15`"、"`iso885915`"、"`l9`"、"`latin9`" | `'iso-8859-15'` |
| "`iso-8859-16`" | `'iso-8859-16'` |
| "`cskoi8r`"、"`koi`"、"`koi8`"、"`koi8-r`"、"`koi8_r`" | `'koi8-r'` |
| "`koi8-u`" | `'koi8-u'` |
| "`csmacintosh`"、"`mac`"、"`macintosh`"、"`x-mac-roman`" | `'macintosh'` |
| "`dos-874`"、"`iso-8859-11`"、"`iso8859-11`"、"`iso885911`"、"`tis-620`"、"`windows-874`" | `'windows-874'` |
| "`cp1250`"、"`windows-1250`"、"`x-cp1250`" | `'windows-1250'` |
| "`cp1251`"、"`windows-1251`"、"`x-cp1251`" | `'windows-1251'` |
| "`ansi_x3.4-1968`"、"`ascii`"、"`cp1252`"、"`cp819`"、"`csisolatin1`"、"`ibm819`"、"`iso-8859-1`"、"`iso-ir-100`"、"`iso8859-1`"、"`iso88591`"、"`iso_8859-1`"、"`iso_8859-1:1987`"、"`l1`"、"`latin1`"、"`us-ascii`"、"`windows-1252`"、"`x-cp1252`" | `'windows-1252'` |
| "`cp1253`"、"`windows-1253`"、"`x-cp1253`" | `'windows-1253'` |
| "`cp1254`"、"`csisolatin5`"、"`iso-8859-9`"、"`iso-ir-148`"、"`iso8859-9`"、"`iso88599`"、"`iso_8859-9`"、"`iso_8859-9:1989`"、"`l5`"、"`latin5`"、"`windows-1254`"、"`x-cp1254`" | `'windows-1254'` |
| "`cp1255`"、"`windows-1255`"、"`x-cp1255`" | `'windows-1255'` |
| "`cp1256`"、"`windows-1256`"、"`x-cp1256`" | `'windows-1256'` |
| "`cp1257`"、"`windows-1257`"、"`x-cp1257`" | `'windows-1257'` |
| "`cp1258`"、"`windows-1258`"、"`x-cp1258`" | `'windows-1258'` |
| "`x-mac-cyrillic`"、"`x-mac-ukrainian`" | `'x-mac-cyrillic'` |
| "`chinese`"、"`csgb2312`"、"`csiso58gb231280`"、"`gb2312`"、"`gb_2312`"、"`gb_2312-80`"、"`gbk`"、"`iso-ir-58`"、"`x-gbk`" | `'gbk'` |
| "`gb18030`" | `'gb18030'` |
| "`hz-gb-2312`" | `'hz-gb-2312'` |
| "`big5`"、"`big5-hkscs`"、"`cn-big5`"、"`csbig5`"、"`x-x-big5`" | `'big5'` |
| "`cseucpkdfmtjapanese`"、"`euc-jp`"、"`x-euc-jp`" | `'euc-jp'` |
| "`csiso2022jp`"、"`iso-2022-jp`" | `'iso-2022-jp'` |
| "`csshiftjis`"、"`ms_kanji`"、"`shift-jis`"、"`shift_jis`"、"`sjis`"、"`windows-31j`"、"`x-sjis`" | `'shift-jis'` |
| "`cseuckr`"、"`csksc56011987`"、"`euc-kr`"、"`iso-ir-149`"、"`korean`"、"`ks_c_5601-1987`"、"`ks_c_5601-1989`"、"`ksc5601`"、"`ksc_5601`"、"`windows-949`" | `'euc-kr'` |
| "`csiso2022kr`"、"`iso-2022-kr`" | `'iso-2022-kr'` |
| "`utf-16be`" | `'utf-16be'` |
| "`utf-16`"、"`utf-16le`" | `'utf-16le'` |
| "`x-user-defined`" | `'x-user-defined'` |
| "`iso-2022-cn`"、"`iso-2022-cn-ext`" | `'replacement'` |


SVGPathElement.getTotalLength() - Web API 接口参考

SVGPathElement.getTotalLength()
===============================

**`SVGPathElement.getTotalLength()`** 该方法返回用户代理对路径总长度（以用户单位为单位）的计算值。

**备注：** 在 SVG 2 中，该方法被移动到 `SVGGeometryElement` (en-US) 接口，由 `SVGPathElement` (en-US) 继承。

语法
--

```js
getTotalLength();
```

### 返回值

指示路径总长度（以用户单位为单位）的浮点数。

规范
--

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGGeometryElement\_\_getTotalLength |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `SVGGeometryElement.getTotalLength()`


Using the Web Animations API - Web API 接口参考

Using the Web Animations API
============================

web 动画 API 可以让我们用 JavaScript 写动画并且控制动画。本文将通过有趣的 demo 和教学，以有趣的方式开启你对这片爱丽丝仙境的探索。

认识 Web 动画 API
-------------

Web 动画 API将浏览器动画引擎向开发者打开，并由 JavaScript 进行操作。这些 API 被设计成 CSS Animations and CSS Transitions的接口，未来会对这些 API 做补充以丰富更多的功能。它是对网络上动画化的支持最有效的方式之一，让浏览器进行自己的内部，不需要 hacks，或者强迫，或者`Window.requestAnimationFrame()`。

通过 Web 动画 API，我们可以将交互式动画从样式表移动到 JavaScript，将表现与行为分开。我们不再需要依赖 DOM 重的技术，如将 CSS 属性和范围类写入元素来控制播放方向。与纯粹的声明式 CSS 不同，JavaScript 还允许我们动态地将属性值设置为持续时间。对于构建自定义动画库和创建交互式动画，Web 动画 API 可能是完成工作的完美工具。让我们看看它能做什么！

浏览器兼容情况
-------

默认情况下，Firefox 48+ 和 Chrome 36+ 中提供了本文中讨论的基本 Web 动画 API 功能。Webkit 和 Edge 已经将 API 移动到各自的待办事项列表中，但是直到我们看到所有浏览器都有完整的支持，所以有一个便于维护的 polyfill（ handy maintained polyfill）可以测试功能支持，并在必要时添加它。

用 web 动画 API 写 css 动画
---------------------

学习 Web 动画 API 的更为熟悉的方法之一是从大多数网络开发人员开始使用以前的 CSS 动画。CSS 动画有一个熟悉的语法，很好地分解为演示目的。

### The CSS version

这是一个用 CSS 写的滚动动画，显示爱丽丝落下通向仙境的兔子洞 (see the full code on Codepen):

![Alice Tumbling down the rabbit's hole.](/zh-CN/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API/tumbling-alice_optimized.gif)

请注意背景的移动，爱丽丝的旋转，以及她的颜色偏移变化。本教程我们将仅仅关注爱丽丝。这是控制爱丽丝动画的简化的 CSS：

```css
#alice {
  animation: aliceTumbling infinite 3s linear;
}

@keyframes aliceTumbling {
  0% {
    color: #000;
    transform: rotate(0) translate3D(-50%, -50%, 0);
  }
  30% {
    color: #431236;
  }
  100% {
    color: #000;
    transform: rotate(360deg) translate3D(-50%, -50%, 0);
  }
}
```

这样可以以恒定的（线性 linear）速率在 3 秒内改变爱丽丝的颜色和变换的旋转，并无限循环。在 @keyframes 块中，我们可以看到每个循环（约 0.9 秒）的 30％，Alice 的颜色从黑色变为深红色，然后在循环结束时再次返回。

### Moving it to JavaScript

现在让我们尝试使用 Web 动画 API 创建相同的动画。

#### Representing keyframes

我们首先要做的是创建一个对应于我们的 CSS @keyframes 块的关键帧对象：

```js
var aliceTumbling = [
  { transform: "rotate(0) translate3D(-50%, -50%, 0)", color: "#000" },
  { color: "#431236", offset: 0.3 },
  { transform: "rotate(360deg) translate3D(-50%, -50%, 0)", color: "#000" },
];
```

这里我们使用一个包含多个对象的数组。每个对象代表原始 CSS 中的一个键。然而，与 CSS 不同，Web 动画 API 不需要明确地告知每个键出现的动画的百分比。它将根据你给出的按键数量自动将动画划分为相等的部分。这意味着具有三个键的关键帧对象将通过动画的每个循环的方式播放中间键，除非另有说明。

当我们想要明确地设置一个键与其他键的偏移量时，我们可以直接在对象中指定一个偏移量，并与逗号分隔。在上面的例子中，为了确保爱丽丝的颜色变化为 30％而不是 50％，我们给它的偏移量为 0.3。

必须至少指定两个关键帧（表示动画序列的开始和结束状态）.如果你的关键帧列表只有一个条目，`Element.animate()` 将抛出不支持的异常报错。

所以要回顾一下，除非你指定一个键上的偏移量，否则键的默认值是等间隔的。方便吗？

#### 表示时间属性

我们还需要创建一个定时属性的对象 (an `AnimationEffectTimingProperties` (en-US) object) 对应于爱丽丝动画中的值：

```js
var aliceTiming = {
  duration: 3000,
  iterations: Infinity,
};
```

你会注意到这里有一些差异，如何在 CSS 中表示等价的值：

* 一个，持续时间是毫秒，而不是秒 - 3000 不是 3 秒.。像`WindowTimers.setTimeout()` (en-US) 和`Window.requestAnimationFrame()`, Web 动画 API 只支持毫秒。
* The other thing you'll notice is that it's `iterations`, not `iteration-count`.

**备注：** CSS 动画中使用的属性值与 Web 动画中使用的属性值存在一些小的差异。比如，Web 动画中不能使用字符串“infinite”，而是使用 Javascript 的关键字 Infinity。以及我们用 `easing` 来代替`timing-function`。我们不必在这列出`easing`的值，因为不像在 CSS 动画里，默认的"animation-timing-function"是`ease`。页面动画 API 的默认 easing 是`linear`— 而这就是我们想要的。

#### 整合这些特性

是时候把这些特性结合到一起运用了 `Element.animate()` :

```js
document.getElementById("alice").animate(aliceTumbling, aliceTiming);
```

And boom: the animation starts playing (see the finished version on Codepen).

可以在可以使用 CSS 动画化的任何 DOM 元素上调用 animate() 方法。它可以用几种方式写成。我们可以直接像这样传递他们的值，而不需要为关键帧和时间属性创建对象：

```js
document.getElementById("alice").animate(
  [
    { transform: "rotate(0) translate3D(-50%, -50%, 0)", color: "#000" },
    { color: "#431236", offset: 0.3 },
    { transform: "rotate(360deg) translate3D(-50%, -50%, 0)", color: "#000" },
  ],
  {
    duration: 3000,
    iterations: Infinity,
  },
);
```

更重要的是，如果我们只想指定动画的持续时间，而不是其迭代（默认动画迭代一次），我们可以单独传递毫秒：

```js
document.getElementById("alice").animate(
  [
    { transform: "rotate(0) translate3D(-50%, -50%, 0)", color: "#000" },
    { color: "#431236", offset: 0.3 },
    { transform: "rotate(360deg) translate3D(-50%, -50%, 0)", color: "#000" },
  ],
  3000,
);
```

使用 play()，pause()，reverse() 和 playbackRate 控制播放
-----------------------------------------------

虽然我们可以使用 Web 动画 API 编写 CSS 动画，其中 API 真正派上用场的是操纵动画的播放。Web 动画 API 提供了一些控制播放的有用方法。让我们来看看在 Growing / Shrinking Alice 游戏中暂停和播放动画（请查看 Codepen 的完整代码 full code on Codepen）：

![Playing the growing and shrinking game with Alice.](/zh-CN/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API/growing-shrinking_article_optimized.gif)

在这个游戏中，爱丽丝有一个动画，使她从小到大，我们通过一个瓶子和一个蛋糕控制。这两个都有自己的动画。

### 暂停和启动动画

稍后我们会再讨论爱丽丝的动画，但现在我们来看看蛋糕的动画：

```js
var nommingCake = document
  .getElementById("eat-me\_sprite")
  .animate(
    [{ transform: "translateY(0)" }, { transform: "translateY(-80%)" }],
    {
      fill: "forwards",
      easing: "steps(4, end)",
      duration: aliceChange.effect.timing.duration / 2,
    },
  );
```

`Element.animate()` 方法会在调用后立即执行。为了防止蛋糕在用户有机会点击之前进食自己，我们调用 `Animation.pause()` (en-US) ，如下：

```js
nommingCake.pause();
```

我们可以运行 `Animation.play()` 方法：

```js
nommingCake.play();
```

特别地，我们想将其链接到爱丽丝的动画，所以当蛋糕被吃掉时，她变得更大。我们可以通过以下功能来实现：

```js
var growAlice = function () {
  // Play Alice's animation.
  aliceChange.play();

  // Play the cake's animation.
  nommingCake.play();
};
```

当用户握住鼠标或者在触摸屏上按住他们的手指在蛋糕上时，我们现在可以调用 growAlice 来使所有动画发挥作用：

```js
cake.addEventListener("mousedown", growAlice, false);
cake.addEventListener("touchstart", growAlice, false);
```

### 其他有用的方法

除了暂停和播放，我们可以使用以下动画方法：

* `Animation.finish()` (en-US) 动画结束。
* `Animation.cancel()` 终止动画。
* `Animation.reverse()` (en-US) 反向播放动画。相当于设置动画播放速度（`Animation.playbackRate` (en-US)）为负值，并播放。

让我们先来看一下 playbackRate——一个负值的播放速度将导致一个动画反向播放。当爱丽丝从瓶中喝酒时，她越来越小。这是因为瓶子将动画的播放速度从 1 更改为 -1：

```js
var shrinkAlice = function () {
  aliceChange.playbackRate = -1;
  aliceChange.play();
};

bottle.addEventListener("mousedown", shrinkAlice, false);
bottle.addEventListener("touchstart", shrinkAlice, false);
```

在爱丽丝镜中奇遇记中，爱丽丝旅行到一个世界，她必须在场景中跑步——而且以两倍的速度快速前进！在红女王比赛的例子中，爱丽丝和红女王正在场景中跑步（查看 Codepen 上的完整代码）：

![Alice and the Red Queen race to get to the next square in this game.](/zh-CN/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API/red-queen-race_optimized.gif)

因为小孩子很容易疲惫不堪，不像自动机棋子，爱丽丝不断减速。我们已经通过在动画播放时设置了一个衰减代码：

```js
setInterval(function () {
  // Make sure the playback rate never falls below .4
  if (redQueen_alice.playbackRate > 0.4) {
    redQueen_alice.playbackRate \*= 0.9;
  }
}, 3000);
```

但是通过点击或点击来敦促他们使他们通过乘以播放速度来加快速度：

```js
var goFaster = function () {
  redQueen_alice.playbackRate \*= 1.1;
};

document.addEventListener("click", goFaster);
document.addEventListener("touchstart", goFaster);
```

背景元素还具有播放时间，当你点击或点击时，它们会受到影响。当 Alice 和 Red Queen 跑两倍的时候会发生什么？当你让他们放慢时会发生什么？

获取动画信息
------

想象其他方式我们可以使用 playbackRate，例如通过让他们减慢整个网站的动画来改善具有前庭障碍的用户的无障碍。这不可能在 CSS 中重新计算每个 CSS 规则的持续时间，但是通过 Web 动画 API，我们可以使用即将到来的（在浏览器中不支持！）`document.getAnimations()` (en-US)方法 循环遍历页面上的每个动画，并将它们的播放速度减半：

```js
document.getAnimations().forEach(function (animation) {
  animation.playbackRate \*= 0.5;
});
```

使用 Web 动画 API，你需要更改的只是一个小的属性！

另一件与 CSS 动画有关的难点就是创建依赖于其他动画提供的值。例如，在“成长和收缩爱丽丝”游戏的例子中，你可能会注意到蛋糕的持续时间有些奇怪：

```js
duration: aliceChange.effect.timing.duration / 2;
```

要了解这里发生了什么，让我们来看看 Alice 的动画：

```js
var aliceChange = document
  .getElementById("alice")
  .animate(
    [
      { transform: "translate(-50%, -50%) scale(.5)" },
      { transform: "translate(-50%, -50%) scale(2)" },
    ],
    {
      duration: 8000,
      easing: "ease-in-out",
      fill: "both",
    },
  );
```

爱丽丝的动画让她的尺寸在 8 秒内从一半到两倍。然后我们暂停她：

```js
aliceChange.pause();
```

如果我们在动画开始时已经把她暂停了，那么她的全部尺寸将从一半开始，就像她已经把整个瓶子都喝完了一样！我们想把动画的“播放头”放在中间，这样她就在半途了。我们可以通过将她的 `Animation.currentTime` 设置为 4 秒，如下所示：

```js
aliceChange.currentTime = 4000;
```

但是在制作这个动画的时候，我们可能会改变爱丽丝的持续时间。如果我们将她的 `currentTime` 设置为动态的，它不会更好吗？所以我们不必一次做两个更新？我们实际上可以通过引用 aliceChange 的 `Animation.effect` 属性来实现，该属性返回一个包含 Alice 上所有效果细节的对象：

```js
aliceChange.currentTime = aliceChange.effect.timing.duration / 2;
```

`effect` 让我们能够访问动画的关键帧和时间对象——`aliceChange.effect.timing` 指向 Alice 的时间对象（其类型为 `AnimationEffectTimingReadOnly`）——这包含她的 `AnimationEffectTimingReadOnly.duration`。我们可以将她的持续时间分成两半，以获得她动画时间轴的中点，使她成为正常的高度。现在，我们可以在任何一个方向扭转和播放动画，使她变小或变大！

当设置蛋糕和瓶子的持续时间时，我们可以做同样的事情：

```js
var drinking = document
  .getElementById("liquid")
  .animate([{ height: "100%" }, { height: "0" }], {
    fill: "forwards",
    duration: aliceChange.effect.timing.duration / 2,
  });
drinking.pause();
```

现在，所有三个动画只有一个持续时间，我们可以从一个地方容易地改变。

我们还可以使用 Web 动画 API 来确定动画当前的时间。当你用尽蛋糕吃或者清空瓶子时，游戏就结束了。哪个角色扮演者取决于爱丽丝在她的动画中有多远，无论她是否变得太大，不能进入小门太小，无法达到打开门的钥匙。我们可以弄清楚她是否在动画的大端或小端，让她的动画当前时间 (`currentTime`) 被她的 activeDuration 分成：

```js
var endGame = function() {

  // get Alice's timeline's playhead location
  var alicePlayhead = aliceChange.currentTime;
  var aliceTimeline = aliceChange.effect.activeDuration;

  // stops Alice's and other animations
  stopPlayingAlice();

  // depending on which third it falls into
  var aliceHeight = alicePlayhead/aliceTimeline;

  if (aliceHeight <= .333){
    // Alice got smaller!
    ...

  } else if (aliceHeight >= .666) {
    // Alice got bigger!
    ...

  } else {
    // Alice didn't change significantly
    ...

  }
}
```

**备注：** `getAnimations()` and `effect` are not fully supported as of this writing, but the polyfill does support them today.

Callbacks and promises
----------------------

CSS 动画和转换有自己的事件侦听器，这些也可以通过 Web 动画 API：

* `onfinish` (en-US) is the event handler for the `finish` event and can be triggered manually with `finish()` (en-US).
* `oncancel` is the event handler for the `cancel` event and can be triggers with `cancel()`.

在这里，我们为蛋糕，瓶子和爱丽丝设置回调来触发 endGame 功能：

```js
// When the cake or runs out...
nommingCake.onfinish = endGame;
drinking.onfinish = endGame;

// ...or Alice reaches the end of her animation
aliceChange.onfinish = endGame;
```

Prefer promises? The Web Animations API also specifies two promises: `onfinish` (en-US) and `oncancel`.

**备注：** These promises are not fully supported as of this writing.

结论
--

这些是 Web 动画 API 的基本功能，其中大部分功能已在最新版本的 Firefox 和 Chrome 中得到支持。到目前为止，你应该准备好在浏览器中“跳下兔子洞”，动画制作动画实验！如果你正在使用 API 并要共享，请尝试使用#WAAPI 主题标签。我们将会观看并且将编写更多的教程来涵盖更多的功能，支持传播！

See also
--------

* The full suite of Alice in Wonderland demos on CodePen for you to play with, fork, and share
* Animating like you just don’t care with Element.animate — a great article to read that explains more on the background of the Web Animations API, and why it is more performant than other web animation methods
* web-animations-js — the Web Animations API polyfill


关键帧格式 - Web API 接口参考

关键帧格式
=====

`Element.animate()`、`KeyframeEffect.KeyframeEffect()` (en-US) 和 `KeyframeEffect.setKeyframes()` (en-US) 都接受格式为一组关键帧的对象，这种格式有以下几种选项。

语法
--

关键帧格式有两种不同的方式：

1. 一个由多个关键帧的属性和值组成的对象所构成的`数组`。这是`getKeyframes()` (en-US)方法返回的规范格式。

```js
element.animate(
  [
    {
      // from
      opacity: 0,
      color: "#fff",
    },
    {
      // to
      opacity: 1,
      color: "#000",
    },
  ],
  2000,
);
```

对每个关键帧的偏移可以通过提供一个`offset`来指定。

```js
element.animate(
  [{ opacity: 1 }, { opacity: 0.1, offset: 0.7 }, { opacity: 0 }],
  2000,
);
```

**备注：** `offset` 的值必须是在 **[0.0, 1.0]** 这个区间内，且须升序排列。

并非所有的关键帧都需要设置 `offset`。没有指定 `offset` 的关键帧将与相邻的关键帧均匀间隔。
 可以通过提供`easing`过渡来给指定关键帧之间应用过渡效果，如下所示：

```js
element.animate(
  [
    { opacity: 1, easing: "ease-out" },
    { opacity: 0.1, easing: "ease-in" },
    { opacity: 0 },
  ],
  2000,
);
```

在这个例子中，指定的 easing 仅适用于指定它的关键帧到下一帧之间。但是在`options`中指定的 `easing` 值都将应用在一个动画的整个持续时间里。
2. 一个包含 key-value 键值的`对象`需要包含动画的属性和要循环变化的值`数组`。

```js
element.animate(
  {
    opacity: [0, 1], // [ from, to ]
    color: ["#fff", "#000"], // [ from, to ]
  },
  2000,
);
```

使用这种格式，每个数组的元素数量不必相等。所提供的值将独立分开。

```js
element.animate(
  {
    opacity: [0, 1], // offset: 0, 1
    backgroundColor: ["red", "yellow", "green"], // offset: 0, 0.5, 1
  },
  2000,
);
```

特殊键`offset`，`easing`和`composite`（如下）可以与属性值一起指定。

```js
element.animate(
  {
    opacity: [0, 0.9, 1],
    offset: [0, 0.8], // [ 0, 0.8, 1 ] 的简写
    easing: ["ease-in", "ease-out"],
  },
  2000,
);
```

从属性值列表生成一组合适的关键帧后，每个提供的偏移量将应用于相应的关键帧。如果值不足或者列表包含空值`null`，则以没有指定处理（即和上面第 1 种数组格式的一样均匀间隔）.
 如果`easing` 或`composite` 值太少，将根据需要，重复相应的列表。
属性
--

关键帧可以为任何的 css 动画属性指定 property-value。使用 camel-case 的属性名将变为 camelCase 格式，例如 `background-color` 变成 `backgroundColor` ，再如 `background-position-x` 变成 `backgroundPositionX`.。速记词，例如 `margin` 也是可以用的。.

两个特色的 css 属性：

* `float`, 必须写成 `cssFloat` ，因为"float" 是 JavaScript 的保留关键字
* `offset`, 必须写成 `cssOffset` ，因为"offset" 表示如下的关键帧 offset

还可以指定以下特色属性：

offset

关键帧的 offset 偏移量指定为介于`0.0`和`1.0`之间的数字或为`null`。这相当于使用`@keyframes`在 CSS 样式表中以百分比指定开始和结束状态。如果此值为`null`或缺失，则关键帧将在相邻关键帧之间均匀分布。

easing

从这个关键帧直到这一级中的下一个关键帧所使用的 timing function (en-US)

composite

`KeyframeEffect.composite` (en-US) 操作用于将此关键帧中指定的值与基础值组合在一起。如果正在使用在效果上指定的复合操作，则不会出现这种情况。

参见
--

* Web Animations API
* `Element.animate()`
* `KeyframeEffect()` (en-US)
* `KeyframeEffect.setKeyframes()` (en-US)


检测设备方向 - Web API 接口参考

检测设备方向
======

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

有越来越多的基于 web 的设备能够确定它们的方向; 也就是说，它们可以报告数据以指示基于重力方向的方向改变。特别地，手持设备如手机可以利用这些信息以自动旋转屏幕，保持内容直立，当设备旋转至横屏时（宽度大于高度），提供网页内容的横屏视图。

有两种 Javascript 事件负责处理设备方向信息。第一种是`DeviceOrientationEvent`，它会在加速度传感器检测到设备在方向上产生变化时触发。通过处理该事件传来的数据信息，让交互式地响应用户移动设备旋转和仰角变化成为可能。

第二种是`DeviceMotionEvent`，它会在加速度发生改变时触发。跟`DeviceOrientationEvent`不同，`DeviceMotionEvent`监听的是相应方向上加速度的变化。传感器通常都具有监听`DeviceMotionEvent`的能力，包括笔记本中用于保护移动中的存储设备的传感器。`DeviceOrientationEvent`事件更多见于移动设备中。

处理方向（orientation）事件
-------------------

要接收设备方向变化信息，只需要监听`deviceorientation`事件：

**备注：** gyronorm.js is a polyfill for normalizing the accelerometer and gyroscope data on mobile devices. This is useful for overcoming some of the differences in device support for device orientation.

```js
window.addEventListener("deviceorientation", handleOrientation, true);
```

注册完事件监听处理函数后（对应这个例子中的 handleOrientation），监听函数会定期地接收到最新的设备方向数据。

方向事件对象中包含四个值：

`DeviceOrientationEvent.absolute`
`DeviceOrientationEvent.alpha`
`DeviceOrientationEvent.beta`
`DeviceOrientationEvent.gamma`
下面是一个事件处理函数的例子：

```js
function handleOrientation(orientData) {
  var absolute = orientData.absolute;
  var alpha = orientData.alpha;
  var beta = orientData.beta;
  var gamma = orientData.gamma;

  // Do stuff with the new orientation data
}
```

### 相关值解释

关于每一个轴的记录值表示的是相对于标准的坐标系，设备在某一个给定轴上的旋转量。Orientation and motion data explained 这篇文章有更详细的描述，下面是对这篇文章的总结。

* `DeviceOrientationEvent.alpha` 表示设备沿 z 轴上的旋转角度，范围为 0~360。
* `DeviceOrientationEvent.beta` 表示设备在 x 轴上的旋转角度，范围为 -180~180。它描述的是设备由前向后旋转的情况。
* `DeviceOrientationEvent.gamma` 表示设备在 y 轴上的旋转角度，范围为 -90~90。它描述的是设备由左向右旋转的情况。
### 示例

这个例子会成功运行在支持检测自己方向的设备中的支持`deviceorientation` 事件的浏览器中。

让我们想象一下有一个球在花园中：

```html
<div class="garden">
  <div class="ball"></div>
</div>

<pre class="output"></pre>
```

花园只有 200px 宽（很小对吧），球在中央：

```css
.garden {
  position: relative;
  width: 200px;
  height: 200px;
  border: 5px solid #ccc;
  border-radius: 10px;
}

.ball {
  position: absolute;
  top: 90px;
  left: 90px;
  width: 20px;
  height: 20px;
  background: green;
  border-radius: 100%;
}
```

现在，如果我们移动设备，球将随之移动：

```js
var ball = document.querySelector(".ball");
var garden = document.querySelector(".garden");
var output = document.querySelector(".output");

var maxX = garden.clientWidth - ball.clientWidth;
var maxY = garden.clientHeight - ball.clientHeight;

function handleOrientation(event) {
  var x = event.beta; // In degree in the range [-180,180]
  var y = event.gamma; // In degree in the range [-90,90]

  output.innerHTML = "beta : " + x + "\n";
  output.innerHTML += "gamma: " + y + "\n";

  // Because we don't want to have the device upside down
  // We constrain the x value to the range [-90,90]
  if (x > 90) {
    x = 90;
  }
  if (x < -90) {
    x = -90;
  }

  // To make computation easier we shift the range of
  // x and y to [0,180]
  x += 90;
  y += 90;

  // 10 is half the size of the ball
  // It center the positioning point to the center of the ball
  ball.style.top = (maxX \* x) / 180 - 10 + "px";
  ball.style.left = (maxY \* y) / 180 - 10 + "px";
}

window.addEventListener("deviceorientation", handleOrientation);
```

输出结果：

在这里以新窗口打开此示例；因为有些浏览器中的 `deviceorientation` 事件不支持跨域。

**警告：** Chrome 和 Firefox 处理角度的机制不同，所以某些轴上的方向是相反的。

处理移动（motion）事件
--------------

移动事件的处理跟方向事件是一样的，除了他们有自己的事件名：`devicemotion`

```js
window.addEventListener("devicemotion", handleMotion, true);
```

真正不同的是做为参数传递给*HandleMotion 函数的*`DeviceMotionEvent`对象所包含的信息。

这个对象包含四个属性：

* `DeviceMotionEvent.acceleration`
* `DeviceMotionEvent.accelerationIncludingGravity`
* `DeviceMotionEvent.rotationRate`
* `DeviceMotionEvent.interval`
### 相关值解释

`DeviceMotionEvent`对象提供给 web 开发者设备在位置和方向上的改变速度的相关信息。这些变化信息是通过三个轴来体现的。（Orientation and motion data explained (en-US)有更详细的说明。）

`acceleration` (en-US) 和 `accelerationIncludingGravity` (en-US)，都包含下面三个轴：

* `x`: 西向东
* `y`: 南向北
* `z`: 垂直地面

对于 `rotationRate` (en-US) ，情况有点不同；三个轴的信息对应着以下三种情况：

* `alpha`: 设备沿着垂直于屏幕（对于桌面设备则是垂直于键盘）的轴的旋转速率
* `beta`: 设备沿着屏幕（对于桌面设备则是键盘）左至右方向的轴的旋转速率 (桌面设备相对于键盘)
* `gamma`: 设备沿着屏幕（对于桌面设备则是键盘）下至上方向的轴的旋转速率

最后，`interval` (en-US) 表示的是从设备获取数据的间隔时间，单位是毫秒。

规范
--

| Specification |
| --- |
| DeviceOrientation Event Specification # devicemotion |
| DeviceOrientation Event Specification # deviceorientation |

浏览器兼容性
------

### api.DeviceMotionEvent

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.DeviceOrientationEvent

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `DeviceOrientationEvent`
* `DeviceMotionEvent`
* The legacy `MozOrientation` event.
* Orientation and motion data explained (en-US)
* Using deviceorientation in 3D Transforms (en-US)


Orientation 和 motion 数据解释 - Web API 接口参考

Orientation 和 motion 数据解释
=========================

总言
--

当我们要使用 orientation 和 motion 事件时，理解浏览器给我们的相关值是什么意思就显的相当重要了。这篇文章会详细介绍在用的坐标系统并会教你如何全用它们。

**警告：** 目前，Firefox 和 Chrome 处理坐标的方式不同。在使用它们的时候要多加注意。

坐标系
---

坐标系是一种描述物体位置的系统，它包含三个轴 (X,Y,Z)，三个轴共同描述了物体相对于参照物的位置信息。当我们使用 orientation 和 motion 事件时会接触到两种坐标系统。

### 地球坐标系

地球坐标系是相对于地心的，也就是说，它的轴是基于重力方向和磁场北方向。我们使用大写的 X,Y,Z 来描述地球坐标系的轴。

* X 轴沿着地平面，垂直于 Y 轴，向东为正，向西为负。
* Y 轴沿着地平面，向北 (北极，不是磁场北) 为正，向南为负。
* Z 轴垂直于地平面，想象成一条线连接着设备跟地心。背对地心的方向为正，指向地心的方向为负。
### 设备坐标系

设备坐标系是相对于设备中心的。我们使用小写的 x,y,z 来描述它的轴。

![axes.png](/zh-CN/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/axes.png)

* x 轴沿着屏幕表面，向右为正，向左为负。
* y 轴沿着屏幕表面，向上为正，向下为负。
* z 轴垂直屏幕表面或键盘，远离屏幕的方向为正。

**备注：** 注意：对于手机或平台而言，这里的设备方向总是相对于屏幕的标准方向，大部分是“竖屏”方向。而对于笔记本电脑来说，设备方向是相对于键盘的。如果你想检测设备方向变化来进行补偿调整，你可以使用 orientationchange 事件。

旋转 (Rotation)
-------------

旋转描述的是设备在设备坐标系跟地球坐标系中任意轴上的差异值，用角度表示。

### Alpha

围绕 z 轴旋转设备将使 alpha 角度值发生变化：

![alpha.png](/zh-CN/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/alpha.png)

alpha 为 0° 时表示设备的顶部正指北极方向，当设备向左旋转时，alpha 将增加。

### Beta

围绕 x 轴旋转，也就是前后旋转，将使 beta 值发生改变：

![beta.png](/zh-CN/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/beta2.png)

当 beta 为 0° 时表示设备顶部和底部与地表面的距离是一样的，当设备向前翻转时，beta 递增到 180°，向后翻转递减到 -180°。

### Gamma

当围绕 y 轴旋转，也就是左右倾斜设备时，将使 gamma 值发生改变：

![gamma.png](/zh-CN/docs/Web/API/Device_orientation_events/Orientation_and_motion_data_explained/gamma.png)

gamma 等于 0° 表示设备左右两边与地表面的距离相等，当设备向右翻转时，gamma 递增到 90° ，向左翻转时，递减到 -90°。


ReadableStreamDefaultReader.read() - Web API 接口参考

ReadableStreamDefaultReader.read()
==================================

`ReadableStreamDefaultReader` 接口的 **`read()`** 方法返回一个 `Promise`，这个 promise 提供流的内部队列中下一个分块（以供访问）。

语法
--

```js
read()
```

### 参数

无。

### 返回值

一个 `Promise`，其兑现/拒绝的结果取决于流的状态。不同的可能性如下：

* 如果有分块可用，则 promise 将使用 `{ value: theChunk, done: false }` 形式的对象来兑现。
* 如果流已经关闭，则 promise 将使用 `{ value: undefined, done: true }` 形式的对象来兑现。
* 如果流发生错误，promise 将因相关错误被拒绝。
### 异常

`TypeError`

源对象不是 `ReadableStreamDefaultReader`，或者流没有所有者。

示例
--

### 示例 1——简单的例子

这个例子展示了基本的 API 使用方法，但是其不会尝试处理一些复杂的问题，如流中的分块不在行的末尾结束。

在此示例中 `stream` 是一个先前创建的自定义 `ReadableStream`。它使用 `getReader()` 创建的 `ReadableStreamDefaultReader` 读取。（有关完整代码请参见简单随机流演示）。每个块按顺序读取并作为 UTF-8 字节数组输出到 UI，直到流完成读取，此时我们退出递归函数并将整个流打印到 UI 的另一部分。

```js
function fetchStream() {
  const reader = stream.getReader();
  let charsReceived = 0;
  // read() 返回一个 promise，其会在接收到数据时被兑现
  reader.read().then(function processText({ done, value }) {
    // 结果包含两个属性：
    // done - 如果为 true，表示流已经返回所有的数据。
    // value - 一些数据，done 为 true 时，其值始终为 undefined。
    if (done) {
      console.log("Stream complete");
      para.textContent = result;
      return;
    }
    // 从流中获取的数据是一个 Uint8Array
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent =
      "Received " +
      charsReceived +
      " characters so far. Current chunk = " +
      chunk;
    list2.appendChild(listItem);
    result += chunk;
    // 再次调用该函数以读取更多数据
    return reader.read().then(processText);
  });
}
```

### 示例 2——逐行处理文本

这个示例向你展示如何获取一个文本文件并以流的形式处理文本中的每一行。它能够处理分块不在行的末尾结束的情况，并将 Uint8Array 转换为字符串。

```js
async function\* makeTextFileLineIterator(fileURL) {
  const utf8Decoder = new TextDecoder("utf-8");
  let response = await fetch(fileURL);
  let reader = response.body.getReader();
  let { value: chunk, done: readerDone } = await reader.read();
  chunk = chunk ? utf8Decoder.decode(chunk, { stream: true }) : "";
  let re = /\r\n|\n|\r/gm;
  let startIndex = 0;
  for (;;) {
    let result = re.exec(chunk);
    if (!result) {
      if (readerDone) {
        break;
      }
      let remainder = chunk.substr(startIndex);
      ({ value: chunk, done: readerDone } = await reader.read());
      chunk =
        remainder + (chunk ? utf8Decoder.decode(chunk, { stream: true }) : "");
      startIndex = re.lastIndex = 0;
      continue;
    }
    yield chunk.substring(startIndex, result.index);
    startIndex = re.lastIndex;
  }
  if (startIndex < chunk.length) {
    // last line didn't end in a newline char
    yield chunk.substr(startIndex);
  }
}
for await (let line of makeTextFileLineIterator(urlOfFile)) {
  processLine(line);
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-default-reader-read① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `ReadableStreamDefaultReader()` 构造函数
* 使用可读流


ReadableStreamDefaultReader.releaseLock() - Web API 接口参考

ReadableStreamDefaultReader.releaseLock()
=========================================

`ReadableStreamDefaultReader` 接口的 **`releaseLock()`** 方法用于释放 reader 对流的锁定。

如果释放锁时关联流出错，reader 随后会以同样的方式发生错误；此外，reader 将关闭。

reader 的锁在仍有待处理的读取请求时无法释放，即，如果 reader 的 `ReadableStreamDefaultReader.read()` 方法返回的 promise 尚未完成，这将导致抛出 `TypeError`。

语法
--

```js
releaseLock()
```

### 参数

无。

### 返回值

无 (`undefined`)。

### 异常

`TypeError`

如果源对象不是一个 `ReadableStreamDefaultReader`，或者仍有读取请求处于等待状态。

示例
--

```js
function fetchStream() {
  const reader = stream.getReader();
  ...
  reader.releaseLock()
  ...
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-default-reader-release-lock② |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `ReadableStreamDefaultReader()` 构造函数
* 使用可读流


ReadableStreamDefaultReader.closed - Web API 接口参考

ReadableStreamDefaultReader.closed
==================================

`ReadableStreamDefaultReader` 接口的只读属性 **`closed`** 返回一个 `Promise`，这个 promise 在流关闭时兑现，而在流抛出错误或者 reader 的锁被释放时拒绝。该属性使你能够编写在一个流结束时响应的代码。

值
-

一个 `Promise`。

示例
--

在这个片段中，查询一个先前创建的 reader 以查看流是否被关闭。当它关闭时，promise 兑现，并在控制台输出消息。

```js
reader.closed.then(() => {
  console.log("reader closed");
});
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-generic-reader-closed② |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `ReadableStreamDefaultReader()` 构造函数
* 使用可读流


ReadableStreamDefaultReader.cancel() - Web API 接口参考

ReadableStreamDefaultReader.cancel()
====================================

`ReadableStreamDefaultReader` 接口的 **`cancel()`** 方法返回一个 `Promise`，这个 promise 在流被取消时兑现。消费者在流中调用该方法发出取消流的信号。

cancel 用于在不再需要来自一个流的任何数据的情况下完全结束这个流，即使仍有排队等待的数据块。调用 cancel 后该数据丢失，并且流不再可读。为了仍然可以读这些数据块而不完全结束这个流，你应该使用 `ReadableStreamDefaultController.close()`。

**备注：** 如果 reader 处于激活状态，`cancel()` 方法的行为和关联流 (`ReadableStream.cancel()`) 的行为相同。

语法
--

```js
cancel()
cancel(reason)
```

### 参数

`reason` 可选

人类可读的取消原因。这个值可能会被使用。

### 返回值

一个 `Promise`，会在结束时使用给定的 `reason` 参数兑现。

### 异常

`TypeError`

源对象不是 `ReadableStreamDefaultReader`，或者流没有所有者。

示例
--

在下面的简单示例中，使用 `getReader()` 创建的 `ReadableStreamDefaultReader` 读取先前自定义的 `ReadableStream`。（有关完整代码简单随机流演示）。直到流完成读取，每一个块都按顺序读取并输出到 UI，此时我们退出递归函数并且将整个流打印到 UI 的另一部分。

```js
function fetchStream() {
  const reader = stream.getReader();
  let charsReceived = 0;
  // read() 返回一个 promise，其会在接收到数据时被兑现
  reader.read().then(function processText({ done, value }) {
    // 结果包含两个属性：
    // done - 如果为 true，表示流已经返回所有的数据。
    // value - 一些数据，done 为 true 时，其值始终为 undefined。
    if (done) {
      console.log("Stream complete");
      para.textContent = result;
      return;
    }
    // 从流中获取的数据是一个 Uint8Array
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent =
      "Received " +
      charsReceived +
      " characters so far. Current chunk = " +
      chunk;
    list2.appendChild(listItem);
    result += chunk;
    // 再次调用该函数以读取更多数据
    return reader.read().then(processText);
  });
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-generic-reader-cancel② |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `ReadableStreamDefaultReader()` 构造函数
* 使用可读流


ReadableStreamDefaultReader() - Web API 接口参考

ReadableStreamDefaultReader()
=============================

**`ReadableStreamDefaultReader()`** 构造函数创建并返回一个 `ReadableStreamDefaultReader` 实例对象。

**备注：** 你通常不需要手动创建，可以使用 `ReadableStream.getReader()` 方法代替。

语法
--

```js
new ReadableStreamDefaultReader(stream)
```

### 参数

`stream`

将被读取的 `ReadableStream`。

### 返回值

一个 `ReadableStreamDefaultReader` 实例对象。

### 异常

`TypeError`

如果提供的 `stream` 参数不是一个 `ReadableStream`，或者它已经被另一个 reader 锁定则抛出异常。

示例
--

在下面的简单示例中，使用 `getReader()` 创建的 `ReadableStreamDefaultReader` 读取先前自定义的 `ReadableStream`。（有关完整代码简单随机流演示）。直到流完成读取，每一个块都按顺序读取并输出到 UI，此时我们退出递归函数并且将整个流打印到 UI 的另一部分。

```js
function fetchStream() {
  const reader = stream.getReader();
  let charsReceived = 0;
  // read() 返回一个 promise，其会在接收到数据时被兑现
  reader.read().then(function processText({ done, value }) {
    // 结果包含两个属性：
    // done - 如果为 true，表示流已经返回所有的数据。
    // value - 一些数据，done 为 true 时，其值始终为 undefined。
    if (done) {
      console.log("Stream complete");
      para.textContent = result;
      return;
    }
    // 从流中获取的数据是一个 Uint8Array
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent =
      "Received " +
      charsReceived +
      " characters so far. Current chunk = " +
      chunk;
    list2.appendChild(listItem);
    result += chunk;
    // 再次调用该函数以读取更多数据
    return reader.read().then(processText);
  });
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-default-reader-constructor① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Stream API 概念
* 使用可读流
* `ReadableStream`
* `ReadableStreamDefaultController`


Notification：badge 属性 - Web API 接口参考

Notification：badge 属性
=====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

当没有足够的空间来显示通知本身时，`Notification` 接口的 **`badge`** 属性返回用于表示通知的图像 URL。

值
-

一个包含 URL 的字符串。

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-badge |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Notification：data 属性 - Web API 接口参考

Notification：data 属性
====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`data`** 只读属性返回一个在 `Notification()` 构造函数的 `data` 选项中指定的、结构化的通知的数据。

通知的数据可以是任意你希望与通知关联的数据。

值
-

一个结构化的克隆数据。

示例
--

以下代码段会触发一条通知。一个简单的 `options` 对象被创建，然后使用 `Notification()` 构造函数触发通知。

```js
const options = {
  body: "你提交的代码收到了 3 条新的审阅意见。",
  data: {
    url: "https://example.com/review/12345",
    status: "open",
  },
};

const n = new Notification("新评论活动", options);

console.log(n.data); // 打印 data 对象
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-data |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：actions 属性 - Web API 接口参考

Notification：actions 属性
=======================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Notification` 接口的只读属性 **`actions`** 提供了可供用户选择的以与通知交互的操作。

使用 `showNotification()` (en-US) 方法和 `Notification()` 构造函数的第二个参数的 `actions` 选项设置操作。

**备注：** 浏览器通常会限制它们为特定通知显示的最大操作数。检测 `Notification.maxActions` (en-US) 静态属性以确定限制的操作的数量。

值
-

一个只读的操作数组。数组中的每个元素都是一个具有以下成员的对象：

`action`

一个标识要在通知上显示的用户操作的字符串。

`title`

一个包含要向用户显示的操作文本的字符串。

`icon`

一个包含与操作一起显示的图标 URL 的字符串。

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-actions |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API
* `Notification.maxActions` (en-US)


Notification：silent 属性 - Web API 接口参考

Notification：silent 属性
======================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`silent`** 只读属性指定通知是否应当保持静默，即无论设备设置如何，都不发出声音或振动。该属性在`Notification()` 构造函数的 `silent` 选项中指定。

值
-

一个布尔值。默认值是 `false`；设为 `true` 将使通知静音。

示例
--

以下代码片段旨在触发静默通知；创建一个简单的 `options` 对象，然后调用 `Notification()` 构造函数触发通知。

```js
const options = {
  body: "你提交的代码收到了 3 条新的审阅意见。",
  silent: true,
};

const n = new Notification("新评论活动", options);

console.log(n.silent); // "true"
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-silent |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：vibrate 属性 - Web API 接口参考

Notification：vibrate 属性
=======================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Notification` 接口的 `vibrate` 只读属性指定当通知触发时设备振动硬件发出的振动模式。此属性通过 `Notification()` 构造函数的 `vibrate` 选项指定。

值
-

一个振动 API 规范所指定的振动模式。

示例
--

以下代码片段旨在创建同时触发设备振动的通知；首先创建一个简单的 `options` 对象，然后使用 `Notification()` 构造函数触发通知。

```js
const options = {
  body: "你提交的代码收到了 3 条新的审阅意见。",
  vibrate: [200, 100, 200],
};

const n = new Notification("新的评论活动", options);

console.log(n.vibrate); // "[200, 100, 200]"
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-vibrate |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：close 事件 - Web API 接口参考

Notification：close 事件
=====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口上的 **`close`** 事件在一个 `Notification` 被关闭时触发。

语法
--

在类似 `addEventListener()` 这样的方法中使用事件名称，或者设置事件处理器属性。

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

onclose = (event) => {};
```

事件类型
----

一个通用 `Event`。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Notification`
* 使用 Notification API


Notification：requestPermission() 静态方法 - Web API 接口参考

Notification：requestPermission() 静态方法
=====================================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**备注：** Safari 仍然使用回调函数语法来请求权限。使用 Notifications API 的例子说明了如何检测需使用回调函数语法的情况并以适当的方式运行代码。

`Notification` 接口的 **`requestPermission()`** 静态方法向用户为当前来源请求显示通知的权限。

语法
--

```js
// 最新规范已将此方法更新为基于 promise 的语法，其工作方式如下：
Notification.requestPermission()

// 以前，语法是基于一个简单的回调函数；此版本现已弃用：
Notification.requestPermission(callback)
```

### 参数

`callback` 可选
已弃用

一个可选的参数为权限请求的结果的回调函数。此参数已废弃，请使用 Promise 的语法。

### 返回值

一个 `Promise`，会兑现为一个表示用户选择的权限的字符串。该字符串的可能值为：

* `granted`
* `denied`
* `default`
示例
--

假设如下基本的 HTML：

```html
<button onclick="notifyMe()">通知我！</button>
```

可以按如下方式发送通知——这里我们提供了一组相当详细和完整的代码，如果你想首先检查是否支持通知，然后检查是否已授予当前域名发送通知的权限，然后，如果必需的话，在发送通知前请求权限。

```js
function notifyMe() {
  if (!("Notification" in window)) {
    // 检查浏览器是否支持桌面通知
    alert("此浏览器不支持桌面通知");
  } else if (Notification.permission === "granted") {
    // 检查通知权限是否已经被授予；如果是的话，创建一条通知
    const notification = new Notification("你好呀！");
    // …
  } else if (Notification.permission !== "denied") {
    // 我们需要请求用户的许可
    Notification.requestPermission().then((permission) => {
      // 如果用户同意，让我们创建一个通知
      if (permission === "granted") {
        const notification = new Notification("你好呀！");
        // …
      }
    });
  }

  // 最后，如果用户拒绝了通知，而你想要尊重他们，就没有必要再打扰他们了。
}
```

我们不再在此页面上展示实时示例，因为 Chrome 和 Firefox 不再允许从跨源 `<iframe>` 请求通知权限，并且其他浏览器也将效仿。要查看实际示例，请查看我们的待办事项列表示例（参见实时运行用例）。

**备注：** 在上面的示例中，我们生成通知以响应用户手势（单击按钮）。这不仅仅是最佳实践——你不应该向用户滥发他们不同意的通知——而且未来的浏览器将明确禁止未响应用户手势而触发的通知。例如，Firefox 已经从版本 72 开始这样做了。

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-requestpermission |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notifications API


Notification：image 属性 - Web API 接口参考

Notification：image 属性
=====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Notification` 接口的 `image` 只读属性包含要作为通知的一部分显示的图像的 URL，在 `Notification()` 构造函数的 `image` 选项中指定。

值
-

一个字符串。

规范
--

| Specification |
| --- |
| Notifications API Standard # image-resource |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：close() 方法 - Web API 接口参考

Notification：close() 方法
=======================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 `close()` 的方法用于关闭或移除一个先前显示的通知。

**备注：** 此 API 不应仅用于在固定延迟后从屏幕上移除通知，因为此方法还将从任何通知托盘中删除该通知，阻止用户在最初显示后与其交互。此 API 的有效用途是移除不再相关的通知（例如，如果是消息应用程序，则用户已经阅读了网页上的通知；或者音乐应用程序中已经在播放下一首歌曲）。

语法
--

```js
close()
```

### 参数

无（`undefined`）。

### 返回值

无。

示例
--

在下面的代码片段中，我们有一个简单的函数，当调用时创建一个 `options` 对象，然后是一个新的通知。在函数的最后，它在 `addEventListener()` 函数中调用 `close()` 以在网页上阅读相关内容后移除该通知。

```js
function spawnNotification(theBody, theIcon, theTitle) {
  const options = {
    body: theBody,
    icon: theIcon,
  };

  const n = new Notification(theTitle, options);
  document.addEventListener("visibilitychange", () => {
    if (document.visibilityState === "visible") {
      // 该选项卡已变得可见，因此清除了现在过时的通知。
      n.close();
    }
  });
}
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-close |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notifications API


Notification：show 事件 - Web API 接口参考

Notification：show 事件
====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口上的 **`show`** 事件在一个 `Notification` 显示时触发。

语法
--

在类似 `addEventListener()` 这样的方法中使用事件名称，或者设置事件处理器属性。

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

onshow = (event) => {};
```

事件类型
----

一个通用 `Event`。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Notification`
* 使用 Notification API


Notification：title 属性 - Web API 接口参考

Notification：title 属性
=====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`title`** 只读属性指示通知的标题。此属性通过 `Notification()` 构造函数的 `title` 参数指定。

值
-

一个字符串。

示例
--

```js
function spawnNotification(theBody, theIcon, theTitle) {
  const options = {
    body: theBody,
    icon: theIcon,
  };

  const n = new Notification(theTitle, options);

  console.log(n.title);
}
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-title |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：lang 属性 - Web API 接口参考

Notification：lang 属性
====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`lang`** 只读属性指示通知中使用的语言，在 {domxref("Notification.Notification","Notification()")}} 构造函数的 `lang` 参数中指定。

语言本身是根据 RFC 5646: Tags for Identifying Languages（即 BCP 47）使用表示语言标签的字符串指定的。请参阅 Sitepoint ISO 2 字母语言代码 页面以获取简单参考。

值
-

一个指定语言标签的字符串。

示例
--

以下代码段会触发一条通知；首先创建一个简单的 `options` 对象，然后使用 `Notification()` 构造函数触发通知。

```js
const options = {
  body: "你提交的代码收到了 3 条新的审阅意见。",
  lang: "zh-Hans-CN",
};

const n = new Notification("新的评论活动", options);

console.log(n.lang); // "zh-Hans-CN"
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-lang |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：requireInteraction 属性 - Web API 接口参考

Notification：requireInteraction 属性
==================================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Notification` 接口的 **`requireInteraction`** 只读属性返回一个布尔值，指示在用户点击或关闭通知前，通知应该保持活动状态，而不是自动关闭。

**备注：** 可以在创建通知时通过将 `Notification.Notification()` 构造方法的 `requireInteraction` 选项设置为 `true` 来进行设置。

值
-

一个布尔值。

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-requireinteraction |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：tag 属性 - Web API 接口参考

Notification：tag 属性
===================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`tag`** 只读属性表示通知的识别标签。此属性通过 `Notification()` 构造函数的 `tag` 选项中指定。

通知的标签的构想是多个通知可以共享同一个标签，将它们链接在一起。然后可以通过编程方式将一个通知替换为另一个通知，以避免用户的屏幕被大量类似的通知填满。

值
-

一个字符串。

示例
--

我们的使用通知 API 文章有一个很好的标签属性的使用示例。

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-tag |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：dir 属性 - Web API 接口参考

Notification：dir 属性
===================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 `dir` 只读属性指示通知的文本方向，此文本方向在 `Notification()` 构造函数的 `dir` 选项中指定。

值
-

一个表示文本方向的字符串。可能的取值为：

`auto`

继承浏览器的语言设置里指定的方向（默认值）。

`ltr`

从左到右。

`rtl`

从右到左。

**备注：** 大多数浏览器似乎都忽略了明确的 ltr 和 rtl 设置，而是使用浏览器的通用设置。

示例
--

以下代码段会触发通知；首先创建一个简单的 `options` 对象，然后使用 `Notification()` 构造函数触发通知。

```js
const options = {
  body: "你提交的代码收到了 3 条新的审阅意见。",
  dir: "rtl",
};

const n = new Notification("新评论活动", options);

console.log(n.dir); // "rtl"
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-dir |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：Notification() 构造函数 - Web API 接口参考

Notification：Notification() 构造函数
================================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**`Notification()`** 构造函数创建一个新的代表用户通知的 `Notification` 对象实例。

语法
--

```js
new Notification(title)
new Notification(title, options)
```

### 参数

`title`

定义一个通知的标题，它将显示在通知窗口的顶部。

`options` 可选

一个包含要应用于通知的任何自定义设置的选项对象。可能的选项有：

`dir`

显示通知的方向。它默认为 `auto`，即只采用浏览器的语言设置行为，但你可以通过设置 `ltr` 和 `rtl` 的值来覆盖该行为（尽管大多数浏览器似乎忽略这些设置）。

`lang`

指定通知的语言，根据RFC 5646: 识别语言的标签（也被称为 BCP47）使用表示语言标签的字符串指定。请参阅 Sitepoint ISO 2 字母语言代码页面以获取简单参考。

`badge`

一个包含图像 URL 的字符串，用于在没有足够空间显示通知本身时表示通知。

`body`

一个表示通知正文的字符串，显示在标题下方。

`tag`

一个表示通知的识别标签的字符串，默认值是一个空字符串。

`icon`

一个包含要在通知中显示的图标的 URL 的字符串。

`image`

一个包含要在通知中显示的图像的 URL 的字符串。

`data`

任意你想要与通知关联的数据。它可以是任何数据类型。

`vibrate`

设备振动硬件随通知一起发出的振动模式。当该值被指定时，`silent` 参数不得设置为 `true`。

`renotify`

一个布尔值，指定在新通知替换旧通知后是否应通知用户。默认值为 `false`，这意味着他们不会收到通知。如果该值被指定为 `true`，那么必须同时设置 `tag` 参数。

`requireInteraction`

指示通知应保持活动状态，直到用户单击或关闭它，而不是自动关闭。默认值为 `false`。

`actions`

要在通知中显示的一系列操作的数组。数组中的每个元素都是一个具有以下成员的对象：

* `action`：一个标识要在通知上显示的用户操作的字符串。
* `title`：一个包含要向用户显示的操作文本的字符串。
* `icon`：一个包含与操作一起显示的图标 URL 的字符串。

使用 `notificationclick` (en-US) 事件中的 `event.action` 构建适当的响应。

`silent`

一个布尔值，指定通知是否静音（不发出声音或振动），无论设备设置如何。默认值为 `false`，这意味着它不会保持静音。如果被设置为 `true`，那么不能同时传递 `vibrate` 参数。

### 异常

`TypeError`

如果满足以下条件之一，则抛出该异常：

* `options.silent` 是 `true` 且同时指定了 `options.vibrate`。
* `options.renotify` 是 `true` 但是 `options.tag` 为空值。

示例
--

在我们的 `Emogotchi` 演示（查看源代码）中，当我们想要触发通知时，我们运行 `spawnNotification()` 函数。该函数传递参数来指定我们想要的正文、图标和标题，然后它创建必要的 `options` 对象并使用 `Notification()` 构造函数触发通知。

```js
function spawnNotification(body, icon, title) {
  const notification = new Notification(title, { body, icon });
}
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-notification |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### Chrome 浏览器备注

从 Chrome 49 开始，通知在无痕模式下不起作用。

Android 版 Chrome 会在调用 `Notification` 构造函数时抛出 `TypeError`。它仅支持从 Service Worker 中创建通知。有关更多详细信息，请参阅 Chromium 问题跟踪器。

参见
--

* 使用 Notification API


Notification：click 事件 - Web API 接口参考

Notification：click 事件
=====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`click`** 事件在用户点击显示的 `Notification` 时候触发。

默认的事件行为是将焦点移动到与通知相关浏览上下文的视口上。如果你不想要默认行为，请在事件对象上调用 `preventDefault()`。

语法
--

在类似 `addEventListener()` 这样的方法中使用事件名称，或者设置事件处理器属性。

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

onclick = (event) => {};
```

事件类型
----

一个通用 `Event`。

示例
--

在下面这个例子中，我们使用 onclick 处理器来监听点击通知的事件，并在新窗口（通过包含一个参数 `'_blank'`）打开一个页面：

```js
notification.onclick = (event) => {
  event.preventDefault(); // 阻止浏览器聚焦于 Notification 的标签页
  window.open("http://www.mozilla.org", "\_blank");
};
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-onclick |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Notification`
* 使用 Notification API


Notification：icon 属性 - Web API 接口参考

Notification：icon 属性
====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`icon`** 只读属性包含将作为通知的一部分显示的图标的 URL，在 `Notification()` 构造函数的 `icon` 选项中指定。

值
-

一个字符串。

示例
--

在我们的 To-do list app（查看实时运行示例），我们使用 `Notification()` 构造函数触发通知，并将参数传递给它以指定我们想要的 body、icon 和 title。

```js
const notification = new Notification("To do list", {
  body: text,
  icon: img,
});
```

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-icon |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Notification API


Notification：error 事件 - Web API 接口参考

Notification：error 事件
=====================

**备注：** 此特性在 Web Worker 中可用

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`Notification` 接口的 **`error`** 事件在 `Notification` 调用出错时候触发（在许多情况下，错误会阻止通知的显示）。

语法
--

在类似 `addEventListener()` 这样的方法中使用事件名称，或者设置事件处理器属性。

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

onerror = (event) => {};
```

事件类型
----

一个通用 `Event`。

规范
--

| Specification |
| --- |
| Notifications API Standard # dom-notification-onerror |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Notification`
* 使用 Notification API