DOMParser - Web API 接口参考

DOMParser
=========

**`DOMParser`** 可以将存储在字符串中的 XML 或 HTML 源代码解析为一个 DOM `Document`。

**备注：** `XMLHttpRequest` 支持从 URL 可寻址资源解析 XML 和 HTML，在其`response` 属性中返回`Document`。

你可以使用`XMLSerializer` 接口执行相反的操作 - 将 DOM 树转换为 XML 或 HTML 源。

对于 HTML 文档，你还可以通过设置 `Element.innerHTML` 和`outerHTML` 属性的值，将部分 DOM 替换为从 HTML 构建的新 DOM 树。还可以读取这些属性以获取对应于相应 DOM 子树的 HTML 片段。

语法
--

```js
let domparser = new DOMParser();
```

方法
--

`DOMParser.parseFromString()` (en-US)### 语法

```js
let doc = domparser.parseFromString(string, mimeType);
```

### 返回值

基于 **`mimeType`** 参数，返回 `Document` 或 `XMLDocument` 或其他文档类型。

### 参数

该方法接收 2 个必要参数：

`string`

要解析的 `DOMString`。它必须包含 HTML、xml、xhtml+xml 或 svg 文档。

`mimeType`

一个 `DOMString`。This string determines a class of the the method's return value. The possible values are the following:

| `mimeType` | doc.constructor |
| --- | --- |
| `text/html` | `Document` |
| `text/xml` | `XMLDocument` |
| `application/xml` | `XMLDocument` |
| `application/xhtml+xml` | `XMLDocument` |
| `image/svg+xml` | `XMLDocument` |

解析 XML
------

一旦建立了一个解析对象以后，你就可以使用它的 `parseFromString` 方法来解析一个 XML 字符串：

```js
let parser = new DOMParser(),
  doc = parser.parseFromString(stringContainingXMLSource, "application/xml");
```

#### 错误处理

如果解析失败，`DOMParser` 不会抛出任何异常，而是会返回一个给定的错误文档：

```xml
<parsererror xmlns="http://www.mozilla.org/newlayout/xml/parsererror.xml">
(error description)
<sourcetext>(a snippet of the source XML)</sourcetext>
</parsererror>
```

解析错误会显示在错误控制台，包括文档的地址和错误的源代码。

解析 SVG 或者 HTML 文档
-----------------

`DOMParser` 也可以用来解析 SVG 文档或者 HTML 文档。根据给定的 MIME 类型不同，`parseFromString` 方法可能返回三种不同类型的文档。如果 MIME 类型是 `text/xml`，则返回一个 `XMLDocument`，如果 MIME 类型是 `text/svg+xml`，则返回一个 `SVGDocument`，如果 MIME 类型是 `text/html`，则返回一个 `HTMLDocument`。

```js
let parser = new DOMParser();
let doc = parser.parseFromString(stringContainingXMLSource, "application/xml");
// 返回一个 Document 对象，但不是 SVGDocument，也不是 HTMLDocument

parser = new DOMParser();
doc = parser.parseFromString(stringContainingXMLSource, "image/svg+xml");
// 返回一个 SVGDocument 对象，同时也是一个 Document 对象。

parser = new DOMParser();
doc = parser.parseFromString(stringContainingHTMLSource, "text/html");
// 返回一个 HTMLDocument 对象，同时也是一个 Document 对象。
```

DOMParser HTML 扩展
-----------------

```js
/\*
 \* DOMParser HTML extension
 \* 2012-09-04
 \*
 \* By Eli Grey, http://eligrey.com
 \* Public domain.
 \* NO WARRANTY EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK.
 \*/

/\*! @source https://gist.github.com/1129031 \*/
/\*global document, DOMParser\*/

(function (DOMParser) {
  "use strict";

  var proto = DOMParser.prototype,
    nativeParse = proto.parseFromString;

  // Firefox/Opera/IE throw errors on unsupported types
  try {
    // WebKit returns null on unsupported types
    if (new DOMParser().parseFromString("", "text/html")) {
      // text/html parsing is natively supported
      return;
    }
  } catch (ex) {}

  proto.parseFromString = function (markup, type) {
    if (/^\s\*text\/html\s\*(?:;|$)/i.test(type)) {
      var doc = document.implementation.createHTMLDocument("");
      if (markup.toLowerCase().indexOf("<!doctype") > -1) {
        doc.documentElement.innerHTML = markup;
      } else {
        doc.body.innerHTML = markup;
      }
      return doc;
    } else {
      return nativeParse.apply(this, arguments);
    }
  };
})(DOMParser);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-parsing-and-serialization |

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

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

参见
--

* Parsing and serializing XML (en-US)
* `XMLHttpRequest`
* `XMLSerializer`
* `JSON.parse()` - counterpart for `JSON` documents.


NodeList - Web API 接口参考

NodeList
========

`NodeList` 对象是节点的集合，通常是由属性，如`Node.childNodes` 和 方法，如`document.querySelectorAll` 返回的。

**备注：** `NodeList` **不是一个数组**，是一个类似数组的对象 (*Like Array Object*)。虽然 `NodeList` 不是一个数组，但是可以使用 `forEach()` 来迭代。你还可以使用 `Array.from()` 将其转换为数组。

不过，有些浏览器较为过时，没有实现 `NodeList.forEach()` 和 `Array.from()`。你可以用 `Array.prototype.forEach()` 来规避这一问题。请查看该例。

在一些情况下，`NodeList` 是一个实时集合，也就是说，如果文档中的节点树发生变化，`NodeList` 也会随之变化。例如，`Node.childNodes` 是实时的：

```js
var parent = document.getElementById("parent");
var child_nodes = parent.childNodes;
console.log(child_nodes.length); // 我们假设结果会是“2”
parent.appendChild(document.createElement("div"));
console.log(child_nodes.length); // 但此时的输出是“3”
```

在其他情况下，`NodeList` 是一个静态集合，也就意味着随后对文档对象模型的任何改动都不会影响集合的内容。比如 `document.querySelectorAll` 就会返回一个静态 `NodeList`。

最好牢记这种不同，尤其是在当你选择 `NodeList` 中所有项遍历的方式，或缓存它的长度的时候。

属性
--

`NodeList.length`

`NodeList` 中包含的节点个数。

方法
--

`NodeList.item()`

返回 `NodeList` 对象中指定索引的节点，如果索引越界，则返回`null`。等价的写法是 `nodeList[i]`，不过，在这种情况下，越界访问将返回 `undefined`。

`NodeList.entries()`

Returns an `iterator`, allowing code to go through all key/value pairs contained in the collection. (In this case, the keys are numbers starting from 0 and the values are nodes.)

`NodeList.forEach()`

Executes a provided function once per `NodeList` element, passing the element as an argument to the function.

`NodeList.keys()`

Returns an `iterator`, allowing code to go through all the keys of the key/value pairs contained in the collection. (In this case, the keys are numbers starting from 0.)

`NodeList.values()`

Returns an `iterator` allowing code to go through all values (nodes) of the key/value pairs contained in the collection.

例子
--

可以使用 for 循环遍历一个 `NodeList` 对象中的所有的节点：

```js
for (var i = 0; i < myNodeList.length; ++i) {
  var item = myNodeList[i]; // 调用 myNodeList.item(i) 是没有必要的
}
```

**不要尝试使用 `for...in` 或者 `for each...in` 来遍历一个 `NodeList` 对象中的元素**，因为，如果你把上述两个属性也看成 `element` 对象的话，`NodeList` 对象中的 `length` 和 `item` 属性也会被遍历出来，这可能会导致你的脚本运行出错。此外，`for...in` 不能保证访问这些属性的顺序。

for...of 循环**将会**正确的遍历 `NodeList` 对象：

```js
var list = document.querySelectorAll("input[type=checkbox]");
for (var checkbox of list) {
  checkbox.checked = true;
}
```

最近，浏览器也支持一些遍历方法，比如 `forEach()` 与 `entries()`、`values()`、和 `keys()`。

也有一种使用数组 `Array` 的 `Array.prototype.forEach` 来遍历 `NodeList` 的方法，这种方法兼容 Internet Explorer
已弃用
：

```js
var list = document.querySelectorAll("input[type=checkbox]");
Array.prototype.forEach.call(list, function (checkbox) {
  checkbox.checked = true;
});
```

英文原版中已删除的内容
-----------

>
> 译者注：也许它已独立成了一篇单独的技术文章。如果有找到这样的文章，请将其链接添加至本页末的“参见”处，并删除本节内容。如果没有“参见”，请添加它为二级标题（`<h2>`），`<h2>` 的 `id` 属性为“See\_also”或“参见”。
>
>
>

### 为什么 NodeList 不是数组？

`NodeList` 对象在某些方面和数组非常相似，看上去可以直接使用从 `Array.prototype` 上继承的方法。然而，除了 `forEach` 方法，`NodeList` 没有这些类似数组的方法。

JavaScript 的继承机制是基于原型的。数组元素之所以有一些数组方法（比如 `forEach` 和 `map`），是因为它的原型链上有这些方法，如下：

`myArray --> Array.prototype --> Object.prototype --> null`（想要获取一个对象的原型链，可以连续地调用 `Object.getPrototypeOf`，直到原型链尽头）。

`forEach`，`map` 这些方式其实是 `Array.prototype` 这个对象的方法。

和数组不一样的是，`NodeList` 的原型链是这样的：

`myNodeList --> NodeList.prototype --> Object.prototype --> null`

NodeList 的原型上除了类似数组的 `forEach` 方法之外，还有 `item`，`entries`，`keys` 和 `values` 方法。

#### 解决办法

一个解决办法就是把 `Array.prototype` 上的方法添加到 `NodeList.prototype` 上。可是，要注意扩展 DOM 对象的原型是非常危险的，尤其是在旧版本的 Internet Explorer（6，7，8）中。

```js
var arrayMethods = Object.getOwnPropertyNames(Array.prototype);

arrayMethods.forEach(attachArrayMethodsToNodeList);

function attachArrayMethodsToNodeList(methodName) {
  if (methodName !== "length") {
    NodeList.prototype[methodName] = Array.prototype[methodName];
  }
}

var divs = document.getElementsByTagName("div");
var firstDiv = divs[0];

firstDiv.childNodes.forEach(function (divChild) {
  divChild.parentNode.style.color = "#0F0";
});
```

不扩展 DOM 对象原型的解决办法：

```js
var forEach = Array.prototype.forEach;

var divs = document.getElementsByTagName("div");
var firstDiv = divs[0];

forEach.call(firstDiv.childNodes, function (divChild) {
  divChild.parentNode.style.color = "#0F0";
});
```

**备注：** 请注意，在上面的代码中，将某个宿主对象（如 `NodeList`）作为 `this` 传递给原生方法（如 forEach）不能保证在所有浏览器中工作，已知在一些浏览器中会失败。

规范
--

| Specification |
| --- |
| DOM Standard # interface-nodelist |

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

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


HTMLScriptElement - Web API 接口参考

HTMLScriptElement
=================

HTML 脚本元素暴露 HTMLScriptElement 接口，它提供了特殊的属性和方法 (超出了常规 HTMLElement 对象接口，他们也可以通过继承操纵<脚本>元素的布局和演示。）

属性
--

*从其父类中继承的属性，`HTMLElement`。*

| Name | Type | Description |
| --- | --- | --- |
| `type` | `DOMString` | 代表了脚本的 MIME 类型。它反映了 `type` 属性。如何解析奇异的编程语言，请阅读这篇文章。 |
| `src` | `DOMString` | 代表了使用外部脚本资源的地址。它反映了 `src` 属性。 |
| `htmlFor`
已弃用
 | `DOMString` | 他 htmlFor 属性设置或返回的值的属性标签。属性指定的表单元素绑定到一个标签。 |
| `event`
已弃用
 | `DOMString` | HTML DOM 事件允许 JavaScript 注册不同的事件处理程序的元素在一个 HTML 文档。 |
| `charset` | `DOMString` | 代表外部脚本资源的字符编码。它反映了 `charset` 属性。 |
| `async` | `Boolean` (en-US) | **async 和 defer 属性值为 bool，它用来说明 script 脚本应该如何执行。在没有 src 属性的情况下，async 和 defer 属性可以不指定值。**
使用该属性有三种模式可供选择，如果 async 属性存在，脚本将异步执行，只要它是可用的，如果 async 属性不存在，而 defer 属性存在，脚本将会在页面完成解析后执行，如果都不存在，那么脚本会在 useragent 解析页面之前被取出并立刻执行。

**备注：**这些属性的具体处理细节非常复杂，涉及 HTML
 的许多不同方面，因此分散在整个规范中。这些算法描述了核心思想，但它们依赖于 HTML、外部内容和 XML 中
`<script>` 开始和结束标记的解析规则；`document.write()` 方法的规则；脚本处理等等。

延迟属性可以指定即使指定异步属性，导致遗留 Web 浏览器只支持推迟（而不是异步）回落推迟行为而不是同步阻塞是默认的行为。 |
| `defer` | `Boolean` (en-US) |
| `crossOrigin`

实验性
 | `DOMString` | 反馈该脚本元素 CORS 设置的字符串。对其他源的脚本，此属性控制错误信息的暴露情况。 |
| `text` | `DOMString` | 一个字符串，用于按树形顺序连接并返回 `<script>` 元素（忽略注释等其他节点）内所有文本节点 (en-US)的内容。在设置时，它的作用与 `textContent` IDL 属性相同。

**备注：**当插入使用
 `document.write()` 方法，`<script>`
 元素执行（通常是同步），但当插入使用 innerHTML 和 outerHTML 属性，它们不执行。
  |

方法
--

*没有具体的方法；属性从其父类 `HTMLElement` 继承。*

示例
--

### 动态导入脚本

让我们创建一个名为 importScript 的函数，它能够在一个文档中导入新的脚本，创建一个 `<script>` 节点，并立即插入到宿主 `<script>` 之前（通过 `document.currentScript` 可以获取宿主 script 标签）。这些脚本将**异步**执行。更多细节，请参见 defer 和 async 属性。

```js
function loadError(oError) {
  throw new URIError("The script " + oError.target.src + " is not accessible.");
}

function importScript(sSrc, fOnload) {
  var oScript = document.createElement("script");
  oScript.type = "text/javascript";
  oScript.onerror = loadError;
  if (fOnload) {
    oScript.onload = fOnload;
  }
  document.currentScript.parentNode.insertBefore(
    oScript,
    document.currentScript,
  );
  oScript.src = sSrc;
}
```

以下函数不是将新脚本直接插入在 `document.currentScript` 元素之前，而是将它们作为 `<head>` 标签的子节点追加。

```js
var importScript = (function (oHead) {
  function loadError(oError) {
    throw new URIError(
      "The script " + oError.target.src + " is not accessible.",
    );
  }

  return function (sSrc, fOnload) {
    var oScript = document.createElement("script");
    oScript.type = "text/javascript";
    oScript.onerror = loadError;
    if (fOnload) {
      oScript.onload = fOnload;
    }
    oHead.appendChild(oScript);
    oScript.src = sSrc;
  };
})(document.head || document.getElementsByTagName("head")[0]);
```

示例用法：

```js
importScript("myScript1.js");
importScript(
  "myScript2.js",
  /\* onload function: \*/ function () {
    alert(
      'You read this alert because the script "myScript2.js" has been correctly loaded.',
    );
  },
);
```

规范
--

| Specification |
| --- |
| HTML Standard # htmlscriptelement |

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

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

参见
--

* HTML `<script>` 元素
* HTML `<noscript>` 元素
* `document.currentScript`
* Web Worker（代码片段与脚本类似，但在另外一个全局上下文中执行）


Web Storage API - Web API 接口参考

Web Storage API
===============

**Web Storage API** 提供了浏览器可以存储键/值对的机制，其方式比使用 cookie 更直观。

Web Storage 概念和用法
-----------------

Web Storage 包含如下两种机制：

* `sessionStorage` 为每一个给定的源（origin）维持一个独立的存储区域，该存储区域在页面会话期间可用（即只要浏览器处于打开状态，包括页面重新加载和恢复）。
    + 仅为会话存储数据，这意味着数据将一直存储到浏览器（或选项卡）关闭。
    + 数据永远不会被传输到服务器。
    + 存储限额大于 cookie（最大 5MB）。
* `localStorage` 做同样的事情，但即使浏览器关闭并重新打开也仍然存在。
    + 存储的数据没有过期日期，只能通过 JavaScript、清除浏览器缓存或本地存储的数据来清除。
    + 存储限额是两者之间的最大值。

这两种机制是通过 `Window.sessionStorage` 和 `Window.localStorage` 属性使用（更确切的说，在支持的浏览器中 `Window` 对象实现了 `WindowLocalStorage` 和 `WindowSessionStorage` 对象并挂在其 `localStorage` 和 `sessionStorage` 属性下）——调用其中任一对象会创建 `Storage` 对象，通过 `Storage` 对象，可以设置、获取和移除数据项。对于每个源 `sessionStorage` 和 `localStorage` 使用不同的 Storage 对象——独立运行和控制。

**备注：** 在 Firefox 中，当浏览器崩溃或重新启动时，为了避免过度使用 Web storage 导致的内存问题，每个源的存储大小将限制在 10M。有关详细信息，请参阅存储配额和清理标准。

**备注：** 若用户禁用第三方 cookie，那么将不允许来自第三方 IFrame 对 Web Storage 的访问。

Web Storage 接口
--------------

`Storage`

允许你在一个特定域中设置、检索和删除数据和储存类型（session 或 local）。

`Window`

Web Storage API 继承于 `Window` 对象，并提供两个新属性——`Window.sessionStorage` 和 `Window.localStorage`——分别地提供对当前域的会话和本地 `Storage` 对象的访问。以及当存储区域改变时触发的 `storage` 事件处理器（例如，存储新的项）。

`StorageEvent`

当一个存储区域发生变化时，在文档的 `Window` 对象上触发 `storage` 事件。

示例
--

为了阐述一些典型的 web storage 的用法，我们创了一个简单的例子，想象上地称为 Web Storage 演示。着陆页提供了可以用来自定义颜色、字体和装饰图片的控件。当你选择不同的选项，页面会被立即更新；此外，你的选择将被储存到 `localStorage` 中，以便当你离开该页面，然后过些时候在重新加载它时，你的选择会被记住。

另外，我们还提供了一个事件输出页面——如果你在另一个标签页加载这个页面，然后在着陆页改变你的选择，你将看到在触发 `StorageEvent` 时输出更新后的存储信息。

规范
--

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

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

### api.Window.localStorage

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

### api.Window.sessionStorage

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

隐私浏览/隐身模式
---------

隐私窗口、隐身模式和类似名称的隐私浏览选项不会存储历史记录和 cookie 等数据。在隐身模式下，`localStorage` 被视为 `sessionStorage`。存储 API 仍然可用且功能齐全，但是当浏览器或浏览器选项卡关闭时，所有存储在隐私窗口中的数据都会被删除。

参见
--

* 使用 Web Storage API
* 浏览器存储限制和清理标准


AudioContext - Web API 接口参考

AudioContext
============

`AudioContext`接口表示由链接在一起的音频模块构建的音频处理图，每个模块由一个`AudioNode`表示。音频上下文控制它包含的节点的创建和音频处理或解码的执行。在做任何其他操作之前，你需要创建一个`AudioContext`对象，因为所有事情都是在上下文中发生的。建议创建一个`AudioContext`对象并复用它，而不是每次初始化一个新的`AudioContext`对象，并且可以对多个不同的音频源和管道同时使用一个`AudioContext`对象。

EventTarget

BaseAudioContext

(en-US)

AudioContext构造函数
----

`AudioContext()`

创建并返回一个新的 `AudioContext` 对象。

属性
--

*也从其父接口继承属性，`BaseAudioContext` (en-US).*

`AudioContext.baseLatency` (en-US) 只读
实验性

返回`AudioContext`将音频从`AudioDestinationNode`传递到音频子系统的处理延迟的秒数。

`AudioContext.outputLatency` (en-US) 只读
实验性

返回对当前音频上下文的预估输出延迟。

方法
--

*也从其父接口继承方法 , `BaseAudioContext` (en-US).*

`AudioContext.close()`

关闭一个音频环境，释放任何正在使用系统资源的音频。

`AudioContext.createMediaElementSource()`

创建一个`MediaElementAudioSourceNode`接口来关联`HTMLMediaElement`. 这可以用来播放和处理来自`<video>`或`<audio>` 元素的音频。

`AudioContext.createMediaStreamSource()`

创建一个`MediaStreamAudioSourceNode`接口来关联可能来自本地计算机麦克风或其他来源的音频流`MediaStream`。

`AudioContext.createMediaStreamDestination()` (en-US)

创建一个`MediaStreamAudioDestinationNode` (en-US)接口来关联可能储存在本地或已发送至其他计算机的`MediaStream`音频。

`AudioContext.createMediaStreamTrackSource()` (en-US)

创建一个`MediaStreamTrackAudioSourceNode` (en-US)，它与一个`MediaStream`相关联，表示一个媒体流轨迹。

`AudioContext.getOutputTimestamp()` (en-US)

返回一个新的 AudioTimestamp 对象，该对象包含两个与当前音频上下文相关的音频时间戳。

`AudioContext.resume()`

恢复之前被暂停的音频上下文中的时间进程。

`AudioContext.suspend()`

暂停音频上下文中的时间进程，暂停音频硬件访问并减少进程中的 CPU/电池使用。

例子
--

简单声明：

```js
var audioCtx = new AudioContext();
```

跨浏览器的方式：
```

var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();

var oscillatorNode = audioCtx.createOscillator();
var gainNode = audioCtx.createGain();
var finish = audioCtx.destination;
// etc.
```

规范
--

| Specification |
| --- |
| Web Audio API # AudioContext |

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

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

参见
--

* 使用 Web Audio API (en-US)
* `OfflineAudioContext`


atob() - Web API 接口参考

atob()
======

**`atob()`** 对经过 base-64 编码的字符串进行解码。你可以使用 `window.btoa()` 方法来编码一个可能在传输过程中出现问题的数据，并且在接受数据之后，使用 atob() 方法再将数据解码。例如：你可以编码、传输和解码操作各种字符，比如 0-31 的 ASCII 码值。

关于针对 Unicode 或者 UTF-8 的应用方面，请查看 this note at Base64 encoding and decoding (en-US) 和 `btoa()` 的备注。

语法
--
```

var decodedData = scope.atob(encodedData);
```

### 异常

如果传入字符串不是有效的 base64 字符串，比如其长度不是 4 的倍数，则抛出`DOMException`。

示例
--

```js
let encodedData = window.btoa("Hello, world"); // 编码
let decodedData = window.atob(encodedData); // 解码
```

规范
--

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

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

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

参见
--

* Base64 encoding and decoding
* `data` URIs
* `btoa()`
* Components.utils.importGlobalProperties


MediaStreamEvent - Web API 接口参考

MediaStreamEvent
================

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

**`MediaStreamEvent`** 接口表示发生在 `MediaStream`中的事件。这种类型返回两个事件：`addstream` 和 `removestream` (en-US).

Properties
----------

*一个 `MediaStreamEvent` 作为一个 `Event`，该事件也实现了这些属性。*

`MediaStreamEvent.stream` (en-US) 只读

包含了 `MediaStream` 以及相关的事件流。

Constructors
------------

`MediaStreamEvent()` (en-US)

返回一个新的 `MediaStreamEvent`. 它需要两个参数，第一个为 `DOMString` 代表事件的类型；第二个是一个 `MediaStream` 集合。

Methods
-------

*一个 `MediaStreamEvent` 作为一个 `Event`, 这个事件也实现了这些属性*. *没有特定的 *`MediaStreamEvent`* 方法。*

示例
--

```js
pc.onaddstream = function (ev) {
  alert(
    "A stream (id: '" + ev.stream.id + "') has been added to this connection.",
  );
};
```

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

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

参见
--

* WebRTC
* 它的常见目标：`RTCPeerConnection`。


AbortSignal - Web API 接口参考

AbortSignal
===========

**`AbortSignal`** 接口表示一个信号对象（signal object），它允许你通过 `AbortController` 对象与 DOM 请求（如 Fetch）进行通信并在需要时将其中止。

属性
--

*AbortSignal 接口还继承了其父接口 `EventTarget` 的属性。*

`AbortSignal.aborted` 只读

一个 `Boolean` (en-US)，表示与之通信的请求是否被终止（`true`）或未终止（`false`）。

`AbortSignal.reason` 只读

一旦信号被中止，提供一个使用 JavaScript 值表示的中止原因。

方法
--

***`AbortSignal`** 接口继续它父接口 `EventTarget` 的方法。*

`AbortSignal.throwIfAborted()`

如果信号已经被中止，则抛出信号中止的 `reason`；否则没有任何用处。

静态方法
----

`AbortSignal.abort()`

返回一个已经被设置为中止的 **`AbortSignal`** 实例。

`AbortSignal.timeout()`

返回一个在指定事件后将自动终止的 **`AbortSignal`** 实例。

### 事件

使用 `addEventListener()` 或将事件监听器分配给该接口的 `oneventname` 属性。

`abort`

当与 signal 通信 DOM 请求被中止时调用。也可以通过 `onabort` 属性调用。

示例
--

### 使用显式的信号终止 fetch 操作

以下片段展示了我们如何使用 signal 去中止使用 Fetch API 下载视频。

我们首先使用 `AbortController()` 创建一个中止控制器，然后使用 `AbortController.signal` 属性获取与它关联的 `AbortSignal` 对象的引用。

当 fetch 请求开始时，我们将 `AbortSignal` 作为一个选项传递进请求的 option 对象中（见下面的 `{signal}`）。这个将信号和控制器与 fetch 请求相关联，并且允许我们通过调用 `AbortController.abort()` 中止它。你可以看见当中止按钮（`abortBtn`）被点击时，第二个事件监听器触发，使 fetch 操作被中止。

```js
const controller = new AbortController();
const signal = controller.signal;

const url = "video.mp4";
const downloadBtn = document.querySelector(".download");
const abortBtn = document.querySelector(".abort");

downloadBtn.addEventListener("click", fetchVideo);

abortBtn.addEventListener("click", () => {
  controller.abort();
  console.log("Download aborted");
});

function fetchVideo() {
  fetch(url, { signal })
    .then((response) => {
      console.log("Download complete", response);
    })
    .catch((err) => {
      console.error(`Download error: ${err.message}`);
    });
}
```

**备注：** 当调用 `abort()` 时，`fetch()` promise 会以“`AbortError`”`DOMException` 拒绝。

你可以在 GitHub 上找到一个完整、可运行的示例；你也可以参见在线演示。

### 中止超时的读取操作

如果你需要中止一个超时的操作，你可以使用 `AbortSignal.timeout()` 静态方法。该方法返回一个 `AbortSignal` 并在指定的毫秒时间后后自动超时。

以下代码片段展示了如何成功地下载一个文件或者在五秒钟后处理一个超时的错误。注意，当出现超时时，`fetch()` promise 会以“`TimeoutError`”`DOMException` 拒绝。这允许代码区分超时（可能需要通知用户）和用户中止。

```js
const url = "video.mp4";

try {
  const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
  const result = await res.blob();
  // …
} catch (err) {
  if (err.name === "TimeoutError") {
    console.error("Timeout: It took more than 5 seconds to get the result!");
  } else if (err.name === "AbortError") {
    console.error(
      "Fetch aborted by user action (browser stop button, closing tab, etc.",
    );
  } else if (err.name === "TypeError") {
    console.error("AbortSignal.timeout() method is not supported");
  } else {
    // A network error, or some other problem.
    console.error(`Error: type: ${err.name}, message: ${err.message}`);
  }
}
```

### 超时或显式中止 fetch

`fetch()` 不是为了组合多个信号而设计的，所以你不能因为调用了 `AbortController.abort()` 或者 `AbortSignal` 超时而"直接"中止下载（尽管在上面的例子中，超时信号中止由停止按钮等内置浏览器机制触发）。

为了触发多个 signal，它们必须是菊花链式连接。以下代码片段展示了在处理程序中如何为独立的计时器调用 `AbortController.abort()`。

```js
try {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 5000);
  const res = await fetch(url, { signal: controller.signal });
  const body = await res.json();
} catch (e) {
  if (e.name === "AbortError") {
    // Notify the user of abort.
    // Note this will never be a timeout error!
  } else {
    // A network error, or some other problem.
    console.log(`Type: ${e.name}, Message: ${e.message}`);
  }
} finally {
  clearTimeout(timeoutId);
}
```

**备注：** 与使用 `AbortSignal.timeout()` 不同，没有方法来判断最终中止是否由超时引起。

规范
--

| Specification |
| --- |
| DOM Standard # interface-AbortSignal |

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

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

参见
--

* Fetch API
* Abortable Fetch by Jake Archibald


AudioParamDescriptor - Web API 接口参考

AudioParamDescriptor
====================

The **`AudioParamDescriptor`** dictionary of the Web Audio API specifies properties for an `AudioParam` objects. It is used to create custom `AudioParam`s on an `AudioWorkletNode`. If the underlying `AudioWorkletProcessor` has a `parameterDescriptors` (en-US) static getter, then the returned array of objects based on this dictionary is used internally by `AudioWorkletNode` constructor to populate its `parameters` (en-US) property accordingly.

属性
--

`name`

The `DOMString` which represents the name of the `AudioParam`. Under this name the `AudioParam` will be available in the `parameters` (en-US) property of the node, and under this name the `AudioWorkletProcessor.process` (en-US) method will acquire the calculated values of this `AudioParam`.

`automationRate` 可选

Either `"a-rate"`, or `"k-rate"` string which represents an automation rate of this `AudioParam`. Defaults to `"a-rate"`.

`minValue` 可选

A `float` which represents minimum value of the `AudioParam`. Defaults to `-3.4028235e38`.

`maxValue` 可选

A `float` which represents maximum value of the `AudioParam`. Defaults to `3.4028235e38`.

`defaultValue` 可选

A `float` which represents initial value of the `AudioParam`. Defaults to `0`.

示例
--

下面的代码片段展示了自定义的 `AudioWorkletProcessor` 中的静态方法 `parameterDescriptors` (en-US) 返回该类型的描述符（这是 AudioWorkletNode.parameters (en-US) 中完整示例的一部分）。

```js
// white-noise-processor.js
class WhiteNoiseProcessor extends AudioWorkletProcessor {
  static get parameterDescriptors() {
    return [
      {
        name: "customGain",
        defaultValue: 1,
        minValue: 0,
        maxValue: 1,
        automationRate: "a-rate",
      },
    ];
  }

  // …
}
```

规范
--

#### No specification found

No specification data found for `api.AudioParamDescriptor`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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


FileSystemDirectoryEntry - Web API 接口参考

FileSystemDirectoryEntry
========================

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

文件和目录条目 API 的 **`FileSystemDirectoryEntry`** 接口表示文件系统中的目录。它提供了方法，使其能够访问和操作目录中的文件，以及访问目录中的条目。

**备注：** 由于这是个非标准的 API，它的规范当前并没有在标准进程中，重要的是要记住，并不是所有浏览器都实现了他，并且实现它的浏览器可能仅仅实现了一小部分。更多细节请查看 Browser compatibility 。

基本概念
----

你可以通过调用 `getDirectory()` (en-US) 创建新的目录。如果你打算创建子目录，按需创建每个子目录。如果你尝试使用完整路径创建目录，包含不存在的父目录，会返回错误。所以需要在创建父目录之后，递归添加新的路径来创建层次。

### 示例

下面的代码中，我们创建了一个叫做 "Documents" 的目录。

```js
// Taking care of the browser-specific prefixes.
window.requestFileSystem  = window.requestFileSystem || window.webkitRequestFileSystem;
window.directoryEntry = window.directoryEntry || window.webkitDirectoryEntry;

...

function onFs(fs){
  fs.root.getDirectory('Documents', {create:true}, function(directoryEntry){
    //directoryEntry.isFile === false
    //directoryEntry.isDirectory === true
    //directoryEntry.name === 'Documents'
    //directoryEntry.fullPath === '/Documents'

    }, onError);

  }

// Opening a file system with temporary storage
window.requestFileSystem(TEMPORARY, 1024\*1024 /\*1MB\*/, onFs, onError);
```

属性
--

这个接口没有自己的属性，但是从它的父接口 `FileSystemEntry` (en-US) 继承了属性。

方法
--

这个接口从它的父接口 `FileSystemEntry` (en-US) 继承了方法。

`createReader()` (en-US)

创建 `FileSystemDirectoryReader` (en-US) 对象，它可以用于服务目录中的条目。

`getDirectory()` (en-US)

返回 `FileSystemDirectoryEntry` 对象，表示位于给定路径的目录，相对于方法调用处的目录。

`getFile()` (en-US)

返回 `FileSystemFileEntry`对象，表示在目录层次中的一个文件，提供相对于方法调用处目录的路径。

### 废弃的方法

`removeRecursively()` (en-US)

删除目录和所有内容，包含子目录的内容。它已经从规范中移除。

规范
--

| Specification |
| --- |
| File and Directory Entries API # api-directoryentry |

这个 API 没有官方的 W3C 或者 WHATWG 规范。

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

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

另见
--

* 文件和目录条目 API
* 文件系统 API 简介
* `FileSystemDirectoryReader` (en-US)
* `FileSystemEntry` (en-US)
* `FileSystemFileEntry`


CountQueuingStrategy - Web API 接口参考

CountQueuingStrategy
====================

Streams API 的 **`CountQueuingStrategy`** 接口提供了一个内置的、用于对分块进行计数的队列策略，可以在构造流的时候使用。

构造函数
----

`CountQueuingStrategy()`

创建一个新的 `CountQueuingStrategy` 对象实例。

实例属性
----

`CountQueuingStrategy.highWaterMark` 只读

在应用背压之前，内部队列可以包含的分块总数。

实例方法
----

`CountQueuingStrategy.size()`

返回 `1`。

示例
--

```js
const queueingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });

const writableStream = new WritableStream(
  {
    // Implement the sink
    write(chunk) {
      // …
    },
    close() {
      // …
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queueingStrategy,
);

const size = queueingStrategy.size();
```

规范
--

| Specification |
| --- |
| Streams Standard # cqs-class |

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

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

参见
--

* Stream API
* `CountQueuingStrategy()` 构造函数
* 内置队列和队列策略


ResizeObserver - Web API 接口参考

ResizeObserver
==============

**`ResizeObserver`** 接口监视 `Element` 内容盒或边框盒或者 `SVGElement` 边界尺寸的变化。

**备注：** 内容盒是盒模型放置内容的部分，这意味着边框盒减去内边距和边框的宽度就是内容盒。边框盒包含内容、内边距和边框。有关进一步阐述，参见盒模型。

`ResizeObserver` 避免了通过回调函数调整大小时，通常创建的无限回调循环和循环依赖项。它只能通过在后续的帧中处理 DOM 中更深层次的元素来做到这一点。如果它的实现遵循规范，则应在绘制前和布局后调用 resize 事件。

构造函数
----

`ResizeObserver()`

创建并返回一个新的 `ResizeObserver` 对象。

属性
--

无。

方法
--

`ResizeObserver.disconnect()`

取消特定观察者目标上所有对 `Element` 的监听。

`ResizeObserver.observe()`

开始对指定 `Element` 的监听。

`ResizeObserver.unobserve()`

结束对指定 `Element` 的监听。

示例
--

在 resize-observer-text.html（见源码）示例中，我们使用 resize observer 去更改头和段落的 `font-size`，随着 slider 的值被改变，也引起了包含的 `<div>` 的宽度改变。这展示了你可以响应元素大小的变化，即使它们与视口无关。

我们也提供了一个 checkbox 来关闭和打开 observer。如果它是关闭的，文本将不会随着 `<div>` 的宽度改变而改变。

JavaScript 看起来像这样：

```js
const h1Elem = document.querySelector("h1");
const pElem = document.querySelector("p");
const divElem = document.querySelector("body > div");
const slider = document.querySelector('input[type="range"]');
const checkbox = document.querySelector('input[type="checkbox"]');

divElem.style.width = "600px";

slider.addEventListener("input", () => {
  divElem.style.width = `${slider.value}px`;
});

const resizeObserver = new ResizeObserver((entries) => {
  for (const entry of entries) {
    if (entry.contentBoxSize) {
      // Firefox implements `contentBoxSize` as a single content rect, rather than an array
      const contentBoxSize = Array.isArray(entry.contentBoxSize)
        ? entry.contentBoxSize[0]
        : entry.contentBoxSize;

      h1Elem.style.fontSize = `${Math.max(
 1.5,
 contentBoxSize.inlineSize / 200,
 )}rem`;
      pElem.style.fontSize = `${Math.max(
 1,
 contentBoxSize.inlineSize / 600,
 )}rem`;
    } else {
      h1Elem.style.fontSize = `${Math.max(
 1.5,
 entry.contentRect.width / 200,
 )}rem`;
      pElem.style.fontSize = `${Math.max(1, entry.contentRect.width / 600)}rem`;
    }
  }

  console.log("Size changed");
});

resizeObserver.observe(divElem);

checkbox.addEventListener("change", () => {
  if (checkbox.checked) {
    resizeObserver.observe(divElem);
  } else {
    resizeObserver.unobserve(divElem);
  }
});
```

规范
--

| Specification |
| --- |
| Resize Observer # resize-observer-interface |

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

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

参见
--

* 盒模型
* `PerformanceObserver`
* `IntersectionObserver`（Intersection Observer API 的一部分）


CacheStorage - Web API 接口参考

CacheStorage
============

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

**`CacheStorage`** 接口表示 `Cache` 对象的存储。它提供了一个 `ServiceWorker` 、其他类型 worker 或者 `window` 范围内可以访问到的所有命名 cache 的主目录（它并不是一定要和 service workers 一起使用，即使它是在 service workers 规范中定义的），并维护一份字符串名称到相应 `Cache` 对象的映射。

`CacheStorage` 同样暴露了 `CacheStorage.open()` 和 `CacheStorage.match()`方法。使用 `CacheStorage.open()` 获取 `Cache` 实例。使用 `CacheStorage.match()` 检查给定的 `Request` 是否是 `CacheStorage` 对象跟踪的任何 `Cache` 对象中的键。

你可以通过 `caches` (en-US) 属性访问 `CacheStorage` .

**备注：** CacheStorage 总是对不受信任的源（即那些不使用 HTTPS，尽管此定义将来很可能变得更加复杂。）使用 `SecurityError` reject. 测试时，你可以在 Firefox Devtools 选项/齿轮菜单中通过选中"通过 HTTP 启用 Service Workers (当工具箱打开时)" 选项来绕开这个限制。

**备注：** `CacheStorage.match()` 是一个便捷方法。匹配 cache 条目的同等功能可以通过执行 `CacheStorage.open()` 打开 cache，使用 `CacheStorage.keys()` 返回它包含的条目，并将你所需的条目与 `CacheStorage.match()` 匹配。

方法
--

`CacheStorage.match()`

检查给定的 `Request` 是否是 `CacheStorage` 对象跟踪的任何 `Cache` 对象的键，并返回一个 resolve 为该匹配的 `Promise` .

`CacheStorage.has()`

如果存在与 `cacheName` 匹配的 `Cache` 对象，则返回一个 resolve 为 true 的 `Promise` .

`CacheStorage.open()`

返回一个 `Promise` ，resolve 为匹配 `cacheName` （如果不存在则创建一个新的 cache）的 `Cache` 对象

`CacheStorage.delete()`

查找匹配 `cacheName` 的 `Cache` 对象，如果找到，则删除 `Cache` 对象并返回一个 resolve 为 true 的 `Promise` 。如果没有找到 `Cache` 对象，则返回 `false`.

`CacheStorage.keys()`

返回一个 `Promise` ，它将使用一个包含与 `CacheStorage` 追踪的所有命名 `Cache` 对象对应字符串的数组来 resolve. 使用该方法迭代所有 `Cache` 对象的列表。

示例
--

此代码片段来自于 MDN sw-test example （请参阅sw-test running live.）此 service worker 脚本等待 `InstallEvent` 触发，然后运行 `waitUntil` 来处理应用程序的安装过程。这包括调用 `CacheStorage.open` 创建一个新的 cache，然后使用 `Cache.addAll` 向其添加一系列资源。

在第二个代码块，我们等待 `FetchEvent` 触发。我们构建自定义相应，像这样：

1. 检查 CacheStorage 中是否找到了匹配请求的内容。如果是，使用匹配内容。
2. 如果没有，从网络获取请求，然后同样打开第一个代码块中创建的 cache，并使用 `Cache.put` (`cache.put(event.request, response.clone())`.) 将请求的 clone 副本添加到它。
3. 如果此操作失败（例如，因为网络关闭），返回备用相应。

最后，使用 `FetchEvent.respondWith` 返回自定义响应最终等于的内容。

```js
this.addEventListener("install", function (event) {
  event.waitUntil(
    caches.open("v1").then(function (cache) {
      return cache.addAll([
        "/sw-test/",
        "/sw-test/index.html",
        "/sw-test/style.css",
        "/sw-test/app.js",
        "/sw-test/image-list.js",
        "/sw-test/star-wars-logo.jpg",
        "/sw-test/gallery/bountyHunters.jpg",
        "/sw-test/gallery/myLittleVader.jpg",
        "/sw-test/gallery/snowTroopers.jpg",
      ]);
    }),
  );
});

this.addEventListener("fetch", function (event) {
  var response;
  event.respondWith(
    caches
      .match(event.request)
      .catch(function () {
        return fetch(event.request);
      })
      .then(function (r) {
        response = r;
        caches.open("v1").then(function (cache) {
          cache.put(event.request, response);
        });
        return response.clone();
      })
      .catch(function () {
        return caches.match("/sw-test/gallery/myLittleVader.jpg");
      }),
  );
});
```

说明
--

| Specification |
| --- |
| Service Workers # cachestorage-interface |

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

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

参见
--

* Using Service Workers (en-US)
* `Cache`
* `WorkerGlobalScope.caches` (en-US)


全屏 API - Web API 接口参考

全屏 API
======

**`全屏 API`** 为使用用户的整个屏幕展现网络内容提供了一种简单的方式，并且在不需要时退出全屏模式。这种 API 让你可以简单地控制浏览器，使得一个元素与其子元素，如果存在的话，可以占据整个屏幕，并在此期间，从屏幕上隐藏所有的浏览器用户界面以及其他应用。

可以在全屏 API 指南这篇文章了解更多细节。

**备注：** 当前并不是所有的浏览器都支持该 API，大多数浏览器需要使用供应商前缀或者尚未实现该规范。下面的浏览器兼容性表 Browser compatibility 可以看到各个浏览器对此的支持（你也可以使用 Fscreen 来提供跨浏览器 API 访问）。

接口
--

全屏 API 没有它自己的接口实现。相反，它提供了一些其他接口以供实现全屏所需的方法、属性、事件处理函数。接下来会列出所有细节。

方法
--

全屏 API 在 `Document` 和 `Element` 接口中增加了一些方法，可用于允许打开关闭全屏模式。

### Document 中的方法

`Document.exitFullscreen()`

用于请求从全屏模式切换到窗口模式，会返回一个 `Promise`，会在全屏模式完全关闭的时候被置为 resolved 状态。

### Element 中的方法

`Element.requestFullscreen()`

请求浏览器（user agent）将特定元素（甚至延伸到它的后代元素）置为全屏模式，隐去屏幕上的浏览器所有 UI 元素，以及其他应用。返回一个 `Promise`，并会在全屏模式被激活的时候变成 resolved 状态。

属性
--

*`Document` 提供了可以用于判断是否支持和启用全屏模式的属性，也能得知现在是否处在全屏模式、哪一个元素在使用屏幕等信息。*

`DocumentOrShadowRoot.fullscreenElement`

`fullscreenElement` 属性提供了当前在 DOM（或者 shadow DOM）里被展示为全屏模式的 `Element`，如果这个值为 `null`，文档不处于全屏模式。

`Document.fullscreenEnabled`

`fullscreenEnabled` 属性提供了启用全屏模式的可能性。当它的值是 `false` 的时候，表示全屏模式不可用（可能的原因有 `"fullscreen"` 特性不被允许，或全屏模式不被支持等）。

### 事件处理程序

Fullscreen API 定义了两个事件，可用于检测全屏模式的打开和关闭，以及在全屏和窗口模式之间切换过程中发生的错误。*`Document`* 和 *`Element`* 接口提供了这些事件的事件处理函数。

**备注：** 这些事件处理函数特性不可以当成 HTML 内容属性来使用。换句话说，你无法在 HTML 内容中为 `fullscreenchange` 和 `fullscreenerror` 指定事件处理程序，你必须通过 JavaScript 代码添加它们。

#### Document 上的事件处理程序

`Document.onfullscreenchange`

`fullscreenchange` 事件的处理程序，当进入全屏或退出全屏时，事件将被发送到`Document`上。此处理程序仅在整个文档全屏模式更改时有效。

`Document.onfullscreenerror`

`fullscreenerror` 事件的处理程序，当进入全屏或退出全屏出错时，事件将被发送到 `Document` 上，仅对整个文档的全屏模式更改出错时候有效。

#### Element 上的事件处理程序

`Element.onfullscreenchange`

当全屏事件发生时，该事件会被发送到该元素，表明该元素进入或退出全屏模式

`Element.onfullscreenerror`

`fullscreenerror` 事件的处理程序，当指定的 `Element` 改变全屏模式时候出现错误，该事件将被发送到指定的 `Element` 上。

### 废弃属性

`Document.fullscreen`
已弃用

一个布尔值，文档内任意一个元素以全屏模式程序时该值为`true`，否则为 `false`。

**备注：** 请改用 `ShadowRoot` 或 `Document` 上的 `fullscreenElement` 属性；如果它不是 null，则它是就是当前在全屏模式下显示的元素。

事件
--

全屏 API 定义了两个事件：1.可用来检测全屏模式何时打开和关闭。2.在全屏模式和窗口模式之间切换过程中何时发生错误。

`fullscreenchange`

当全屏或退出全屏时发送消息给（监听的）的 `Document` 或 `Element` 。

`fullscreenerror`

当全屏或退出全屏是发生了错误时，将错误消息发送给（监听的）的 `Document` 或 `Element` 。

Dictionaries
------------

`FullscreenOptions` (en-US)

在调用 `requestFullscreen()` 时可以设置选项。

访问控制
----

全屏模式可由功能策略（ Feature Policy）控制。全屏模式功能由字符串“full screen”标识，默认的允许列表值为“self”，这意味着在顶级文档上下文 以及 从与顶级文档相同的源加载的嵌套上下文中允许使用全屏模式。

请参阅使用功能策略（Feature Policy）以了解有关使用功能策略控制对 API 的访问的更多信息。

使用说明
----

用户通过按 `ESC` 键（或 `F11`）即可退出全屏模式，而不是等着站点或应用的代码来做这件事。确定你在你的用户界面里提供合适的界面元素来告知用户这个可选项。

**备注：** 当处在全屏模式中，浏览其他页面，切换标签页，或者切换到其他应用（例如使用 `Alt`-`Tab`）也会导致退出全屏模式。

示例
--

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

查看在线演示

### 监听 `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()`（或其前缀化的版本，这取决于你使用的浏览器）。

规范
--

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenelement① |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |
| Fullscreen API Standard # ref-for-dom-document-exitfullscreen① |
| Fullscreen API Standard # ref-for-dom-element-requestfullscreen① |
| Fullscreen API Standard # dom-document-fullscreen |

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

### api.Document.fullscreenElement

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

### api.Document.fullscreenEnabled

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

### api.Document.exitFullscreen

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

### api.Element.requestFullscreen

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.

参见
--

* Using fullscreen mode
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`, `::backdrop`
* `allowfullscreen`


Pointer Lock API - Web API 接口参考

Pointer Lock API
================

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

**指针锁定**(以前叫做鼠标锁定) 提供了一种输入方法，这种方法是基于鼠标随着时间推移的运动的（也就是，deltas），而不仅是鼠标光标的绝对位置。通过它可以访问原始的鼠标运动，把鼠标事件的目标锁定到一个单独的元素，这就消除了鼠标在一个单独的方向上到底可以移动多远这方面的限制，并从视图中删去光标。

这个 API 对于需要大量的鼠标输入来控制运动，旋转物体，以及更改项目的应用程序来说非常有用。对高度视觉化的应用程序尤其重要，例如那些使用第一人称视角的应用程序，以及 3D 视图和建模。

举例来说，你可以创建让你的用户简单地通过移动鼠标而不需要点击任何按钮就可以控制视角的应用。那么这些按钮就可以被用作其他动作。这类鼠标输入对于查看地图，卫星图像，或者第一人称场景（例如在一个游戏中或者一个全景视频中）是非常方便使用的。

即使在光标移到浏览器或者屏幕区域之外，指针锁定也能够让你访问鼠标事件。例如，你的用户可以通过不断地移动鼠标来持续旋转或操纵一个 3D 模型。如果没有指针锁定的话，这些旋转或操纵会在指针到达浏览器或者屏幕边缘的那一刻停止。尤其是游戏玩家将会因为此功能而兴奋不已，因为他们可以疯狂地点击按钮，来回地滑动鼠标光标，而不必担心离开了游戏区域，进而不小心误点到另外一个应用程序上，结果将鼠标焦点移离了游戏。杯具了！

基本概念
----

指针锁定和鼠标捕获有关。鼠标捕获在一个鼠标被拖曳时可以向一个目标元素持续传递有关事件，但是当鼠标按钮被放开时就会停止。指针锁定和鼠标捕获在以下方面有所不同：

* 它是持久性的。指针锁定不释放鼠标，直到作出一个显式的 API 调用或是用户使用一个专门的释放手势。
* 它不局限于浏览器或者屏幕边界。
* 它持续发送事件，而不管鼠标按钮状态如何。
* 它隐藏光标。
示例
--

下面是一个如何在你的网页中设置指针锁定的示例。

```js
<button onclick="lockPointer();">锁住它！</button>
<div id="pointer-lock-element"></div>
<script>
// 注意：截止本文撰写时，仅有 Mozilla 和 WebKit 支持指针锁定。

// 我们将要使之全屏并指针锁定的元素。
var elem;

document.addEventListener("mousemove", function(e) {
  var movementX = e.movementX       ||
                  e.mozMovementX    ||
                  e.webkitMovementX ||
                  0,
      movementY = e.movementY       ||
                  e.mozMovementY    ||
                  e.webkitMovementY ||
                  0;

  // 打印鼠标移动的增量值。
  console.log("movementX=" + movementX, "movementY=" + movementY);
}, false);

function fullscreenChange() {
  if (document.webkitFullscreenElement === elem ||
      document.mozFullscreenElement === elem ||
      document.mozFullScreenElement === elem) { // 较旧的 API 大写 'S'.
    // 元素进入全屏模式了，现在我们可以请求指针锁定。
    elem.requestPointerLock = elem.requestPointerLock    ||
                              elem.mozRequestPointerLock ||
                              elem.webkitRequestPointerLock;
    elem.requestPointerLock();
  }
}

document.addEventListener('fullscreenchange', fullscreenChange, false);
document.addEventListener('mozfullscreenchange', fullscreenChange, false);
document.addEventListener('webkitfullscreenchange', fullscreenChange, false);

function pointerLockChange() {
  if (document.mozPointerLockElement === elem ||
      document.webkitPointerLockElement === elem) {
    console.log("指针锁定成功了。");
  } else {
    console.log("指针锁定已丢失。");
  }
}

document.addEventListener('pointerlockchange', pointerLockChange, false);
document.addEventListener('mozpointerlockchange', pointerLockChange, false);
document.addEventListener('webkitpointerlockchange', pointerLockChange, false);

function pointerLockError() {
  console.log("锁定指针时出错。");
}

document.addEventListener('pointerlockerror', pointerLockError, false);
document.addEventListener('mozpointerlockerror', pointerLockError, false);
document.addEventListener('webkitpointerlockerror', pointerLockError, false);

function lockPointer() {
  elem = document.getElementById("pointer-lock-element");
  // 开始于使元素进入全屏模式。目前的实现
  // 要求元素在请求指针锁定前要处于全屏模式下
  // -- 这在以后可能会发生改变。
  elem.requestFullscreen = elem.requestFullscreen    ||
                           elem.mozRequestFullscreen ||
                           elem.mozRequestFullScreen || // 较旧的 API 把‘S’大写
                           elem.webkitRequestFullscreen;
  elem.requestFullscreen();
}
</script>
```

方法/属性 概述
--------

Pointer lock API，和 Fullscreen API 类似，通过添加新方法来扩展 DOM 元素，`requestPointerLock`, 目前还是厂商前缀。按下面这样来写：

```js
element.webkitRequestPointerLock(); // Chrome

element.mozRequestPointerLock(); // Firefox
```

目前 `requestPointerLock` 的实现还是和 `requestFullScreen` 以及 Fullscreen API 紧紧地绑在一起的。一个元素在能够被指针锁定之前，必须首先进入全屏模式。就像上面演示的那样，锁定指针的过程是异步的，使用 (`pointerlockchange`, `pointerlockerror`) 事件来表明请求是成功还是失败了。这和 Fullscreen API 的工作方式是一致的，它使用 `requestFullScreen` 方法，以及 `fullscreenchange` 和 `fullscreenerror` 事件。

Pointer lock API 还扩展了 `document` 接口，添加了一个新的属性和一个新的方法。新的属性被用于访问当前被锁定的元素（如果有的话），并被命名为 `pointerLockElement`，目前也使用厂商前缀。 `document` 添加的新方法是 `exitPointerLock` ，顾名思义，它是用来退出指针锁定的。

`pointerLockElement` 属性适用于确定当前是否有被指针锁定的元素（例如，用来做一个布尔检查），以及当有元素被锁定时获取该元素的一个引用。下面是这两种用法的一个例子：

```js
document.pointerLockElement =
  document.pointerLockElement ||
  document.mozPointerLockElement ||
  document.webkitPointerLockElement;

// 1) 用于布尔检查 -- 我们被指针锁定了吗？
if (!!document.pointerLockElement) {
  // 指针被锁定
} else {
  // 指针未被锁定
}

// 2) 用于访问指针锁定的元素
if (document.pointerLockElement === someElement) {
  // someElement 当前被指针锁定
}
```

`document` 的 `exitPointerLock` 方法被用来退出指针锁定，而且和 requestPointerLock 一样，使用 `pointerlockchange` 和 `pointerlockerror`事件以异步方式工作：

```js
document.exitPointerLock =
  document.exitPointerLock ||
  document.mozExitPointerLock ||
  document.webkitExitPointerLock;

function pointerLockChange() {
  document.pointerLockElement =
    document.pointerLockElement ||
    document.mozPointerLockElement ||
    document.webkitPointerLockElement;

  if (!!document.pointerLockElement) {
    console.log("目前还是被锁定。");
  } else {
    console.log("已经退出锁定。");
  }
}

document.addEventListener("pointerlockchange", pointerLockChange, false);
document.addEventListener("mozpointerlockchange", pointerLockChange, false);
document.addEventListener("webkitpointerlockchange", pointerLockChange, false);

// 试图解除锁定
document.exitPointerLock();
```

pointerlockchange 事件
--------------------

当指针锁定状态改变时 - 例如，当调用 `requestPointerLock`, `exitPointerLock`，用户按下 ESC 键，等等。— `pointerlockchange` 事件被分发到 `document`。这是一个简单事件所以不包含任何的额外数据。

**备注：** 该事件目前在 Firefox 中使用前缀的格式是 `mozpointerlockchange` ，在 Chrome 中是 `webkitpointerlockchange`。

pointerlockerror 事件
-------------------

当调用 `requestPointerLock` 或 `exitPointerLock`而引发错误时， `pointerlockerror` 事件被分发到 `document`。这是一个简单事件所以不包含任何的额外数据。

**备注：** 该事件目前在 Firefox 中被加上前缀为 `mozpointerlockerror` ，在 Chrome 中为 `webkitpointerlockerror`。

鼠标事件扩展
------

Pointer lock API 使用 movement 属性扩展了标准的 `MouseEvent`。

```webidl
partial interface MouseEvent {
    readonly attribute long movementX;
    readonly attribute long movementY;
};
```

**备注：** movement 属性目前在 Firefox 中被加上前缀为 `.mozMovementX` 和 `.mozMovementY` , 在 Chrome 中为`.webkitMovementX` 和 `.webkitMovementY`。

鼠标事件的两个新参数—`movementX` 和 `movementY`—提供了鼠标位置的变化情况。这两个参数的值，等于两个`MouseEvent` 属性（ `screenX` 和 `screenY）`之间值的变化程度，这些 MouseEvent 属性被存储在两个连续的鼠标移动事件（ `eNow` 和 `ePrevious`）中。换言之，指针锁定参数 `movementX = eNow.screenX - ePrevious.screenX`。（译注：不存在名为 eNow 或 ePrevious 的事件或属性，eNow 代指当前的鼠标移动事件，ePrevious 代指前一个鼠标移动事件）

### 锁定状态

当指针锁定被启动之后，正常的 `MouseEvent` 属性 `clientX`, `clientY`, `screenX`, 和 `screenY` ，保持不变，就像鼠标没有在移动一样。 `movementX` 和 `movementY` 属性持续提供鼠标的位置变化。如果鼠标在一个方向上持续移动，`movementX` 和 `movementY`的值是没有限制的。不存在鼠标光标的概念，而且光标无法移到窗口之外，而且也不会被屏幕边缘所固定。

### 未锁定状态

无论鼠标锁定状态是怎样的， `movementX` 和 `movementY` 参数一直有效，并且为了方便起见，甚至在未锁定状态也是有效的。

当鼠标被解除锁定，系统光标可以退出并重新进入浏览器窗口。如果发生这种情况，`movementX` 和 `movementY` 可能会被设置成 0。

iframe 的限制
----------

指针锁定一次只能锁定一个 iframe。如果你锁定了一个 iframe，你不能试图锁定另外一个 iframe 然后把目标转移到这个 iframe 上；指针锁定将会出错。为了避免这一问题，首先解锁那个锁定的 iframe，然后再锁定另外一个。

在 iframe 默认的情况下， "sandboxed" iframes 会阻止指针锁定。避免这种限制的能力，即以属性/值 `<iframe sandbox="allow-pointer-lock">` 组合的形式 , 有望很快在 Chrome 中出现。

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

### api.Document.exitPointerLock

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

### api.Element.requestPointerLock

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

参见
--

W3C Pointer Lock API Specification

MouseEvent


HTMLImageElement - Web API 接口参考

HTMLImageElement
================

**`HTMLImageElement`** 接口提供了特别的属性和方法 (在常规的 `HTMLElement`之外，它也能通过继承使用) 来操纵 `<img>` 元素的布局和图像。

Constructor
-----------

`Image()`

`Image()` 构造器，带有两个可选的参数，分别表示资源的宽度和高度，创建了一个尚未被插入 DOM 树中的 `HTMLImageElement` 实例。When called without parameters, `new Image()` is equivalent to calling `document.createElement("img")`.

属性
--

*从它的父元素 `HTMLElement` 继承的属性。*

`HTMLImageElement.alt` (en-US)

一个 `DOMString` 表示 HTML 属性 `alt`，表明图像的后备描述内容，会在图像无法加载时显示。

`HTMLImageElement.complete` (en-US) 只读

返回一个 `Boolean` (en-US) 如果浏览器已经下载完毕，并且图像是受支持的图片类型 (en-US)、解码的过程中没有发生错误，则返回 `true`。That means this value is also `true` if the image has no `src` (en-US) value indicating an image to load.

`HTMLImageElement.crossOrigin` (en-US)

一个 `DOMString` 表示这个 img 元素的 CORS 设置。参考 CORS settings attributes (en-US)。This may be `null` if CORS is not used.

`HTMLImageElement.currentSrc` (en-US) 只读

 返回一个 `DOMString` 表示加载当前显示的图像的 URL。
 这可能会改变，因为图像是调整，由于不断变化的条件，由任何 media queries 的地方。

`HTMLImageElement.decoding`

An optional `DOMString` representing a hint given to the browser on how it should decode the image. If this value is provided, it must be one of the possible permitted values: `sync` to decode the image synchronously, `async` to decode it asynchronously, or `auto` to indicate no preference (which is the default). Read the `decoding` page for details on the implications of this property's values.

`HTMLImageElement.height` (en-US)

一个整数，表示 HTML 属性 `height`，说明了图像在 CSS 像素中渲染的高度。

`HTMLImageElement.isMap` (en-US)

一个 `Boolean` (en-US) 表示 HTML 属性 `ismap`，说明了图像是某个服务器端图像映射的一部分。This is different from a client-side image map, specified using an `<img>` element and a corresponding `<map>` which contains `<area>` elements indicating the clickable areas in the image. The image *must* be contained within an `<a>` element; see the `ismap` page for details.

`HTMLImageElement.naturalHeight` 只读

返回一个整数，如果可用的话，表明图像在 CSS 中固有的高度，单位为像素；否则返回 `0`。如果图片是以其原来的大小渲染，则此值等于图片的高度。

`HTMLImageElement.naturalWidth` (en-US) 只读

返回一个整数，如果可用的话，表明图像在 CSS 中固有的宽度，单位为像素；否则返回 `0`。如果图片是以其原来的大小渲染，则此值等于图片的宽度。

`HTMLImageElement.referrerPolicy`

A `DOMString` that reflects the `referrerpolicy` HTML attribute, which tells the user agent how to decide which referrer to use in order to fetch the image. Read this article for details on the possible values of this string.

`HTMLImageElement.sizes` (en-US)
实验性

A `DOMString` reflecting the `sizes` HTML attribute. This string specifies a list of comma-separated conditional sizes for the image; that is, for a given viewport size, a particular image size is to be used. Read the documentation on the `sizes` (en-US) page for details on the format of this string.

`HTMLImageElement.src` (en-US)

一个 `DOMString` 表示 HTML 属性 `src`，包含图像的完整的 URL，包含图像的基础 URL。

`HTMLImageElement.srcset`
实验性

一个 `DOMString` 表示 HTML 属性 `srcset`，包含了候选图像列表，用逗号分隔（`',', U+002C COMMA`）。一个候选的图像是一个 URL 跟着一个 `'w'` 表示图像的宽度，或者一个 `'x'` 表示像素密度。

`HTMLImageElement.useMap` (en-US)

一个 `DOMString` 表示 HTML 属性 `usemap`，包含一个 `<map>` 元素的页面本地 URL。The page-local URL is a pound (hash) symbol (`#`) followed by the ID of the `<map>` element, such as `#my-map-element`. The `<map>` in turn contains `<area>` elements indicating the clickable areas in the image.

`HTMLImageElement.width` (en-US)

一个整数，表示 HTML 属性 `width`，说明图像在 CSS 像素中渲染的宽度。

`HTMLImageElement.x` (en-US) 只读
实验性

An integer indicating the horizontal offset of the left border edge of the image's CSS layout box relative to the origin of the `<html>` element's containing block.

`HTMLImageElement.y` (en-US) 只读
实验性

The integer vertical offset of the top border edge of the image's CSS layout box relative to the origin of the `<html>` element's containing block.

已废弃的属性
------

`HTMLImageElement.align` (en-US)
已弃用

一个 `DOMString`，表示图像如何与它周围的内容对齐。The possible values are `"left"`, `"right"`, `"justify"`, and `"center"`. This is obsolete; you should instead use CSS (such as `text-align`, which works with images despite its name) to specify the alignment.

`HTMLImageElement.border` (en-US)
已弃用

一个 `DOMString`，表示图像边框的宽度。此属性已被弃用，应该用 CSS `border` 属性来代替它。

`HTMLImageElement.hspace` (en-US)
已弃用

一个整数值，指定图像左右的留白，单位为像素。

`HTMLImageElement.longDesc` (en-US)
已弃用

一个 `USVString`，specifying the URL at which a long description of the image's contents may be found. This is used to turn the image into a hyperlink automatically. Modern HTML should instead simply place an `<img>` inside an `<a>` element defining the hyperlink.

`HTMLImageElement.lowSrc`
已弃用

一个 `USVString`，specifying the URL of a low-quality (but faster to load) version of the same image. This was once used by browsers under constrained network conditions or on slow devices.

`HTMLImageElement.name` (en-US)
已弃用

一个 `DOMString`，representing the name of the element.

`HTMLImageElement.vspace` (en-US)
已弃用

一个整数值，指定图像上下的留白，单位为像素。

方法
--

*从它的父元素 `HTMLElement` 继承的方法。*

`HTMLImageElement.decode()`

Returns a `Promise` that resolves when the image is decoded and it's safe to append the image to the DOM. This prevents rendering of the next frame from having to pause to decode the image, as would happen if an undecoded image were added to the DOM.

错误
--

* The `src` attribute is empty or `null`.
* The specified `src` URL is the same as the URL of the page the user is currently on.
* The specified image is corrupted in some way that prevents it from being loaded.
* The specified image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the `<img>` element's attributes.
* The specified image is in a format not supported by the user agent.

If an error occurs while trying to load or render the image, and an `onerror` event handler has been configured to handle the `error` event, that event handler will get called. This can happen in a number of situations, including:

例子
--

```js
var img1 = new Image(); // Image 构造器
img1.src = "image1.png";
img1.alt = "alt";
document.body.appendChild(img1);

var img2 = document.createElement("img"); // 使用 DOM HTMLImageElement
img2.src = "image2.jpg";
img2.alt = "alt text";
document.body.appendChild(img2);

// 使用文档中的第一个 img
alert(document.images[0].src);
```

规范
--

| Specification |
| --- |
| HTML Standard # htmlimageelement |

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

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

参见
--

* 实现了这个接口的 HTML 元素：`<img>`


Element - Web API 接口参考

Element
=======

**`Element`** 是最通用的基类，`Document` 中的所有元素对象（即表示元素的对象）都继承自它。它只具有各种元素共有的方法和属性。更具体的类则继承自 `Element`。

例如，`HTMLElement` 接口是所有 HTML 元素的基本接口。同样，`SVGElement` 接口是所有 SVG 元素的基本接口，而 `MathMLElement` 接口则是 MathML 元素的基础接口。大多数功能是在这个类的更深层级的接口中被进一步制定的。

在 Web 平台的领域以外的语言，比如 XUL，通过 `XULElement` 接口，同样也实现了 `Element` 接口。

EventTarget

Node

Element实例属性
----

*`Element` 从其父接口 `Node` 以及该接口的父接口 `EventTarget` 继承属性。*

`Element.assignedSlot` (en-US) 只读

返回一个表示节点所插入的 `<slot>` 的 `HTMLSlotElement` 值。

`Element.attributes` 只读

返回一个 `NamedNodeMap` 对象，其中包含相应 HTML 元素的指定属性。

`Element.childElementCount` 只读

返回此元素的子元素个数。

`Element.children` 只读

返回此元素的子元素。

`Element.classList` 只读

返回该元素包含的所有 class 属性，是一个 `DOMTokenList`。

`Element.className`

一个字符串，表示这个元素的类。

`Element.clientHeight` 只读

返回代表元素内部高度的数值。

`Element.clientLeft` 只读

返回代表元素左边界宽度的数值。

`Element.clientTop` 只读

返回代表元素顶部边框宽度的数值。

`Element.clientWidth` 只读

返回代表元素内部宽度的数值。

`Element.elementTiming` (en-US)
实验性

一个字符串，反映了 `elementtiming` (en-US) 属性，该属性在 `PerformanceElementTiming` (en-US) API 中标记了一个观察元素。

`Element.firstElementChild` 只读

返回此元素的第一个子元素。

`Element.id`

一个字符串，表示此元素的 id 值。

`Element.innerHTML`

一个字符串，表示元素内容标记。

`Element.lastElementChild` 只读

返回此元素的最后一个子元素。

`Element.localName` 只读

一个字符串，代表元素限定名称的本地部分。

`Element.namespaceURI` 只读

元素对应的命名空间 URI，如果没有则返回 `null`。

**备注：** 在 Firefox 3.5 及更早版本中，HTML 元素不在命名空间中。在以后的版本中，HTML 元素在 HTML 树和 XML 树中都属于 `http://www.w3.org/1999/xhtml` 命名空间。

`Element.nextElementSibling` 只读

一个 `Element`，树中紧跟给定元素的元素，如果没有同级节点，则为 `null`。

`Element.outerHTML`

一个字符串，代表元素的标记（包括其内容）。作为 setter 使用时，将用从给定字符串解析出的节点替换元素。

`Element.part` (en-US)

代表元素的部分标识符（即使用 `part` 属性设置的标识符），以 `DOMTokenList` 的形式返回。

`Element.prefix` 只读

代表元素命名空间前缀的字符串，如果没有指定前缀，则为 `null`。

`Element.previousElementSibling` 只读

一个 `Element`，树中紧靠给定元素的元素，如果没有同级元素，则为 `null`。

`Element.scrollHeight` 只读

元素滚动视图高度的数值。

`Element.scrollLeft`

元素左滚动偏移量的数值。

`Element.scrollLeftMax`
非标准
 只读

元素可能的最大左滚动偏移值。

`Element.scrollTop`

元素顶部垂直滚动的像素数。

`Element.scrollTopMax`
非标准
 只读

元素可能的最大顶部滚动偏移值。

`Element.scrollWidth` 只读

代表元素滚动视图宽度的数值。

`Element.shadowRoot` 只读

返回元素挂载的开放影子根；如果没有开放影子根，则返回 null。

`Element.slot`

返回元素插入的影子 DOM 插槽的名称。

`Element.tagName` 只读

返回一个字符串，包含给定元素的标签名称。

### ARIA 中包含的实例属性

*`Element` 接口包括以下在 `ARIAMixin` 混入中定义的属性。*

`Element.ariaAtomic` (en-US)

反映 `aria-atomic` (en-US) 属性的字符串，表示辅助技术是否将根据 `aria-relevant` (en-US) 属性定义的变更通知，显示全部或仅部分变更区域。

`Element.ariaAutoComplete` (en-US)

反映 `aria-autocomplete` (en-US) 属性的字符串，表示输入文本是否会触发显示一个或多个用户对组合框、搜索框或文本框的预期值的预测，并指定如果进行了预测将如何显示。

`Element.ariaBusy` (en-US)

反映 `aria-busy` (en-US) 属性的字符串，表示元素是否正在被修改，因为辅助技术可能希望等到修改完成后再向用户展示。

`Element.ariaChecked` (en-US)

反映 `aria-checked` (en-US)属性的字符串，表示复选框、单选按钮和其他具有选中状态的部件的当前“选中”状态。

`Element.ariaColCount` (en-US)

反映 `aria-colcount` (en-US) 属性的字符串，该属性定义了表格、网格或树状网格中的列数。

`Element.ariaColIndex` (en-US)

反映 `aria-colindex` (en-US) 属性的字符串，该属性定义了元素的列索引或相对于表格、网格或树状网格中列总数的位置。

`Element.ariaColIndexText` (en-US)
实验性

反映 `aria-colindextext` (en-US) 属性的字符串，该属性定义了 aria-colindex 的人类可读文本替代。

`Element.ariaColSpan` (en-US)

反映 `aria-colspan` (en-US) 属性的字符串，该属性定义了表格、网格或树型网格中单元格或网格单元格所跨列数。

`Element.ariaCurrent` (en-US)

反映 `aria-current` (en-US) 属性的字符串，表示在一个容器或一组相关元素中代表当前项目的元素。

`Element.ariaDescription` (en-US)

反映 `aria-description` (en-US) 属性的字符串，该属性定义了描述或注释当前元素的字符串值。

`Element.ariaDisabled` (en-US)

反映 `aria-disabled` (en-US) 属性的字符串，表示该元素可感知但已禁用，因此不可编辑或以其他方式操作。

`Element.ariaExpanded` (en-US)

反映 `aria-expanded` (en-US) 属性的字符串，表示该元素拥有或控制的分组元素是展开还是折叠状态。

`Element.ariaHasPopup` (en-US)

反映 `aria-haspopup` (en-US) 属性的字符串，表示可由元素触发的交互式弹出元素（如菜单或对话框）的可用性和类型。

`Element.ariaHidden` (en-US)

反映 `aria-hidden` 属性的字符串，表示元素是否暴露于无障碍 API。

`Element.ariaKeyShortcuts` (en-US)

反映 `aria-keyshortcuts` (en-US) 属性的字符串，表示作者为激活元素或将焦点赋予元素而实施的键盘快捷方式。

`Element.ariaLabel` (en-US)

反映 `aria-label` 属性的字符串，该属性定义了标示当前元素的字符串值。

`Element.ariaLevel` (en-US)

反映 `aria-level` (en-US) 属性的字符串，该属性定义了结构中元素的层次级别。

`Element.ariaLive`

反映 `aria-live` (en-US) 属性的字符串，表示元素将被更新，并描述了用户代理、辅助技术和用户可期望从实时区域获得的更新类型。

`Element.ariaModal` (en-US)

反映 `aria-modal` (en-US) 属性的字符串，表示元素在显示时是否为模态元素。

`Element.ariaMultiline` (en-US)

反映 `aria-multiline` (en-US) 属性的字符串，表示文本框是接受多行输入还是只接受单行输入。

`Element.ariaMultiSelectable` (en-US)

反映 `aria-multiselectable` (en-US) 属性的字符串，表示用户可以从当前可选后代中选择多个项目。

`Element.ariaOrientation` (en-US)

反映 `aria-orientation` (en-US) 属性的字符串，表示元素的方向是水平、垂直还是未知/模糊。

`Element.ariaPlaceholder` (en-US)

反映 `aria-placeholder` (en-US) 属性的字符串，它定义了一个简短的提示，目的是在控件无值时帮助用户输入数据。

`Element.ariaPosInSet` (en-US)

反映 `aria-posinset` (en-US) 属性的字符串，它定义了元素在当前列表项或树状项集合中的编号或位置。

`Element.ariaPressed` (en-US)

反映 `aria-pressed` (en-US) 属性的字符串，表示切换按钮当前的“按下”状态。

`Element.ariaReadOnly` (en-US)

反映 `aria-readonly` (en-US) 属性的字符串，表示该元素不可编辑，但在其他方面是可操作的。

`Element.ariaRelevant` (en-US)
非标准

反映 `aria-relevant` (en-US) 属性的字符串，表示当实时区域内的无障碍树被修改时，用户代理将触发哪些通知。该属性用于描述 `aria-live` 区域中哪些变化是相关的，应予以公布。

`Element.ariaRequired` (en-US)

`aria-required` (en-US) 属性的字符串，表示在提交表单前需要用户输入。

`Element.ariaRoleDescription` (en-US)

反映 `aria-roledescription` (en-US) 属性的字符串，它定义了一个元素的角色的人类可读、作者本地化描述。

`Element.ariaRowCount` (en-US)

反映 `aria-rowcount` (en-US) 属性的字符串，该属性定义了表格、网格或树状网格中的总行数。

`Element.ariaRowIndex` (en-US)

反映 `aria-rowindex` (en-US) 属性的字符串，它定义了元素的行索引或相对于表格、网格或树状网格中总行数的位置。

`Element.ariaRowIndexText` (en-US)
实验性

反映 `aria-rowindextext` (en-US) 属性的字符串，它定义了 aria-rowindex 的人类可读文本替代。

`Element.ariaRowSpan` (en-US)

反映 `aria-rowspan` (en-US) 属性的字符串，该属性定义了表格、网格或树型网格中单元格或网格单元格所跨行数。

`Element.ariaSelected` (en-US)

反映 `aria-selected` (en-US) 属性的字符串，表示具有选定状态的元素的当前“选定”状态。

`Element.ariaSetSize` (en-US)

反映 `aria-setsize` (en-US) 属性的字符串，该属性定义了当前列表项或树状项集合中的项数。

`Element.ariaSort` (en-US)

反映 `aria-sort` (en-US) 属性的字符串，表示表格或网格中的项目是按升序还是降序排序。

`Element.ariaValueMax` (en-US)

反映 `aria-valueMax` (en-US) 属性的字符串，该属性定义了范围部件允许的最大值。

`Element.ariaValueMin` (en-US)

反映 `aria-valueMin` (en-US) 属性的字符串，该属性定义了范围部件的最小允许值。

`Element.ariaValueNow` (en-US)

反映 `aria-valueNow` (en-US) 属性的字符串，该属性定义了范围部件的当前值。

`Element.ariaValueText` (en-US)

反映 `aria-valuetext` (en-US) 属性的字符串，该属性为范围部件定义了 aria-valuenow 的人类可读文本替代值。

实例方法
----

*`Element` 继承 `Node` 及其父接口 `EventTarget` 的方法。*

`Element.after()`

在 `Element` 父节点的子节点列表中插入一组 `Node` 对象或字符串，位于 `Element` 之后。

`Element.animate()`

在元素上创建并运行动画的快捷方法。返回创建的动画对象实例。

`Element.append()`

在元素的最后一个子元素后插入一组 `Node` 对象或字符串。

`Element.attachShadow()`

为指定元素附加影子 DOM 树，并返回指向其 `ShadowRoot` 的引用。

`Element.before()`

在 `Element` 父节点的子节点列表中插入一组 `Node` 对象或字符串，位于 `Element` 之前。

`Element.closest()`

返回 `Element` 当前元素（或当前元素本身）最接近的祖先，且与参数中给定的选择器匹配。

`Element.computedStyleMap()` (en-US)

返回一个 `StylePropertyMapReadOnly` (en-US) 接口，该接口提供 CSS 声明块的只读表示，可替代 `CSSStyleDeclaration`。

`Element.getAnimations()` (en-US)

返回元素当前活动的动画对象数组。

`Element.getAttribute()`

从当前节点读取指定属性的值，并以字符串形式返回。

`Element.getAttributeNames()`

返回当前元素的属性名称数组。

`Element.getAttributeNode()`

从当前节点获取指定属性的节点表示，并以 `Attr` 的形式返回。

`Element.getAttributeNodeNS()`

从当前节点读取指定名称和命名空间的属性的节点表示，并以 `Attr` 的形式返回。

`Element.getAttributeNS()` (en-US)

从当前节点读取指定名称空间和名称的属性值，并以字符串形式返回。

`Element.getBoundingClientRect()`

返回元素的大小及其相对于视口的位置。

`Element.getBoxQuads()`
实验性

返回代表节点 CSS 片段的 `DOMQuad` 对象列表。

`Element.getClientRects()`

返回表示客户端中每行文本边界矩形的矩形集合。

`Element.getElementsByClassName()`

返回一个实时的 `HTMLCollection`，其中包含当前元素的所有后代，这些后代拥有参数中给定的类列表。

`Element.getElementsByTagName()`

返回一个实时的 `HTMLCollection`，其中包含当前元素的特定标签名的所有后代元素。

`Element.getElementsByTagNameNS()`

返回一个实时的 `HTMLCollection`，其中包含当前元素的特定标签名和命名空间的所有后代元素。

`Element.hasAttribute()`

返回一个布尔值，表示元素是否具有指定属性。

`Element.hasAttributeNS()`

返回一个布尔值，表示元素是否在指定名称空间中具有指定属性。

`Element.hasAttributes()`

返回一个布尔值，表示元素是否具有一个或多个 HTML 属性。

`Element.hasPointerCapture()` (en-US)

指示调用该函数的元素是否具有指针捕获功能，用于捕获由给定指针 ID 标识的指针。

`Element.insertAdjacentElement()`

将指定元素节点插入调用该函数的元素的指定位置。

`Element.insertAdjacentHTML()`

解析 HTML 或 XML 文本，并将生成的节点插入树中指定的位置。

`Element.insertAdjacentText()`

将给定的文本节点插入调用该函数的元素的指定位置。

`Element.matches()`

返回一个布尔值，表示该元素是否会被指定的选择器字符串选中。

`Element.prepend()`

在元素的第一个子元素之前插入一组 `Node` 对象或字符串。

`Element.querySelector()`

返回相对于元素符合指定选择器字符串的第一个 `Node`。

`Element.querySelectorAll()`

返回 `NodeList` 中相对于元素符合指定选择器字符串的节点。

`Element.releasePointerCapture()` (en-US)

释放（停止）之前为特定`指针事件`设置的指针捕捉。

`Element.remove()`

从父元素的子元素列表中删除该元素。

`Element.removeAttribute()`

从当前节点删除指定属性。

`Element.removeAttributeNode()`

从当前节点删除指定属性的节点表示。

`Element.removeAttributeNS()`

从当前节点删除指定名称和命名空间的属性。

`Element.replaceChildren()`

用一组指定的新子节点替换 `Node` 的现有子节点。

`Element.replaceWith()`

用一组 `Node` 对象或字符串替换父元素子元素列表中的元素。

`Element.requestFullscreen()`

异步要求浏览器全屏显示元素。

`Element.requestPointerLock()`

允许异步请求锁定给定元素上的指针。

`Element.scroll()`

滚动到指定元素内部的特定坐标。

`Element.scrollBy()`

以给定数值滚动元素。

`Element.scrollIntoView()`

滚动页面，直到元素进入视图。

`Element.scrollIntoViewIfNeeded()`
非标准

如果当前元素尚未进入浏览器窗口的可见区域，则将其滚动到浏览器窗口的可见区域。**请使用标准的 `Element.scrollIntoView()`。**

`Element.scrollTo()`

滚动到指定元素内部的特定坐标。

`Element.setAttribute()`

设置当前节点的指定属性值。

`Element.setAttributeNode()`

设置当前节点指定属性的节点表示形式。

`Element.setAttributeNodeNS()`

设置当前节点具有指定名称和命名空间的属性的节点表示形式。

`Element.setAttributeNS()`

设置当前节点指定名称和命名空间的属性值。

`Element.setCapture()`
非标准

已弃用

设置鼠标事件捕获，将所有鼠标事件重定向到此元素。

`Element.setHTML()`
实验性

解析和净化 (en-US) HTML 字符串，并插入到 DOM 作为元素的子树。

`Element.setPointerCapture()`

指定一个特定的元素作为未来指针事件的捕获目标。

`Element.toggleAttribute()`

在指定的元素上切换布尔属性，如果存在则删除它，如果不存在则添加它。

事件
--

使用 `addEventListener()` 或将事件监听器分配给此接口的 `oneventname` 属性来监听这些事件。

`afterscriptexecute`
非标准

执行脚本时触发此事件。

`beforematch` (en-US)
实验性

浏览器在（处于*被找到前隐藏*状态的）元素因用户已通过“在页面中查找”功能或片段导航找到了该内容而即将显示时触发。

`beforescriptexecute`
非标准

脚本即将执行时触发此事件。

`contentvisibilityautostatechange`
实验性

当元素开始或停止与用户相关和跳过其内容时，触发任何设置了 `content-visibility: auto` 的元素。

`scroll`

当文档视图或元素滚动时触发此事件。

`scrollend` (en-US)

当文档视图完成滚动时触发此事件。

`securitypolicyviolation` (en-US)

当违反内容安全策略时触发此事件。

`wheel`

当用户旋转指向设备（通常是鼠标）上的滚轮按钮时触发此事件。

### 动画事件

`animationcancel`

当动画意外终止时触发此事件。

`animationend`

当动画正常结束时触发此事件。

`animationiteration`

当动画迭代完成时触发此事件。

`animationstart`

当动画开始时触发此事件。

### 剪贴板事件

`copy`

当用户通过浏览器的用户界面初始化复制操作时触发此事件。

`cut`

当用户通过浏览器的用户界面初始化剪切操作时触发此事件。

`paste`

当用户通过浏览器的用户界面初始化粘贴操作时触发此事件。

### 合成事件

`compositionend`

当文本合成系统（如输入法编辑器）完成或取消当前合成会话时触发此事件。

`compositionstart`

当文本合成系统（如输入法编辑器）开始新的合成会话时触发此事件。

`compositionupdate`

在文本合成系统（如输入法编辑器）控制的文本合成会话中收到新字符时触发此事件。

### 聚焦事件

`blur`

当元素失去焦点时触发此事件。

`focus`

当元素获得焦点时触发此事件。

`focusin` (en-US)

当元素获得焦点时触发此事件，位于 `focus` 事件之后。

`focusout`

当元素失去焦点时触发此事件，位于 `blur` 事件之后。

### 全屏事件

`fullscreenchange`

当前 `Element` 进入或退出全屏模式时发送给该元素。

`fullscreenerror`

如果在尝试将当前 `Element` 切换到或切换出全屏模式时发生错误，则向该 `Element` 发送该事件。

### 键盘事件

`keydown`

当按键按下时触发此事件。

`keypress`
已弃用

当按下可产生字符值的按键时触发此事件。

`keyup`

当按键释放时触发此事件。

### 鼠标事件

`auxclick`

当元素上的非主要指针设备按钮（例如除左键以外的任何鼠标按钮）被按下并释放时触发此事件。

`click`

指针设备按钮（如鼠标的主按钮）在单个元素上按下并释放时触发此事件。

`contextmenu`

当用户尝试打开上下文菜单时触发此事件。

`dblclick`

当指针设备按钮（如鼠标的主按钮）在单个元素上被点击两次时触发此事件。

`DOMActivate`
已弃用

元素被激活，例如通过鼠标点击或按键时触发此事件。

`DOMMouseScroll` (en-US)
已弃用

非标准

操作鼠标滚轮或类似设备，且自上次事件以来累计滚动量超过 1 行或 1 页时触发此事件。

`mousedown`

当元素上的指针设备按钮被按下时触发此事件。

`mouseenter`

当指针设备（通常是鼠标）移动到附加了监听器的元素上时触发此事件。

`mouseleave`

当指针设备（通常是鼠标）的指针移出附有监听器的元素时触发此事件。

`mousemove`

当指针设备（通常是鼠标）在元素上移动时触发此事件。

`mouseout`

当指针设备（通常是鼠标）离开监听器所连接的元素或其子元素时触发此事件。

`mouseover`

当指针设备移动到监听器所连接的元素上或其子元素上时触发此事件。

`mouseup`

当元素上的指针设备按钮被释放时触发此事件。

`mousewheel`
已弃用

非标准

操作鼠标滚轮或类似设备时触发此事件。

`MozMousePixelScroll` (en-US)
已弃用

非标准

操作鼠标滚轮或类似设备时触发此事件。

`webkitmouseforcechanged` (en-US)
非标准

每次触控板触摸屏上的压力发生变化时触发此事件。

`webkitmouseforcedown` (en-US)
非标准

在鼠标按下事件后，一旦施加了足够的压力，就会触发“强制点击”。

`webkitmouseforcewillbegin` (en-US)
非标准

在 `mousedown` 事件之前触发。

`webkitmouseforceup` (en-US)
非标准

在 `webkitmouseforcedown` (en-US) 事件之后，当压力充分减小以结束“强制点击”时触发。

### 指针事件

`gotpointercapture`

当元素使用 `setPointerCapture()` 捕捉指针时触发。

`lostpointercapture`

当捕获指针被释放时触发。

`pointercancel`

指针事件取消时触发。

`pointerdown`

指针变为活动状态时触发。

`pointerenter`

指针移动到元素或其子代的命中测试边界时触发。

`pointerleave`

当指针移出元素的命中测试边界时触发。

`pointermove`

指针改变坐标时触发。

`pointerout`

当指针移出元素的*命中测试*边界（以及其他原因）时触发。

`pointerover`

当指针移动到元素的命中测试边界时触发。

`pointerrawupdate` (en-US)
实验性

指针改变任何属性时触发，这些属性不会触发 `pointerdown` 或 `pointerup` 事件。

`pointerup`

指针不再处于活动状态时触发。

### 触摸事件

`gesturechange` (en-US)
非标准

触控手势期间数字移动时触发。

`gestureend` (en-US)
非标准

当不再有多个手指接触触摸表面时触发，从而结束手势。

`gesturestart` (en-US)
非标准

当多个手指接触触摸表面时触发，从而开始一个新手势。

`touchcancel`

当一个或多个触摸点以特定的实现方式受到破坏（例如，创建的触摸点过多）时触发。

`touchend`

当一个或多个触摸点从触摸表面移除时触发。

`touchmove`

当一个或多个触摸点沿触摸表面移动时触发。

`touchstart`

当一个或多个触摸点放置在触摸表面时触发。

### 过渡事件

`transitioncancel`

CSS 过渡被取消时触发的 `Event`。

`transitionend`

CSS 过渡结束播放时触发的 `Event`。

`transitionrun` (en-US)

当创建 CSS 过渡（即当它被添加到一组正在运行的过渡中时）时，一个 `Event` 会被触发，但不一定会被启动。

`transitionstart`

CSS 过渡开始过渡时触发的 `Event`。

规范
--

| Specification |
| --- |
| DOM Standard # interface-element |
| Pointer Events # extensions-to-the-element-interface |
| Pointer Lock 2.0 # extensions-to-the-element-interface |
| Fullscreen API Standard # api |
| DOM Parsing and Serialization # extensions-to-the-element-interface |
| CSSOM View Module # extension-to-the-element-interface |

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

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


WheelEvent - Web API 接口参考

WheelEvent
==========

**`WheelEvent`** 接口表示用户滚动鼠标滚轮或类似的输入设备时触发的事件。

**备注：** 该事件为标准规定的滚轮事件接口。早期的浏览器实现过 `MouseWheelEvent` 和 `MouseScrollEvent` 两种滚轮事件接口，但这两种接口皆非标准，加之各浏览器间对其兼容性极差。因而开发者应使用该标准事件接口取代这两个非标准接口。

**备注：** 不要混淆 `wheel` 事件和 `scroll` 事件。`wheel` 事件的默认动作取决于浏览器实现。因此 `wheel` 事件不一定会触发 `scroll` 事件。即便 `wheel` 事件引发了文档内容的滚动行为，也不表示 `wheel` 事件中的 `delta*` 值恰好反映文档内容的滚动方向。因此，不要依赖 `delta*` 属性获知文档内容的滚动方向。而应该在 `scroll` 事件中监听目标的 `scrollLeft` 和 `scrollTop` 的变化以推断滚动方向。

Event

UIEvent

MouseEvent

WheelEvent构造函数
----

`WheelEvent()` (en-US)

创建一个 `WheelEvent` 对象。

属性
--

*该接口继承了父接口 `MouseEvent`、`UIEvent` 和 `Event` 的属性。*

`WheelEvent.deltaX` 只读

返回一个 `double` 值，该值表示滚轮的横向滚动量。

`WheelEvent.deltaY` 只读

返回一个 `double` 值，该值表示滚轮的纵向滚动量。

`WheelEvent.deltaZ` 只读

返回一个 `double` 值，该值表示滚轮的 z 轴方向上的滚动量。

`WheelEvent.deltaMode` 只读

返回一个 `unsigned long` 值，该值表示上述各 `delta*` 的值的单位。允许的值如下：

| 常量 | 值 | 描述 |
| --- | --- | --- |
| `WheelEvent.DOM_DELTA_PIXEL` | `0x00` | `delta*` 的单位为像素。 |
| `WheelEvent.DOM_DELTA_LINE` | `0x01` | `delta*` 单位为行。每一次点击鼠标都会滚动一行内容，行高的计算取决于浏览器。 |
| `WheelEvent.DOM_DELTA_PAGE` | `0x02` | `delta*` 单位为页。每一次点击鼠标都会滚动一页内容。 |

`WheelEvent.wheelDelta` 只读
已弃用

返回一个整数（32 位），表示以像素为单位的距离。

`WheelEvent.wheelDeltaX` 只读
已弃用

返回一个整数，表示水平滚动量。

`WheelEvent.wheelDeltaY` 只读
已弃用

返回一个整数，表示垂直滚动量。

**备注：** 元素：mousewheel 事件有关于已弃用的属性（`wheelDelta`、`wheelDeltaX` 和 `wheelDeltaY`）的额外说明。

方法
--

*该接口本身未定义方法，但继承了父接口 `MouseEvent`、`UIEvent`、`Event` 的方法。*

规范
--

| Specification |
| --- |
| UI Events # interface-wheelevent |

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

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

参见
--

* `wheel` 事件
* 该接口取代的过时接口：
    + `MouseScrollEvent`（Gecko 内核浏览器）


HTMLHeadElement - Web API 接口参考

HTMLHeadElement
===============

**`HTMLHeadElement`** 接口包含一个文档的描述信息（或者称作元信息）这类对象继承了`HTMLElement`接口的全部属性和方法。

属性
--

*继承了父对象`HTMLElement`的属性。*

`HTMLHeadElement.profile`
已弃用

空格隔开的一个或多个用于表示元信息 URI 的`DOMString`。

方法
--

*没有特殊的方法；继承了父对象 `HTMLElement` 的方法。*

规范
--

| Specification |
| --- |
| HTML Standard # htmlheadelement |

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

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

另见
--

* 对应的 HTML 元素是根据 `<head>`实现。


StorageEvent - Web API 接口参考

StorageEvent
============

当前页面使用的 storage 被其他页面修改时会触发 StorageEvent 事件。

[译者：事件在同一个域下的不同页面之间触发，即在 A 页面注册了 storge 的监听处理，只有在跟 A 同域名下的 B 页面操作 storage 对象，A 页面才会被触发 storage 事件]

Event

StorageEvent

**备注：** 尽管这个事件已经早在 Gecko 2.0 时就已存在，但是并不符合规范。老的事件模型直到 `nsIDOMStorageEventObsolete` 确定才被表现出来。

方法描述
----
```

void initStorageEvent(
  in DOMString typeArg,
  in boolean canBubbleArg,
  in boolean cancelableArg,
  in DOMString keyArg,
  in DOMString oldValueArg,
  in DOMString newValueArg,
  in DOMString urlArg,
  in nsIDOMStorage storageAreaArg
);
```

属性
--

*除了下面列出的属性以外，`StorageEvent` 还继承了父接口 `Event` 的属性。*

`key` (en-US) 只读

被修改的键名。当被 `clear()` 方法清除后该属性值为 `null`。

`newValue` (en-US) 只读

修改后的新值。当被 `clear()` 方法清除或者从存储中移除该键值对时，`newValue` 的值为 `null` 。

`oldValue` (en-US) 只读

该键（`key`）在修改前的旧值。在添加新键值对时由于没有原始值，该属性值为 `null`。

`storageArea` (en-US) 只读

被操作的 `Storage` 对象。

`url` (en-US) 只读

`key` 发生改变的对象所在文档的 URL 地址。

方法
--

### initStorageEvent()

类似 DOM 中的初始化事件，即初始化新创建的 Storage 对象的属性。
```

void initStorageEvent(
  in DOMString typeArg,
  in boolean canBubbleArg,
  in boolean cancelableArg,
  in DOMString keyArg,
  in DOMString oldValueArg,
  in DOMString newValueArg,
  in DOMString urlArg,
  in nsIDOMStorage storageAreaArg
);
```

参数：

`typeArg`

事件名

`canBubbleArg`

布尔值，代表是否可以通过 dom 冒泡

`cancelableArg`

布尔值，代表是否可以注销事件

`keyArg`

事件结果时被改变的值对应的属性名称

`oldValueArg`

旧值

`newValueArg`

新值

`urlArg`

事件初始化时页面的 url

`storageAreaArg`

发生在哪个 storage 对象上

规范
--

| Specification |
| --- |
| HTML Standard # the-storageevent-interface |

参阅
--

* Specification


btoa() - Web API 接口参考

btoa()
======

**`btoa()`** 方法可以将一个*二进制字符串*（例如，将字符串中的每一个字节都视为一个二进制数据字节）编码为 Base64 编码的 ASCII 字符串。

你可以使用这个方法来对可能遇到通信问题的数据进行编码，然后使用 `atob()` 方法来对数据进行解码。例如，你可以对 ASCII 中的控制字符（值为 0 到 31 的字符）进行编码。

语法
--

```js
btoa(stringToEncode)
```

### 参数

`stringToEncode`

一个需要编码的*二进制字符串*。

### 返回值

一个包含 `stringToEncode` 的 Base64 表示的 ASCII 字符串。

### 异常

`InvalidCharacterError` `DOMException`

该字符串包含非单字节的字符。参见下方的“Unicode 字符串”。

示例
--

```js
const encodedData = btoa("Hello, world"); // 编码字符串
const decodedData = atob(encodedData); // 解码字符串
```

Unicode 字符串
-----------

`btoa()` 函数将一个 JavaScript 字符串作为其参数。而 JavaScript 字符串使用 UTF-16 字符编码表示：在这种编码中，字符串使用一串 16 比特（2 字节）的单元来表示。每一个 ASCII 字符会被填充到每个单元的第一个字节中，而很多其他的字符则不然。

根据设计，Base64 仅将二进制数据作为其输入。而在 JavaScript 字符串中，这意味着每个字符只能使用一个字节表示。所以，如果你将一个字符串传递给 `btoa()`，而其中包含了需要使用超过一个字节才能表示的字符，你就会得到一个错误，因为这个字符串不能被看作是二进制数据：

```js
const ok = "a";
console.log(ok.codePointAt(0).toString(16)); // 61：占用 < 1 byte

const notOK = "✓";
console.log(notOK.codePointAt(0).toString(16)); // 2713：占用 > 1 byte

console.log(btoa(ok)); // YQ==
console.log(btoa(notOK)); // error
```

如果你需要使用 `btoa()` 将 Unicode 文本编码为 ASCII，一种选择是将字符串中的每一个 16 比特的单元都转换为使用一个字节的单元。例如：

```js
// convert a Unicode string to a string in which
// each 16-bit unit occupies only one byte
function toBinary(string) {
  const codeUnits = new Uint16Array(string.length);
  for (let i = 0; i < codeUnits.length; i++) {
    codeUnits[i] = string.charCodeAt(i);
  }
  const charCodes = new Uint8Array(codeUnits.buffer);
  let result = "";
  for (let i = 0; i < charCodes.byteLength; i++) {
    result += String.fromCharCode(charCodes[i]);
  }
  return result;
}

// a string that contains characters occupying > 1 byte
const myString = "☸☹☺☻☼☾☿";

const converted = toBinary(myString);
const encoded = btoa(converted);
console.log(encoded); // OCY5JjomOyY8Jj4mPyY=
```

如果你按上述的方法进行了编码，你当然需要一种方法来进行解码：

```js
function fromBinary(binary) {
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < bytes.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  const charCodes = new Uint16Array(bytes.buffer);
  let result = "";
  for (let i = 0; i < charCodes.length; i++) {
    result += String.fromCharCode(charCodes[i]);
  }
  return result;
}

const decoded = atob(encoded);
const original = fromBinary(decoded);
console.log(original); // ☸☹☺☻☼☾☿
```

参见 Base64 术语的 Solution #1 – escaping the string before encoding it 示例中的 `utf8_to_b64` 和 `b64_to_utf8` 函数。

规范
--

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

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

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

参见
--

* `core-js` 中有对 `btoa` 的 polyfill
* `data` URL
* `atob()`
* Base64


ErrorEvent - Web API 接口参考

ErrorEvent
==========

**`ErrorEvent`** 事件对象在脚本发生错误时产生，它可以提供发生错误的脚本文件的文件名，以及发生错误时所在的行号等信息。

属性
--

除了从 `Event` 接口继承来的属性外，还有下面这些自身属性。

`ErrorEvent.prototype.message` 只读

一个`字符串`，包含了所发生错误的描述信息。

`ErrorEvent.prototype.filename` 只读

一个 `字符串`，包含了发生错误的脚本文件的文件名。

`ErrorEvent.prototype.lineno` 只读

一个数字，包含了错误发生时所在的行号。

`ErrorEvent.prototype.colno` 只读

一个数字，包含了错误发生时所在的列号。

`ErrorEvent.prototype.error` 只读
实验性

发生错误时所抛出的 `Error` 对象。

构造函数
----

`ErrorEvent()`

根据传入的参数构造 `ErrorEvent` 实例。

方法
--

除了从 `Event` 接口继承来的方法外，没有其他方法。

规范
--

| Specification |
| --- |
| HTML Standard # the-errorevent-interface |

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

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

参见
--

* 使用 web worker，最有可能引发此事件的对象


Gamepad - Web API 接口参考

Gamepad
=======

Gamepad API 的 `Gamepad` 接口，定义了一个独立的游戏手柄或其他控制器，允许访问控制器的信息，譬如按钮按下的状态、坐标输入的位置。游戏手柄或其他控制器，允许访问如按钮按下，和 ID 等信息。

Gamepad 对象有两种方式返回值：通过 `gamepadconnected` 和 `gamepaddisconnected` (en-US) 事件的 `gamepad` 属性，或者在任意位置抓取 `Navigator.getGamepads()` 方法返回的数组。

属性
--

`Gamepad.axes` (en-US) 只读

一个表示控制器设备上存在的坐标轴的数组 (比如控制器摇杆)。

`Gamepad.buttons` (en-US) 只读

一个 `gamepadButton` 对象的数组，表示设备上的按键的数组。

`Gamepad.connected` (en-US) 只读

一个表示控制器是否仍然连接着系统的布尔值。

`Gamepad.displayId` (en-US) 只读

*返回与 `VRDisplay` 相关的 `VRDisplay.displayId` (en-US) (如果有相关) — 控制器所控制的 `VRDisplay` 场景。*

`Gamepad.id` (en-US) 只读

一个包含着控制器标识信息的 `DOMString`。

`Gamepad.index` (en-US) 只读

一个自增的整形数字，对于当前连接到系统的每一个设备是唯一的。

`Gamepad.mapping` (en-US) 只读

一个指示浏览器是否被映射到某个已知布局的字符串。

`Gamepad.timestamp` (en-US) 只读

一个表示上次控制器数据更新时间的 `DOMHighResTimeStamp` 。

`Gamepad.hand` (en-US) 只读

一个枚举项，定义了控制器是用哪只手拿着的，或最可能是哪只手拿着的。

`Gamepad.hapticActuators` (en-US) 只读

一个包含 `GamepadHapticActuator` (en-US) 对象的数组，其中表示控制器上可用的触觉反馈硬件。

`Gamepad.pose` (en-US) 只读
实验性

一个表示 WebVR 控制器姿态方位信息的 `GamepadPose` 对象 (比如其在 3D 空间中的位置和方向)。

示例
--

```js
window.addEventListener("gamepadconnected", function (e) {
  console.log(
    "控制器已连接与 %d 位：%s. %d 个按钮，%d 个坐标方向。",
    e.gamepad.index,
    e.gamepad.id,
    e.gamepad.buttons.length,
    e.gamepad.axes.length,
  );
});
```

规范
--

| Specification |
| --- |
| Gamepad # gamepad-interface |
| Gamepad Extensions # partial-gamepad-interface |

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

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

参见
--

* 使用 Gamepad API
* Gamepad API


HTMLCollection - Web API 接口参考

HTMLCollection
==============

**`HTMLCollection`** 接口表示一个包含了元素（元素顺序为文档流中的顺序）的通用集合（与 `arguments` 相似的类数组 (array-like) 对象），还提供了用来从该集合中选择元素的方法和属性。

**备注：** 由于历史原因（DOM4 之前，实现该接口的集合只能包含 HTML 元素），该接口被称为 `HTMLCollection`。

HTML DOM 中的 `HTMLCollection` 是即时更新的（live）；当其所包含的文档结构发生改变时，它会自动更新。因此，最好是创建副本（例如，使用 `Array.from`）后再迭代这个数组以添加、移动或删除 DOM 节点。

属性
--

`HTMLCollection.length` 只读

返回集合当中子元素的数目。

方法
--

`HTMLCollection.item()`

根据给定的索引（从 0 开始），返回具体的节点。如果索引超出了范围，则返回 `null`。

访问 `collection[i]`（在索引 `i` 超出范围时会返回 `undefined`）的替代方法。这在非 JavaScript DOM 的实现中非常有用。

`HTMLCollection.namedItem()`

根据 ID 返回指定节点，若不存在，则根据字符串所表示的 `name` 属性来匹配。根据 name 匹配只能作为最后的依赖，并且只有当被引用的元素支持 `name` 属性时才能被匹配。如果不存在符合给定 name 的节点，则返回 `null`。

访问 `collection[name]`（在 `name` 不存在时会返回 `undefined`）的替代方法。这在非 JavaScript DOM 的实现中非常有用。

在 JavaScript 中使用
----------------

`HTMLCollection` 还通过将其成员的名称和索引直接以属性的形式公开。HTML ID 可能会包含在 ID 中合法的 `:` 和 `.` 字符，这时就需要使用括号表达式来访问属性。目前，`HTMLCollection` 不能识别纯数字的 ID，因为这与数组形式的访问相冲突（虽然 HTML5 允许使用纯数字的 ID）。

例如，假定在文档中有一个 `<form>` 元素，且它的 `id` 是 `myForm`：

```js
var elem1, elem2;

// document.forms is an HTMLCollection

elem1 = document.forms[0];
elem2 = document.forms.item(0);

alert(elem1 === elem2); // shows: "true"

elem1 = document.forms.myForm;
elem2 = document.forms.namedItem("myForm");

alert(elem1 === elem2); // shows: "true"

elem1 = document.forms["named.item.with.periods"];
```

规范
--

| Specification |
| --- |
| DOM Standard # interface-htmlcollection |

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

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

参见
--

* `NodeList`
* `HTMLFormControlsCollection` (en-US)、`HTMLOptionsCollection` (en-US)


DOMMatrix - Web API 接口参考

DOMMatrix
=========

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

\*\*`DOMMatrix`\*\*接口代表 4x4 矩阵，适合 2D 和 3D 操作。

一个 4x4 矩阵适于描绘任何 3D 的旋转（rotation）和过渡（translation）。

此接口在 Web workers 里应该是可用的，虽然某些实现现在还不允许。

属性
--

*此接口从`DOMMatrixReadOnly` (en-US)继承属性，虽然某些属性被修改为非只读的。*

`m11`, `m12`, `m13`, `m14`, `m21`, `m22`, `m23`, `m24`, `m31`, `m32`, `m33`, `m34`, `m41`, `m42`, `m43`, `m44`

代表一个 4x4 矩阵的每个组成部分的 double 值。

`a`, `b`, `c`, `d`, `e`, `f` 只读

代表了 2D 旋转和过渡所需要的一个 4x4 矩阵的每个组成部分的 double 值。它们是这个矩阵的一些组成的别名：

| `2D` | `3D 等价值` |
| --- | --- |
| `a` | `m11` |
| `b` | `m12` |
| `c` | `m21` |
| `d` | `m22` |
| `e` | `m41` |
| `f` | `m42` |

方法
--

*此接口从`DOMMatrixReadOnly` (en-US)继承方法。*

`DOMMatrixReadOnly.multiplySelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵乘以指定的矩阵`DOMMatrix`的结果。

`DOMMatrixReadOnly.preMultiplySelf()`

返回自身，一个`DOMMatrix`，它的新内容是指定的矩阵`DOMMatrix`乘以原始矩阵的结果。

`DOMMatrix.translateSelf()`

返回自身，一个`DOMMatrix`，它的新内容是矩阵被指定向量转换后的结果。

`DOMMatrix.scaleSelf()`

返回自身，一个`DOMMatrix`，它的新内容是矩阵的 x 和 y 维度被指定因子缩放后的结果，对齐指定原点。

`DOMMatrix.scale3dSelf()`

返回自身，一个`DOMMatrix`，它的新内容是矩阵的 x, y 和 z 维度被指定因子缩放后的结果，对齐指定原点。

`DOMMatrix.scaleNonUniformSelf()`

返回自身，一个`DOMMatrix`，它的新内容是矩阵的 x, y 和 z 维度被各自维度的指定因子缩放后的结果，对齐指定原点。

`DOMMatrix.rotateSelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵被指定角度旋转后的结果，对齐指定原点。

`DOMMatrix.rotateFromVectorSelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵被指定角度旋转后的结果，该角度在指定向量和 (1,0) 之间，对齐指定原点。

`DOMMatrix.rotateAxisAngleSelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵被指定角度和指定向量旋转后的结果。

`DOMMatrix.skewXSelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵被指定因子沿 x 轴倾斜后的结果。

`DOMMatrix.skewYSelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵被指定因子沿 y 轴倾斜后的结果。

`DOMMatrix.invertSelf()`

返回自身，一个`DOMMatrix`，它的新内容是原始矩阵求逆后的结果。如果不能求逆，所有的组成部分会被设为 NaN，并且`is2D() 返回` `false`。

`DOMMatrix.setMatrixValue()`

返回自身，一个`DOMMatrix`，描述了一个矩阵，它的变换（transformation）和被参数指定的 CSS `transform`函数一样。

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # DOMMatrix |

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

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

参见
--

* 它的不可修改部分，`DOMMatrixReadOnly` (en-US)


Long Tasks API - Web API 接口参考

Long Tasks API
==============

目的
--

\*Long Tasks，\*这是一个实验性 API，它可以直观地告诉我们哪些任务执行耗费了 50 毫秒或更多时间。50 毫秒这个阈值标准来源于《RAIL Model》中 "Response: process events in under 50ms" 章节。

阻塞主线程达 50 毫秒或以上的任务会导致以下问题：

* `可交互时间` 延迟
* 严重不稳定的交互行为 (轻击、单击、滚动、滚轮等) 延迟（High/variable input latency）
* 严重不稳定的事件回调延迟（High/variable event handling latency）
* 紊乱的动画和滚动（Janky animations and scrolling）
概念
--

长任务（Long task）API 使用的一些关键术语或思想。

### 长任务（Long task）

任何连续不间断的且主 UI 线程繁忙 50 毫秒及以上的时间区间。比如以下常规场景：

* 长耗时的事件回调（long running event handlers）
* 代价高昂的回流和其他重绘（expensive reflows and other re-renders）
* 浏览器在超过 50 毫秒的事件循环的相邻循环之间所做的工作（work the browser does between different turns of the event loop that exceeds 50 ms）
### 浏览上下文的罪魁容器

浏览上下文的罪魁容器，简称“容器”，指任务发生在其中的顶层页面（the top level page）、iframe、嵌入插槽（embed）或对象（object）。

### 清单（Attributions）

即执行任务的容器清单。针对没有在顶层页面容器内执行的任务，`containerId`、`containerName`和`containerSrc`字段可以用来提供任务源信息。

用法
--

```js
var observer = new PerformanceObserver(function (list) {
  var perfEntries = list.getEntries();
  for (var i = 0; i < perfEntries.length; i++) {
    // Process long task notifications:
    // report back for analytics and monitoring
    // ...
  }
});
// register observer for long task notifications
observer.observe({ entryTypes: ["longtask"] });
// Long script execution after this will result in queueing
// and receiving "longtask" entries in the observer.
```

接口
--

`PerformanceLongTaskTiming`

返回长任务实例。

`TaskAttributionTiming` (en-US)

返回长任务中涉及的工作及其关联的框架上下文信息。

规范
--

| Specification |
| --- |
| Long Tasks API # sec-PerformanceLongTaskTiming |

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

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

相关推荐
----

* GitHub repository 包含文档和代码范例。
* PerfPlanet article on Long Tasks API from 20th December 2017.


SVGElement - Web API 接口参考

SVGElement
==========

所有 SVG DOM 类的父类。

EventTarget

Node

Element

SVGElement属性
--

`SVGElement.dataset`只读

A `DOMStringMap` object which provides a list of key/value pairs of named data attributes which correspond to custom data attributes attached to the element. These can also be defined in SVG using attributes of the form `data-\* (en-US)`, where `*` is the key name for the pair. This works just like HTML's `HTMLElement.dataset` property and HTML's `data-*` global attribute.

`SVGElement.id`只读

A `DOMString` representing the value of the `id` attribute on the given element, or the empty string if `id` is not present.

`SVGElement.xmlbase`只读

A `DOMString` corresponding to the `xml:base (en-US)` attribute on the given element.

`SVGElement.ownerSVGElement`只读

An `SVGSVGElement` referring to the nearest ancestor `<svg>` element. `null` if the given element is the outermost `<svg>` element.

`SVGElement.viewportElement`只读

The `SVGElement`, which established the current viewport. Often, the nearest ancestor `<svg>` element. `null` if the given element is the outermost `<svg>` element.

方法
--

*`SVGElement` 类本身没有方法，但拥有从父类 `Element` 继承的方法。*

规范
--

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # InterfaceSVGElement |

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

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

相关链接
----

* HTML `data-*` 属性
* SVG `data-\* (en-US)` 属性
* 使用数据属性


HTMLDivElement - Web API 接口参考

HTMLDivElement
==============

**`HTMLDivElement`** 接口提供了一些特殊属性（它也继承了通常的 `HTMLElement` 接口）来操作 `<div>` 元素。

属性
--

*属性继承自父类，`HTMLElement`。*

`HTMLDivElement.align`
已弃用

这是一个 `DOMString` 表示一个指示元素内容相对于周围内容的对齐方式的可枚举属性。可取的值有 `"left"`，`"right"`，`"justify"`，和 `"center"`。

方法
--

*没有特有的方法；方法继承自父类，`HTMLElement`。*

规范
--

| Specification |
| --- |
| HTML Standard # htmldivelement |

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

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

参见
--

* 此 HTML 元素实现了这个接口：`<div>`。


ServiceWorkerContainer - Web API 接口参考

ServiceWorkerContainer
======================

Service Worker API 的 `ServiceWorkerContainer` 接口提供了一个对象，该对象表示 service worker 作为网络系统中的整体单元，包括注册、注销和更新 service worker 以及访问 service worker 的状态和它们的注册状态的功能。

更重要的是，它暴露了用于注册 service worker 的 `ServiceWorkerContainer.register()` 方法，和用于确定当前页面是否受到主动控制的 `ServiceWorkerContainer.controller` 属性。

EventTarget

ServiceWorkerContainer实例属性
----

`ServiceWorkerContainer.controller` 只读

如果 ServiceWorker 对象的状态是 `activating` 或 `activated`（与 `ServiceWorkerRegistration.active` (en-US) 返回相同的对象），则返回 `ServiceWorker` 对象。在强制刷新请求（*Shift* + refresh）或者没有激活的 worker 的时候，该属性返回 `null`。

`ServiceWorkerContainer.ready` (en-US) 只读

提供了一种延迟代码执行直到 service worker 被激活的方法。它返回一个从不会拒绝的 `Promise`，并且一直等到与当前页面相关联的 `ServiceWorkerRegistration` (en-US) 有一个 `ServiceWorkerRegistration.active` (en-US) worker。一旦满足该条件，它将用 `ServiceWorkerRegistration` (en-US) 兑现。

### 事件

`controllerchange` (en-US)

当文档关联的 `ServiceWorkerRegistration` (en-US) 获得新激活 (en-US)的 worker 时触发。

`error` (en-US)
已弃用

非标准

每当关联的 service worker 出现错误时触发。

`message` (en-US)

当 `ServiceWorkerContainer` 对象收到传入的消息时触发（例如，通过 `MessagePort.postMessage()` (en-US) 调用）。

实例方法
----

`ServiceWorkerContainer.register()`

用给定的 `scriptURL` 创建或者更新 `ServiceWorkerRegistration` (en-US)。

`ServiceWorkerContainer.getRegistration()` (en-US)

得到一个 `ServiceWorkerRegistration` (en-US) 对象，它的作用域范围与提供的文档匹配。该方法返回一个兑现为 `ServiceWorkerRegistration` (en-US) 或 `undefined` 的 `Promise`。

`ServiceWorkerContainer.getRegistrations()` (en-US)

返回数组中与 `ServiceWorkerContainer` 关联的所有 `ServiceWorkerRegistration` (en-US) 对象。该方法返回一个兑现为 `ServiceWorkerRegistration` (en-US) 的数组的 `Promise`。

`ServiceWorkerContainer.startMessages()` (en-US)

显式启动从 service worker 分发到其控制页面下的消息流（例如，通过 `Client.postMessage()` 发送）。这可用于更早地对发送的消息做出反应，甚至在该页面的内容加载完成之前。

示例
--

以下示例首先检查浏览器是否支持 service worker。如果支持，代码将注册 service worker，并确定页面是否由 service worker 控制。如果不是，它会提示用户重新加载页面，以便 service worker 可以控制。该代码还将报告任何注册的错误。

```js
if ("serviceWorker" in navigator) {
  // Register a service worker hosted at the root of the
  // site using the default scope.
  navigator.serviceWorker
    .register("/sw.js")
    .then((registration) => {
      console.log("Service worker registration succeeded:", registration);
      // At this point, you can optionally do something
      // with registration. See https://developer.mozilla.org/zh-CN/docs/Web/API/ServiceWorkerRegistration
    })
    .catch((error) => {
      console.error(`Service worker registration failed: ${error}`);
    });

  // Independent of the registration, let's also display
  // information about whether the current page is controlled
  // by an existing service worker, and when that
  // controller changes.

  // First, do a one-off check if there's currently a
  // service worker in control.
  if (navigator.serviceWorker.controller) {
    console.log(
      "This page is currently controlled by:",
      navigator.serviceWorker.controller,
    );
  }

  // Then, register a handler to detect when a new or
  // updated service worker takes control.
  navigator.serviceWorker.oncontrollerchange = () => {
    console.log(
      "This page is now controlled by",
      navigator.serviceWorker.controller,
    );
  };
} else {
  console.log("Service workers are not supported.");
}
```

规范
--

| Specification |
| --- |
| Service Workers # serviceworkercontainer-interface |

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

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

参见
--

* 使用 Service Worker
* Service worker 基础代码示例
* 是否支持 ServiceWorker？
* `Promise`
* 使用 web worker


Storage - Web API 接口参考

Storage
=======

作为 Web Storage API 的接口，**`Storage`** 提供了访问特定域名下的会话存储或本地存储的功能，例如，可以添加、修改或删除存储的数据项。

如果你想要操作一个域名的会话存储，可以使用 `Window.sessionStorage`；如果想要操作一个域名的本地存储，可以使用 `Window.localStorage`。

属性
--

`Storage.length` 只读

返回一个整数，表示存储在 `Storage` 对象中的数据项数量。

方法
--

`Storage.key()`

该方法接受一个数值 n 作为参数，并返回存储中的第 n 个键名。

`Storage.getItem()`

该方法接受一个键名作为参数，返回键名对应的值。

`Storage.setItem()`

该方法接受一个键名和值作为参数，将会把键值对添加到存储中，如果键名存在，则更新其对应的值。

`Storage.removeItem()`

该方法接受一个键名作为参数，并把该键名从存储中删除。

`Storage.clear()`

调用该方法会清空存储中的所有键名。

示例
--

这里我们通过调用 `localStorage` 来访问一个 `Storage` 对象。首先，使用 `!localStorage.getItem('bgcolor')` 测试本地存储中是否包含该数据项。如果包含，则运行 `setStyles()` 函数，该函数使用 `localStorage.getItem()` 来获取数据项，并使用这些值更新页面样式。如果不包含，我们运行另一个函数 `populateStorage()`，该函数使用 `localStorage.setItem()` 设置数据项，然后运行 `setStyles()`。

```js
if (!localStorage.getItem("bgcolor")) {
  populateStorage();
} else {
  setStyles();
}

function populateStorage() {
  localStorage.setItem("bgcolor", document.getElementById("bgcolor").value);
  localStorage.setItem("font", document.getElementById("font").value);
  localStorage.setItem("image", document.getElementById("image").value);

  setStyles();
}

function setStyles() {
  const currentColor = localStorage.getItem("bgcolor");
  const currentFont = localStorage.getItem("font");
  const currentImage = localStorage.getItem("image");

  document.getElementById("bgcolor").value = currentColor;
  document.getElementById("font").value = currentFont;
  document.getElementById("image").value = currentImage;

  htmlElem.style.backgroundColor = `#${currentColor}`;
  pElem.style.fontFamily = currentFont;
  imgElem.setAttribute("src", currentImage);
}
```

**备注：** 有关实际运行的例子，详见 Web Storage 演示。

规范
--

| Specification |
| --- |
| HTML Standard # storage |

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

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

相关链接
----

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


CanvasGradient - Web API 接口参考

CanvasGradient
==============

**`CanvasGradient`** 接口表示描述渐变的不透明对象。通过 `CanvasRenderingContext2D.createLinearGradient()` 或 `CanvasRenderingContext2D.createRadialGradient()` 的返回值得到。

属性
--

*不透明对象，没有暴露的属性。*

方法
--

*没有继承的方法。*

`CanvasGradient.addColorStop()`

添加一个由偏移（`offset`）和颜色（`color`）定义的断点到渐变中。如果偏移值不在 0 到 1 之间，将抛出`INDEX_SIZE_ERR 错误，如果颜色值不能被解析为有效的 CSS 颜色值 `<color>`，将抛出 SYNTAX_ERR`错误。

规范
--

| Specification |
| --- |
| HTML Standard # canvasgradient |

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

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

参见
--

* 创建方法在 `CanvasRenderingContext2D`。
* `<canvas>` 元素及其有关接口 `HTMLCanvasElement`。


HTMLLIElement - Web API 接口参考

HTMLLIElement
=============

**`HTMLLIElement`** 接口公开了特定的属性和方法 (超出了常规 `HTMLElement` 接口所定义的接口，它通过继承可用于操作列表元素。

属性
--

*从其父级 `HTMLElement` 继承属性。*

`HTMLLIElement.type`
已弃用

是`DOMString`表示项目符号的类型 `"disc"`，`"square"` 或 `"circle"`。由于定义列表类型的标准方法是通过 CSS `list-style-type`属性，应当使用 CSSOM 方法通过脚本设置它。

`HTMLLIElement.value`

是`long`指示给定`<ol>`中*列表元素*的序号位置。它反映了 HTML `<li>`元素的`value`属性，并且可以小于`0`。如果`<li>`元素不是`<ol>`元素的子元素，则该属性没有意义。

方法
--

*没有具体方法; 从其父级 `HTMLElement` 继承属性。*

规范
--

| Specification |
| --- |
| HTML Standard # htmllielement |

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

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

参见
--

* 实现了此接口的 HTML 元素：`<li>`


Headers - Web API 接口参考

Headers
=======

Fetch API 的 **Headers** 接口允许你对 HTTP 请求和响应头执行各种操作。这些操作包括检索，设置，添加和删除。

一个 Headers 对象具有关联的标头列表，它最初为空，由零个或多个键值对组成。你可以使用类似于 `append()` 这样的方法添加（参见示例）到这个对象中。在该接口的所有方法中，标头名称由不区分大小写的字节序列匹配。

出于安全考虑，某些头只能由用户代理控制。这些头信息包括 forbidden header names 和 forbidden response header names。

一个 Headers 对象也有一个关联的 guard，它具有不可变的值，`request`，`request-no-cors`，`response`或`none`。这会影响 `set()`, `delete()`, 和`append()` 方法 改变 header. 参考更多信息，请看 Guard.

你可以通过 `Request.headers` 和`Response.headers` 属性检索一个`Headers`对象，并使用 `Headers.Headers()` 构造函数创建一个新的`Headers` 对象。

一个实现了`Headers` 的对象可以直接用于 `for...of` 结构中，而不是 `entries()`: `for (var p of myHeaders)` 等价于 `for (var p of myHeaders.entries())`.

**备注：** 你可以通过阅读我们的 HTTP headers参考找到更多关于可用 headers 的信息。

构造函数
----

`Headers.Headers()`

创建一个新的 Headers 对象。

方法
--

`Headers.append()`

给现有的 header 添加一个值，或者添加一个未存在的 header 并赋值。

`Headers.delete()`

从 Headers 对象中删除指定 header.

`Headers.entries()`

以 `迭代器` 的形式返回 Headers 对象中所有的键值对。

`Headers.get()`

以 `ByteString` 的形式从 Headers 对象中返回指定 header 的全部值。

`Headers.has()`

以布尔值的形式从 Headers 对象中返回是否存在指定的 header.

`Headers.keys()`

以`迭代器`的形式返回 Headers 对象中所有存在的 header 名。

`Headers.set()`

替换现有的 header 的值，或者添加一个未存在的 header 并赋值。

`Headers.values()`

以`迭代器`的形式返回 Headers 对象中所有存在的 header 的值。

**备注：** 值得注意的是，在 header 已存在或者有多个值的状态下`Headers.set()` 和 `Headers.append()`的使用有如下区别，`Headers.set()` 将会用新的值覆盖已存在的值，但是`Headers.append()`会将新的值添加到已存在的值的队列末尾。请参相关词条内的示例代码。

**备注：** 如果你尝试传入名称不是有效的 HTTP 标头名称的引用，则所有 Headers 方法都将引发 `TypeError`。如果标头具有不可变的 Guard，则突变操作会引发 `TypeError`。在任何其他失败情况下，它们都会无声地失败。

### Obsolete methods

`Headers.getAll()`

用于返回具有给定名称的 `Headers` 对象中所有值的数组; 这个方法现在已经从规范中删除了，`Headers.get()` 方法现在返回所有的值而不是一个。

示例
--

在这个小示例中，我们将会通过 Headers 构造函数创建一个新的 header，先使用 append() 方法添加一个 header，然后通过 get() 方法返回这个 header 的值

```js
let myHeaders = new Headers();

myHeaders.append("Content-Type", "text/xml");

myHeaders.get("Content-Type");
// should return 'text/xml'
```

规范
--

| Specification |
| --- |
| Fetch Standard # headers-class |

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

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

参见
--

* ServiceWorker API
* HTTP 访问控制（CORS）
* HTTP


InstallEvent - Web API 接口参考

InstallEvent
============

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

该参数传递到 `oninstall` 事件处理程序，`InstallEvent` 接口表示一个 `ServiceWorker` 的 `ServiceWorkerGlobalScope` 上分派的安装操作。作为 `ExtendableEvent` 的一个子类，它确保在安装期间不调度诸如 `FetchEvent` 之类的功能事件。

该接口继承自 `ExtendableEvent` 接口。

构造函数
----

`InstallEvent.InstallEvent()` (en-US)

创建一个新的 `InstallEvent` 对象。

属性
--

*从它的祖先`Event`继承属性。*

`InstallEvent.activeWorker` (en-US) 只读

返回当前处于激活状态，控制页面的`ServiceWorker`。

方法
--

*从它的父类`ExtendableEvent`继承方法。*

示例
--

该代码片段来自 service worker prefetch sample (请参阅 prefetch running live)。代码在`ServiceWorkerGlobalScope.oninstall`中调用`ExtendableEvent.waitUntil(any value)`，并延迟将`ServiceWorkerRegistration.installing` (en-US) worker 视为已安装的，直到传递的 promise 被成功地 resolve。当所有资源已经获取并缓存，或者有任何异常发生时，promise 才会 resolve。

该代码片段也展示了服务工作线程使用的缓存版本控制的最佳实践。虽然此示例只有一个缓存，但你可以将此方法用于多个缓存。代码将缓存的速记标识映射到特定的版本化缓存名称。

**备注：** service worker 的注册日志记录在 Chrome 浏览器中可以通过访问 chrome://serviceworker-internals 查看。

```js
var CACHE\_VERSION = 1;
var CURRENT\_CACHES = {
  prefetch: "prefetch-cache-v" + CACHE\_VERSION,
};

self.addEventListener("install", function (event) {
  var urlsToPrefetch = [
    "./static/pre\_fetched.txt",
    "./static/pre\_fetched.html",
    "https://www.chromium.org/\_/rsrc/1302286216006/config/customLogo.gif",
  ];

  console.log(
    "Handling install event. Resources to pre-fetch:",
    urlsToPrefetch,
  );

  event.waitUntil(
    caches
      .open(CURRENT\_CACHES["prefetch"])
      .then(function (cache) {
        cache
          .addAll(
            urlsToPrefetch.map(function (urlToPrefetch) {
              return new Request(urlToPrefetch, { mode: "no-cors" });
            }),
          )
          .then(function () {
            console.log("All resources have been fetched and cached.");
          });
      })
      .catch(function (error) {
        console.error("Pre-fetching failed:", error);
      }),
  );
});
```

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

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

参见
--

* `NotificationEvent`
* `Promise`
* Fetch API


性能监测对象 - Web API 接口参考

性能监测对象
======

**`PerformanceObserver`** 用于*监测*性能度量事件，在浏览器的性能时间轴记录新的 performance entry 的时候将会被通知。

**备注：** 此特性在 Web Worker 中可用

构造函数
----

`PerformanceObserver()`

创建并返回一个新的 `PerformanceObserver` 对象。

方法
--

`PerformanceObserver.observe()`

指定监测的 `entry types` 的集合。当 `performance entry` 被记录并且是指定的 `entryTypes` 之一的时候，性能观察者对象的回调函数会被调用。

`PerformanceObserver.disconnect()`

性能监测回调停止接收 性能条目。

`PerformanceObserver.takeRecords()`

返回当前存储在性能观察器的 `performance entry` 列表，并将其清空。

示例
--

```js
function perf\_observer(list, observer) {
  // Process the "measure" event
  // 处理 "measure" 事件
}
var observer2 = new PerformanceObserver(perf_observer);
observer2.observe({ entryTypes: ["measure"] });
```

规范
--

| Specification |
| --- |
| Performance Timeline # dom-performanceobserver |

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

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


鼠标事件 - Web API 接口参考

鼠标事件
====

**`MouseEvent`** 接口指用户与指针设备（如鼠标）交互时发生的事件。使用此接口的常见事件包括：`click`、`dblclick`、`mouseup`、`mousedown`。

`MouseEvent` 派生自 `UIEvent`，`UIEvent` 派生自 `Event`。虽然 `MouseEvent.initMouseEvent()` 方法保持向后兼容性，但是应该使用 `MouseEvent()` 构造函数创建一个 `MouseEvent` 对象。

一些具体的事件都派生自 `MouseEvent`：`WheelEvent` 和`DragEvent`。

Event

UIEvent

MouseEvent构造函数
----

`MouseEvent()`

生成一个新的 MouseEvent 对象

属性
--

*这个接口也继承了`UIEvent` 和 `Event`原型上的方法，*

`MouseEvent.altKey` 只读

当鼠标事件触发的时，如果 `alt` 键被按下，返回 true;

`MouseEvent.button` 只读

当鼠标事件触发的时，如果鼠标按钮被按下（如果有的话），将会返回一个数值。

`MouseEvent.buttons` 只读

当鼠标事件触发的时，如果多个鼠标按钮被按下（如果有的话），将会返回一个或者多个代表鼠标按钮的数字。

`MouseEvent.clientX` 只读

鼠标指针在点击元素（DOM）中的 X 坐标。

`MouseEvent.clientY` 只读

鼠标指针在点击元素（DOM）中的 Y 坐标。

`MouseEvent.ctrlKey` 只读

当鼠标事件触发时，如果 `control` 键被按下，则返回 true；

`MouseEvent.metaKey` 只读

当鼠标事件触发时，如果 `meta` 键被按下，则返回 true；

`MouseEvent.movementX` 只读

鼠标指针相对于最后`mousemove`事件位置的 X 坐标。

`MouseEvent.movementY` 只读

鼠标指针相对于最后`mousemove`事件位置的 Y 坐标。

`MouseEvent.offsetX` 只读
实验性

鼠标指针相对于目标节点内边位置的 X 坐标

`MouseEvent.offsetY` 只读
实验性

鼠标指针相对于目标节点内边位置的 Y 坐标

`MouseEvent.pageX` 只读
实验性

鼠标指针相对于整个文档的 X 坐标；

`MouseEvent.pageY` 只读
实验性

鼠标指针相对于整个文档的 Y 坐标；

`MouseEvent.region` 只读

返回被点击事件影响的点击区域的 id，如果没有区域被影响则返回 null。

`MouseEvent.relatedTarget` 只读

鼠标事件的次要目标（如果有的话）

`MouseEvent.screenX` 只读

鼠标指针相对于全局（屏幕）的 X 坐标；

`MouseEvent.screenY` 只读

鼠标指针相对于全局（屏幕）的 Y 坐标；

`MouseEvent.shiftKey` 只读

当鼠标事件触发时，如果 `shift` 键被按下，则返回 true；

`MouseEvent.which`
非标准
 只读

当鼠标事件触发时，表示被按下的按钮。

`MouseEvent.mozInputSource`
非标准
 只读

生成事件的类型（若干 `MOZ_SOURCE_*`常量如下列出）。可通过该属性获知鼠标事件是否由真实鼠标设备触发，亦或通过触摸事件触发（这可能影响处理坐标事件时的精确程度）。

`MouseEvent.webkitForce` (en-US)
非标准
 只读

点击时施加的压力量。

`MouseEvent.x`
实验性
只读

`MouseEvent.clientX`的别名。

`MouseEvent.y`
实验性
只读

`MouseEvent.clientY`的别名。

常量
--

`MouseEvent.WEBKIT_FORCE_AT_MOUSE_DOWN` (en-US)
非标准
只读

正常点击所需的最小力量

`MouseEvent.WEBKIT_FORCE_AT_FORCE_MOUSE_DOWN` (en-US)
非标准
只读

强制点击所需的最小力量

方法
--

*这个接口也继承了它的副方法`UIEvent` 和`Event`.*

`MouseEvent.getModifierState()` (en-US)

返回指定修饰键的当前状态。请参照`KeyboardEvent.getModifierState` (en-US)() 查看详情。

`MouseEvent.initMouseEvent()`
已弃用

初始化创建 MouseEvent 的值。如果这个事件已经被分派，这个方法将不会做任何事情。

示例
--

这个例子演示了使用 DOM 方法在复选框上模拟一个点击事件（使用编程的方式生成点击事件）。

```js
function simulateClick() {
  var evt = new MouseEvent("click", {
    bubbles: true,
    cancelable: true,
    view: window,
  });
  var cb = document.getElementById("checkbox"); //element to click on
  var canceled = !cb.dispatchEvent(evt);
  if (canceled) {
    // A handler called preventDefault
    alert("canceled");
  } else {
    // None of the handlers called preventDefault
    alert("not canceled");
  }
}
document.getElementById("button").addEventListener("click", simulateClick);
```

```html
<p>
  <label><input type="checkbox" id="checkbox" /> Checked</label>
</p>
<p><button id="button">Click me</button></p>
```

点击按钮查看演示：

规范
--

| Specification |
| --- |
| UI Events # interface-mouseevent |
| CSSOM View Module # extensions-to-the-mouseevent-interface |
| Pointer Lock 2.0 # extensions-to-the-mouseevent-interface |

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

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

参考
--

* 它的直接父级，`UIEvent`.


SourceBuffer - Web API 接口参考

SourceBuffer
============

**`SourceBuffer`** 接口表示通过 `MediaSource` 对象传递到 `HTMLMediaElement` 并播放的媒体分块。它可以由一个或者多个媒体片段组成。

EventTarget

SourceBuffer属性
--

`SourceBuffer.appendWindowEnd` (en-US)

控制 append window 结束的时间戳。

`SourceBuffer.appendWindowStart` (en-US)

控制 append window 开始的时间戳。这是一个时间戳范围，可以用于过滤附加到 `SourceBuffer` 的媒体数据。此时间戳范围的编码媒体帧将被附加，而超出此范围的将被忽略。

`SourceBuffer.audioTracks` (en-US) 只读

当前包含在 `SourceBuffer` 中的音轨列表。

`SourceBuffer.buffered` 只读

返回当前在 `SourceBuffer` 中缓冲的时间范围。

`SourceBuffer.mode`

控制如何处理 `SourceBuffer` 中媒体片段的顺序，即它们是否可以按任何顺序被加载，或者他们必须保持一个严格的顺序。

`SourceBuffer.textTracks` (en-US) 只读

当前包含在 `SourceBuffer` 中的文本轨列表。

`SourceBuffer.timestampOffset`

控制应用于随后附加到 `SourceBuffer` 的媒体片段内的时间戳偏移量。

`SourceBuffer.updating` 只读

一个布尔值，表示 `SourceBuffer` 当前是否正在更新——即当前是否正在进行 `SourceBuffer.appendBuffer()`、`SourceBuffer.appendStream()` (en-US) 或 `SourceBuffer.remove()` 操作。

`SourceBuffer.videoTracks` (en-US) 只读

当前包含在 `SourceBuffer` 中的视频轨列表。

方法
--

*从它的父接口 `EventTarget` 继承方法。*

`SourceBuffer.abort()` (en-US)

中止当前片段并且重置片段解析器。

`SourceBuffer.appendBuffer()`

将来自 `ArrayBuffer`、`TypedArray` 或 `DataView` 对象的媒体片段数据附加到 `SourceBuffer`。

`SourceBuffer.appendBufferAsync()` (en-US)
实验性

启动异步进程，将指定缓冲数据附加到 `SourceBuffer`。返回一个 `Promise`，一旦添加了缓冲数据，该 promise 将会兑现。

`SourceBuffer.appendStream()` (en-US)

将来自 `ReadableStream` 对象的媒体片段数据附加到 `SourceBuffer`。

`SourceBuffer.changeType()` (en-US)

更改 MIME 类型，使其符合将来调用 `appendBuffer()` 附加的新数据的类型。

`SourceBuffer.remove()`

从 `SourceBuffer` 移除指定时间范围内的媒体片段。

`SourceBuffer.removeAsync()` (en-US)
实验性

启动异步进程，从 `SourceBuffer` 移除指定时间范围的媒体片段。返回一个 `Promise`，一旦所有匹配的片段被删除，该 promise 将会兑现。

事件
--

`abort`

当 `SourceBuffer.appendBuffer()` 或 `SourceBuffer.appendStream()` (en-US) 结束时通过调用 `SourceBuffer.abort()` (en-US) 触发。`SourceBuffer.updating` 从 `true` 改变为 `false`。

`error`

在 `SourceBuffer.appendBuffer()` 或 `SourceBuffer.appendStream()` (en-US) 期间发生错误时触发。`SourceBuffer.updating` 从 `true` 改变为 `false`。

`update`

在 `SourceBuffer.appendBuffer()` 或 `SourceBuffer.remove()` 完成时触发。`SourceBuffer.updating` 从 `true` 改变为 `false`。这个事件在 `updateend` 之前触发。

`updateend`

在 `SourceBuffer.appendBuffer()` 或 `SourceBuffer.remove()` 结束后触发。这个事件在 `update` 后触发。

`updatestart`

当 `SourceBuffer.updating` 从 `false` 改变为 `true` 时触发。

示例
--

这个例子尽可能快地逐块加载视频，并在加载好后立刻播放。以下片段基于 Nick Desaulniers 编写的一个简单示例（查看完整的在线演示，或者下载源代码进行进一步研究）。

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

const assetURL = "frag\_bunny.mp4";
// Need to be specific for Blink regarding codecs
// ./mp4info frag\_bunny.mp4 | grep Codec
const mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  const mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error("Unsupported MIME type or codec: ", mimeCodec);
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  const mediaSource = this;
  const sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}

function fetchAB(url, cb) {
  console.log(url);
  const xhr = new XMLHttpRequest();
  xhr.open("get", url);
  xhr.responseType = "arraybuffer";
  xhr.onload = function () {
    cb(xhr.response);
  };
  xhr.send();
}
```

规范
--

| Specification |
| --- |
| Media Source Extensions™ # sourcebuffer |

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

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

参见
--

* `MediaSource`
* `SourceBufferList`