ServiceWorkerGlobalScope - Web API 接口参考

ServiceWorkerGlobalScope
========================

ServiceWorker API (en-US) 的`ServiceWorkerGlobalScope` 接口，代表一个 service worker 的全局执行上下文。

开发者应该知道，ServiceWorker 的状态在结束/重启的循环中不是一直保持不变的，所以每个事件处理器应该设定一个默认的全局状态。

一旦成功地注册了 service worker，为了节省内存和处理器，它将在他的状态达到了空闲的时候被终止。一个在激活状态的 service worker 为了响应事件是可以自动重启的，就像这两个方法， `ServiceWorkerGlobalScope.onfetch` 或者`ServiceWorkerGlobalScope.onmessage` (en-US).

此外，在 service worker 中，同步请求是被禁止的 - 只有异步请求，如方法`fetch()` 才被允许。

该接口继承自 `WorkerGlobalScope` (en-US) 接口，以及其父类 `EventTarget`, 因此继承属性来自 `WindowTimers`, `WindowBase64`.

属性
--

`ServiceWorkerGlobalScope.clients` (en-US) 只读

Contains the `Clients` object associated with the service worker.

`ServiceWorkerGlobalScope.registration` (en-US) 只读

Contains the `ServiceWorkerRegistration` (en-US) object that represents the service worker's registration.

`ServiceWorkerGlobalScope.caches` 只读

Contains the `CacheStorage` object associated with the service worker.

事件
--

`activate` (en-US)

Occurs when a `ServiceWorkerRegistration` (en-US) acquires a new `ServiceWorkerRegistration.active` (en-US) worker.

`contentdelete` (en-US)
实验性

Occurs when an item is removed from the `Content Index` (en-US).

`fetch` (en-US)

Occurs when a `fetch()` is called.

`install` (en-US)

Occurs when a `ServiceWorkerRegistration` (en-US) acquires a new `ServiceWorkerRegistration.installing` (en-US) worker.

`message` (en-US)

Occurs when incoming messages are received. Controlled pages can use the `MessagePort.postMessage()` (en-US) method to send messages to service workers. The service worker can optionally send a response back via the `MessagePort` exposed in `event.data.port`, corresponding to the controlled page.

`notificationclick` (en-US)

Occurs when a user clicks on a displayed notification.

`notificationclose` (en-US)

Occurs when a user closes a displayed notification.

`sync` (en-US)

Triggered when a call to `SyncManager.register` (en-US) is made from a service worker client page. The attempt to sync is made either immediately if the network is available or as soon as the network becomes available.

`periodicsync` (en-US)
实验性

Occurs at periodic intervals, which were specified when registering a `PeriodicSyncManager` (en-US).

`push` (en-US)

Occurs when a server push notification is received.

`pushsubscriptionchange` (en-US)

Occurs when a push subscription has been invalidated, or is about to be invalidated (e.g. when a push service sets an expiration time).

方法
--

`ServiceWorkerGlobalScope.skipWaiting()`

Allows the current service worker registration to progress from waiting to active state while service worker clients are using it.

`ServiceWorkerGlobalScope` implements `WorkerGlobalScope` (en-US) — which implements `GlobalFetch`. Therefore it also has the following property available to it:

`GlobalFetch.fetch()`

Starts the process of fetching a resource. This returns a promise that resolves to the `Response` object representing the response to your request. This algorithm is the entry point for the fetch handling handed to the service worker context.

示例
--

This code snippet is from the service worker prefetch sample (see prefetch example live.) The `ServiceWorkerGlobalScope.onfetch` event handler listens for the `fetch` event. When fired, the code returns a promise that resolves to the first matching request in the `Cache` object. If no match is found, the code fetches a response from the network.

The code also handles exceptions thrown from the `fetch()` operation. Note that an HTTP error response (e.g., 404) will not trigger an exception. It will return a normal response object that has the appropriate error code set.

```js
self.addEventListener("fetch", function (event) {
  console.log("Handling fetch event for", event.request.url);

  event.respondWith(
    caches.match(event.request).then(function (response) {
      if (response) {
        console.log("Found response in cache:", response);

        return response;
      }
      console.log("No response found in cache. About to fetch from network...");

      return fetch(event.request).then(
        function (response) {
          console.log("Response from network is:", response);

          return response;
        },
        function (error) {
          console.error("Fetching failed:", error);

          throw error;
        },
      );
    }),
  );
});
```

规范
--

| Specification |
| --- |
| Service Workers # serviceworkerglobalscope-interface |

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

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

参见
--

* 使用 Service Worker
* Service worker 基本代码示例
* 是否支持 ServiceWorker
* `Promise`
* 使用 web worker


TransformStreamDefaultController - Web API 接口参考

TransformStreamDefaultController
================================

Stream API 的 **`TransformStreamDefaultController`** 接口提供了操作关联的 `ReadableStream` 和 `WritableStream` 的方法。

当构造 `TransformStream` 时，会创建一个 `TransformStreamDefaultController`。因此它没有构造函数。获取 `TransformStreamDefaultController` 实例的方式是通过 `TransformStream()` 的回调方法。

实例属性
----

`TransformStreamDefaultController.desiredSize`只读

返回填充满流内部队列的可读端所需要的大小。

实例方法
----

`TransformStreamDefaultController.enqueue()`

排入一个分块（单个数据）到流的可读端。

`TransformStreamDefaultController.error()`

转换流的可写端和可读端都出现错误。

`TransformStreamDefaultController.terminate()`

关闭流的可读端并且流的可写端出错。

示例
--

在下面的示例中，一个转换流接收所有的分块将其转换为 `Uint8Array`，使用了 `error()` 和 `enqueue()` 方法。

```js
const transformContent = {
  start() {}, // required.
  async transform(chunk, controller) {
    chunk = await chunk;
    switch (typeof chunk) {
      case "object":
        // just say the stream is done I guess
        if (chunk === null) controller.terminate();
        else if (ArrayBuffer.isView(chunk))
          controller.enqueue(
            new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength),
          );
        else if (
          Array.isArray(chunk) &&
          chunk.every((value) => typeof value === "number")
        )
          controller.enqueue(new Uint8Array(chunk));
        else if (
          "function" === typeof chunk.valueOf &&
          chunk.valueOf() !== chunk
        )
          this.transform(chunk.valueOf(), controller); // hack
        else if ("toJSON" in chunk)
          this.transform(JSON.stringify(chunk), controller);
        break;
      case "symbol":
        controller.error("Cannot send a symbol as a chunk part");
        break;
      case "undefined":
        controller.error("Cannot send undefined as a chunk part");
        break;
      default:
        controller.enqueue(this.textencoder.encode(String(chunk)));
        break;
    }
  },
  flush() {
    /\* do any destructor work here \*/
  },
};

class AnyToU8Stream extends TransformStream {
  constructor() {
    super({ ...transformContent, textencoder: new TextEncoder() });
  }
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ts-default-controller-class |

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

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


CompositionEvent - Web API 接口参考

CompositionEvent
================

DOM 接口 **`CompositionEvent`** 表示用户间接输入文本（如使用输入法）时发生的事件。此接口的常用事件有`compositionstart`, `compositionupdate` 和 `compositionend`

Event

UIEvent

CompositionEvent构造函数
----

`CompositionEvent()` (en-US)

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

属性
--

*这个接口也从`UIEvent` 和 `Event` 继承属性。*

`CompositionEvent.data` (en-US) 只读

返回触发事件的输入方法所产生的字符；取决于生成 `CompositionEvent` 对象的事件类型，结果会有所不同。

`CompositionEvent.locale` (en-US) 只读
已弃用

返回当前输入方法的场景（例如，使用输入法编辑器进行输入合成时，场景就是键盘布局）。

方法
--

*这个接口也从 `UIEvent` 和 `Event` 继承方法。*

`CompositionEvent.initCompositionEvent()` (en-US)
已弃用

初始化 `CompositionEvent` 对象的所有属性。

规范
--

| Specification |
| --- |
| UI Events # interface-compositionevent |

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

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

参见
--

* compositionstart
* compositionend
* compositionupdate
* UIEvent (en-US)
* Event


WritableStream - Web API 接口参考

WritableStream
==============

Stream API 的 **`WritableStream`** 接口为将流数据写入目的地（称为接收器）提供了一个标准的抽象。该对象带有内置的背压和队列。

`WritableStream` 是一个可转移对象。

构造函数
----

`WritableStream()`

创造一个新的 `WritableStream` 对象。

实例属性
----

`WritableStream.locked` 只读

一个布尔值，表示 `WritableStream` 是否锁定到一个 writer。

实例方法
----

`WritableStream.abort()`

中止流，使得生产者不能再成功向流写入数据（会立刻返回一个错误状态），并丢弃所有已入队的数据。

`WritableStream.close()` (en-US)

关闭流。

`WritableStream.getWriter()`

返回一个新的 `WritableStreamDefaultWriter` 实例并且将流锁定到该实例。当流被锁定时，直到这个流被释放之前，不能获取其他 writer。

示例
--

下面的例子说明了这个接口的几个功能。它展示了使用自定义 sink 和由 API 提供的队列策略创建的 `WritableStream`。然后它调用一个 `sendMessage()` 的函数，传递新创建的流和一个字符串。在这个函数内部，它调用流的 `getWriter()` 方法，该方法返回一个 `WritableStreamDefaultWriter` 实例。`forEach()` 用于将字符串的每个分块写入流。最后，`write()` 和 `close()` 方法都会返回 promise，promise 的状态由对应的操作是否成功来决定。

```js
const list = document.querySelector("ul");

function sendMessage(message, writableStream) {
  // defaultWriter is of type WritableStreamDefaultWriter
  const defaultWriter = writableStream.getWriter();
  const encoder = new TextEncoder();
  const encoded = encoder.encode(message, { stream: true });
  encoded.forEach((chunk) => {
    defaultWriter.ready
      .then(() => {
        return defaultWriter.write(chunk);
      })
      .then(() => {
        console.log("Chunk written to sink.");
      })
      .catch((err) => {
        console.log("Chunk error:", err);
      });
  });
  // Call ready again to ensure that all chunks are written
  // before closing the writer.
  defaultWriter.ready
    .then(() => {
      defaultWriter.close();
    })
    .then(() => {
      console.log("All chunks written");
    })
    .catch((err) => {
      console.log("Stream error:", err);
    });
}

const decoder = new TextDecoder("utf-8");
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });
let result = "";
const writableStream = new WritableStream(
  {
    // Implement the sink
    write(chunk) {
      return new Promise((resolve, reject) => {
        var buffer = new ArrayBuffer(1);
        var view = new Uint8Array(buffer);
        view[0] = chunk;
        var decoded = decoder.decode(view, { stream: true });
        var listItem = document.createElement("li");
        listItem.textContent = "Chunk decoded: " + decoded;
        list.appendChild(listItem);
        result += decoded;
        resolve();
      });
    },
    close() {
      var listItem = document.createElement("li");
      listItem.textContent = "[MESSAGE RECEIVED] " + result;
      list.appendChild(listItem);
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queuingStrategy,
);
sendMessage("Hello, world.", writableStream);
```

你可以在我们的简单的 writer 示例找到完整代码。

### 背压

由于 API 支持背压的方式（其在代码中的实现）可能不太明显。要了解背压是如何实现的，请注意以下三点：

* 为创建计数策略（第 35 行）而设置的 `highWaterMark` 属性，其用于设置 `WritableStream` 实例处理单个 `write()` 操作时可接受的最大数据量。在该示例中，它是可以传递给 `defaultWriter.write()` 的最大数据量（第 11 行）。
* `defaultWriter.ready` 属性返回一个当 sink（`WritableStream` 构造函数的第一个属性）完成写入数据时兑现的 promise。数据源可以写入更多的数据（第 9 行）或者调用 `close()`（第 24 行）。过早调用 close() 会阻止数据写入。这就是示例调用 `defaultWriter.ready` 两次的原因（第 9 行和第 22 行）。
* 接收器的 `write()` 方法（第 40 行）返回的 `Promise` 告诉 `WritableStream` 和它的 writer 何时去兑现 `defaultWriter.ready`。
规范
--

| Specification |
| --- |
| Streams Standard # ws-class |

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

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

参见
--

* WHATWG Stream Visualizer，用于可读、可写和转换流的基本可视化。


ValidityState - Web API 接口参考

ValidityState
=============

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
DOM 接口 `ValidityState` 代表一个元素可有的有效性状态（*validity states*），其与约束验证（constraint validation）相关。这些状态一起解释了当元素值无效时，它的值为什么不能通过验证。

属性
--

对于以下每一个布尔值属性来说，值为 `true` 表示这就是验证失败的特定原因之一；**valid** 属性是例外，它为 `true` 表示元素值满足所有的约束条件。

`badInput` (en-US) 只读

一个 `Boolean`，`true` 表示用户提供了浏览器不能转换的输入。

customError 只读

一个 `Boolean`，表示这个元素的自定义验证信息是否已通过调用元素的 `setCustomValidity()` (en-US) 方法设置为一个非空字符串。

`patternMismatch` (en-US) 只读

一个 `Boolean`，`true` 表示元素值不匹配规定的`pattern`，`false` 则表示匹配。`true` 的时候元素可用 CSS 伪类 `:invalid` 匹配。

`rangeOverflow` (en-US) 只读

一个 `Boolean`，`true` 表示值已超过 `max` 属性规定的最大值，`false` 则表示小于或等于这个最大值。`true` 的时候元素可用 CSS 伪类 `:invalid` 和 `:out-of-range` 匹配。

`rangeUnderflow` (en-US) 只读

一个 `Boolean`，`true` 表示值小于 `min` 属性规定的最小值，`false` 则表示大于或等于这个最小值。`true` 的时候元素可用 CSS 伪类 `:invalid` 和 `:out-of-range` 匹配。

`stepMismatch` (en-US) 只读

一个 `Boolean`，`true` 表示值不符合由 `step` 属性规定的规则（即该值不能被步长值除尽，译注：假设最小值是 0）。`false` 表示其符合步长值规则。`true` 的时候元素可用 CSS 伪类 `:invalid` 和 `:out-of-range` 匹配。

`tooLong` (en-US) 只读

一个 `Boolean`，`true` 表示值超过了`HTMLInputElement` 或 `HTMLTextAreaElement` 对象中规定的 `maxlength`， `false` 表示值的长度小于或等于最大长度。**注意**：这个属性在 Gecko 中永远不会是 `true`，因为元素值不允许比 `maxlength` 长。`true` 的时候元素可用 CSS 伪类 `:invalid` 和 `:out-of-range` 匹配。

`tooShort` (en-US) 只读

一个 `Boolean`，`true` 表示值的长度小于 `HTMLInputElement` 或 `HTMLTextAreaElement` 对象中规定的 `minlength`， `false` 表示值的长度大于或等于最大长度。`true` 的时候元素可用 CSS 伪类 `:invalid` 和 `:out-of-range` 匹配。

`typeMismatch` (en-US) 只读

一个 `Boolean`，`true` 表示元素值不满足所需的格式（可见于 `type` 是 `email` 或 `url` 时），`false` 表示格式正确。`true` 的时候元素可用 CSS 伪类 `:invalid` 匹配。

valid 只读

一个 `Boolean`，`true` 表示元素满足所有的验证约束，因此被认为时有效的，`false` 表示有任一约束不满足。`true` 的时候元素可用 CSS 伪类 `:valid` 匹配，否则可用 CSS 伪类 `:invalid` 匹配。

`valueMissing` (en-US) 只读

一个 `Boolean`， `true` 表示元素拥有 `required` 属性，但没有值，否则为 `false`。`true` 的时候元素可用 CSS 伪类 `:invalid` 匹配。

规范
--

| Specification |
| --- |
| HTML Standard # the-constraint-validation-api:validitystate-3 |

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

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

参见
--

* 约束验证
* 表单数据校验


WindowTimers.clearInterval() - Web API 接口参考

WindowTimers.clearInterval()
============================

`WindowOrWorkerGlobalScope` mixin 的 **`clearInterval()`** 方法可取消先前通过 `setInterval()` 设置的重复定时任务。

语法
--
```

scope.clearInterval(intervalID)
```

### Parameters

`intervalID`

要取消的定时器的 ID。是由 `setInterval()` 返回的。

值得一提的是，`setInterval()` 和 `setTimeout()` 共用其定义的 IDs，即可以使用 `clearInterval()` 和 `clearTimeout()` 中的任意一个。然而，为了使代码可读性更强，你应该尽量避免这种用法。

### 返回值

`undefined`示例
--

查看 `setInterval()` 的示例。

规范
--

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

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

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

参见
--

* JavaScript 定时器
* `setTimeout`
* `setInterval`
* `clearTimeout`
* `Window.requestAnimationFrame`
* *Daemons* management


RTCSessionDescription - Web API 接口参考

RTCSessionDescription
=====================

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

**`RTCSessionDescription`** 接口描述连接或潜在连接的一端的配置方式。每一个`RTCSessionDescription` 由一个描述类型组成，该描述类型指示它所描述的请求/应答协商过程的SDP 协议的相关描述。

`RTCSessionDescription` 在两个对等点之间协商连接的过程涉及来回交换对象，每个描述都表示描述的发送者支持的连接配置选项的一个组合。一旦两个对等方就连接的配置达成一致，协商就完成了。

属性
--

*`RTCSessionDescription` 接口不继承任何属性*

`RTCSessionDescription.type` (en-US) 只读

`RTCSdpType` 会话描述类型的原型枚举。

`RTCSessionDescription.sdp` (en-US) 只读

一个 `DOMString` 包含会话的SDP协议描述。

常数
--

### RTCSdpType

当前枚举值定义当前会话描述的状态，例如这个属性： `type` (en-US) 。会话描述的值将使用如下值之一。

| Value | Description |
| --- | --- |
| `answer` | SDP 协议请求内容包含在属性`sdp` (en-US)中。换言之，此会话描述描述了商定的配置，并将被发送以完成协商。. |
| `offer` | 该会话描述对象描述首次握手的请求/响应。会话过程从发送方到接收方。 |
| `pranswer` | 会话描述对象描述一个临时响应；也就是说，它是对以前的提议或临时答案的响应。 |
| `rollback` | 具有空会话描述的这种特殊类型用于回滚到以前的稳定状态。 |

方法
--

*`RTCSessionDescription` 不继承任何方法。*

`RTCSessionDescription()` (en-US)
已弃用

该构造函数返回一个新的 `RTCSessionDescription` 对象。参数是 `RTCSessionDescriptionInit` 字典包含包含分配这两个属性的值。

`RTCSessionDescription.toJSON()` (en-US)

返回一个JSON 描述对象。该对象包含两个值，`type` (en-US) 和`sdp` (en-US)。

示例
--

```js
signalingChannel.onmessage = function (evt) {
  if (!pc) start(false);

  var message = JSON.parse(evt.data);
  if (message.sdp)
    pc.setRemoteDescription(
      new RTCSessionDescription(message),
      function () {
        // if we received an offer, we need to answer
        if (pc.remoteDescription.type == "offer")
          pc.createAnswer(localDescCreated, logError);
      },
      logError,
    );
  else
    pc.addIceCandidate(
      new RTCIceCandidate(message.candidate),
      function () {},
      logError,
    );
};
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # rtcsessiondescription-class |

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

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

参见
--

* WebRTC
* `RTCPeerConnection.setLocalDescription()` (en-US) 和 `RTCPeerConnection.setRemoteDescription()`


AudioWorkletNode - Web API 接口参考

AudioWorkletNode
================

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

虽然这个接口可以在 secure contexts 之外调用，但是 `BaseAudioContext.audioWorklet` (en-US) 属性不行，从而 `AudioWorkletProcessor` 不能在外部定义。

Web Audio API 中的 **`AudioWorkletNode`** 接口代表了用户定义的`AudioNode`的基类，该基类可以与其他节点一起连接到音频路由图。其具有关联的`AudioWorkletProcessor`, 它在 Web Audio 执行实际的音频处理。

构造函数
----

`AudioWorkletNode()` (en-US)

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

属性
--

*也继承父类的属性，`AudioNode`*.

`AudioWorkletNode.port` (en-US) 只读

返回一个 `MessagePort` 用于节点与其关联的 `AudioWorkletProcessor` 间的双向通讯。另一端在处理器属性`port` (en-US) 下可用。

`AudioWorkletNode.parameters` (en-US) 只读

返回一个 `AudioParamMap` (en-US) — `AudioParam` 对象的集合。它们在创建 `AudioWorkletProcessor`的过程中被实例化。如果 `AudioWorkletProcessor` 有一个静态的 `parameterDescriptors` (en-US) getter，从其返回的 `AudioParamDescriptor` 数组用于在 `AudioWorkletNode` 创建 `AudioParam` 对象。通过这种机制，使得 `AudioParam` 对象可以从 `AudioWorkletNode` 中访问。你可以在与其关联的 `AudioWorkletProcessor` 中使用它的值。

### Event handlers

`AudioWorkletNode.onprocessorerror` (en-US)

在关联的 `AudioWorkletProcessor` 对象发生异常时触发。一旦触发，处理器及其节点将在其整个生命周期内处于输出静默状态。

方法
--

*同样继承了其父类的方法，`AudioNode`*.

*AudioWorkletNode 接口未定义其自己的任何方法。*

示例
--

在本示例中我们创建了 `AudioWorkletNode` 对象，它会输出白噪声。

首先，我们需要定义一个自定义的 `AudioWorkletProcessor`, 它将输出白噪声并进行注册。注意，这需要在一个单独的文件中完成。

```js
// white-noise-processor.js
class WhiteNoiseProcessor extends AudioWorkletProcessor {
  process(inputs, outputs, parameters) {
    const output = outputs[0];
    output.forEach((channel) => {
      for (let i = 0; i < channel.length; i++) {
        channel[i] = Math.random() \* 2 - 1;
      }
    });
    return true;
  }
}

registerProcessor("white-noise-processor", WhiteNoiseProcessor);
```

接下来，在脚本主文件中一个 `AudioWorkletNode` 实例，并传递处理器的名称，然后将该实例连接到一个 audio graph.

```js
const audioContext = new AudioContext();
await audioContext.audioWorklet.addModule("white-noise-processor.js");
const whiteNoiseNode = new AudioWorkletNode(
  audioContext,
  "white-noise-processor",
);
whiteNoiseNode.connect(audioContext.destination);
```

规范
--

| Specification |
| --- |
| Web Audio API # AudioWorkletNode |

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

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

See also
--------

* Web Audio API
* Using the Web Audio API


AbortController - Web API 接口参考

AbortController
===============

**`AbortController`** 接口表示一个控制器对象，允许你根据需要中止一个或多个 Web 请求。

你可以使用 `AbortController.AbortController()` 构造函数创建一个新的 `AbortController`。使用 `AbortSignal` 对象可以完成与 DOM 请求的通信。

构造函数
----

`AbortController.AbortController()`

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

属性
--

`AbortController.signal` 只读

返回一个 `AbortSignal` 对象实例，可以用它与一个 DOM 请求进行通信或者中止该请求。

方法
--

`AbortController.abort()`

中止一个尚未完成的 Web（网络）请求。这能够中止 fetch 请求及任何响应体的消费和流。

示例
--

**备注：** `AbortSignal` 中还有其他额外的示例。

在下面的代码片段中，我们想通过 Fetch API 下载一段视频。

我们先使用 `AbortController()` 构造函数创建一个控制器，然后使用 `AbortController.signal` 属性获取其关联 `AbortSignal` 对象的引用。

当 fetch 请求初始化时，我们将 `AbortSignal` 作为一个选项传递进入请求的选项对象中（下面的 `{signal}`）。这将 signal 和 controller 与 fetch 请求相关联，并且允许我们通过调用 `AbortController.abort()` 去中止它，如下面的第二个事件监听器。

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

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

downloadBtn.addEventListener("click", fetchVideo);

abortBtn.addEventListener("click", () => {
  if (controller) {
    controller.abort();
    console.log("中止下载");
  }
});

function fetchVideo() {
  controller = new AbortController();
  const signal = controller.signal;
  fetch(url, { signal })
    .then((response) => {
      console.log("下载完成", response);
    })
    .catch((err) => {
      console.error(`下载错误：${err.message}`);
    });
}
```

**备注：** 当 `abort()` 被调用时，这个 `fetch()` promise 将 `reject` 一个名为 `AbortError` 的 `DOMException`。

你可以在 GitHub 上找到这个示例的完整源代码（也可以在线运行）。

规范
--

| Specification |
| --- |
| DOM Standard # interface-abortcontroller |

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

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

参见
--

* Fetch API
* Abortable Fetch by Jake Archibald


TextDecoder - Web API 接口参考

TextDecoder
===========

**`TextDecoder`** 接口表示一个文本解码器，一个解码器只支持一种特定文本编码，例如 `UTF-8`、`ISO-8859-2`、`KOI8-R`、`GBK`，等等。解码器将字节流作为输入，并提供码位流作为输出。

**备注：** 此特性在 Web Worker 中可用

构造函数
----

`TextDecoder()`

返回一个新构造的 `TextDecoder`，它使用参数中指定的解码方法生成码位流。

属性
--

*`TextDecoder` 接口不继承任何属性。*

`TextDecoder.prototype.encoding`只读

一个包含的解码器名称的字符串，即描述 `TextDecoder` 将使用的方法的字符串。

`TextDecoder.prototype.fatal`只读

一个布尔值，表示错误模式是否致命。

`TextDecoder.prototype.ignoreBOM` 只读

一个布尔值，表示是否忽略字节顺序标记（BOM）标记。

方法
--

*`TextDecoder` 接口不继承任何方法*。

`TextDecoder.prototype.decode()`

返回一个字符串，其中包含使用特定 `TextDecoder` 对象的方法解码的文本。

示例
--

### 用类型化数组表示文本

本示例展示如何解码中文/日语字符
 ![](/zh-CN/docs/Web/API/TextDecoder/2019-05-21_191907.png)，用五个不同的类型化数组表示：`Uint8Array`、`Int8Array`、`Uint16Array`、`Int16Array` 和 `Int32Array`。

```js
let utf8decoder = new TextDecoder(); // default 'utf-8' or 'utf8'

let u8arr = new Uint8Array([240, 160, 174, 183]);
let i8arr = new Int8Array([-16, -96, -82, -73]);
let u16arr = new Uint16Array([41200, 47022]);
let i16arr = new Int16Array([-24336, -18514]);
let i32arr = new Int32Array([-1213292304]);

console.log(utf8decoder.decode(u8arr));
console.log(utf8decoder.decode(i8arr));
console.log(utf8decoder.decode(u16arr));
console.log(utf8decoder.decode(i16arr));
console.log(utf8decoder.decode(i32arr));
```

### 处理非 UTF8 文本

在此示例中，我们对俄语文本“Привет，мир！”进行编码，它的意思是（"Hello, world."）。在我们的 `TextDecoder()` 构造函数中，我们指定适用于西里尔字母的 Windows-1251 字符编码。

```js
const win1251decoder = new TextDecoder("windows-1251");
const bytes = new Uint8Array([
  207, 240, 232, 226, 229, 242, 44, 32, 236, 232, 240, 33,
]);
console.log(win1251decoder.decode(bytes)); // Привет, мир!
```

规范
--

| Specification |
| --- |
| Encoding Standard # interface-textdecoder |

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

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

参见
--

* `TextEncoder` 接口描述了逆操作。
* 一个垫片，允许在不支持它的浏览器使用这个接口。
* Node.js 从 v11.0.0 开始支持全局导出


WebGLContextEvent - Web API 接口参考

WebGLContextEvent
=================

**WebContextEvent** 接口属于 WebGL API 的一部分，同时也是生成用来对 WebGL 渲染上下文作响应的事件接口。

继承
--

**此接口从它的父接口 `Event`继承属性和方法。**

Event

WebGLContextEvent属性
--

**此接口从它的父接口 `Event`继承属性。**

`WebGLContextEvent.statusMessage` (en-US)

一个包含事件额外信息的只读属性。

方法
--

*此接口本身并没有定义任何方法，而是从它的父接口 `Event` 继承方法。*

示例
--

使用 `WEBGL_lose_context` 插件，你可以模拟 `webglcontextlost` 和 `webglcontextrestored` (en-US) 事件：

```js
var canvas = document.getElementById("canvas");
var gl = canvas.getContext("webgl");

canvas.addEventListener(
  "webglcontextlost",
  function (e) {
    console.log(e);
  },
  false,
);

gl.getExtension("WEBGL\_lose\_context").loseContext();

// 记录了 "webglcontextlost" 类型的 WebGLContextEvent 事件
```

规范
--

| Specification |
| --- |
| WebGL Specification # 5.15 |

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

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

相关内容
----

* `WebGLRenderingContext.isContextLost()`
* `WEBGL_lose_context`, `WEBGL_lose_context.loseContext()`, `WEBGL_lose_context.restoreContext()`
* 事件：webglcontextlost, webglcontextrestored (en-US), webglcontextcreationerror (en-US)


DragEvent - Web API 接口参考

DragEvent
=========

**`DragEvent`** 是一个表示拖、放交互的一个`DOM event` 接口。用户通过将指针设备（例如鼠标）放置在触摸表面上并且然后将指针拖动到新位置（诸如另一个 DOM 元素）来发起拖动。应用程序可以按应用程序特定的方式自由解释拖放交互。

这个接口继承 `MouseEvent` 和`Event`属性

属性
--

`DragEvent.dataTransfer` 只读

在拖放交互期间传输的数据。

构造函数
----

虽然这个接口有一个构造函数，但不可能从脚本创建一个有用的 DataTransfer 对象，因为在拖放期间，有一个由浏览器分配的一个处理中和安全模式的`DataTransfer`对象。

`DragEvent()`

创建合成和不可信的 DragEvent.

事件类型
----

`drag`

拖动元素或选择文本时触发此事件。

`dragend`

当拖动操作结束时（释放鼠标按钮或按下退出键），会触发此事件。

`dragenter`

当拖动的元素或选择文本输入有效的放置目标时，会触发此事件。

`dragleave`

当拖动的元素或文本选择离开有效的放置目标时，会触发此事件。

`dragover`

当将元素或文本选择拖动到有效放置目标（每几百毫秒）上时，会触发此事件。

`dragstart`

当用户开始拖动元素或选择文本时触发此事件。

`drop`

当在有效放置目标上放置元素或选择文本时触发此事件。

全局事件处理
------

`GlobalEventHandlers.ondrag`

`drag` 事件的`全局事件处理`。

`GlobalEventHandlers.ondragend` (en-US)

`dragend` 事件的`全局事件处理`。

`GlobalEventHandlers.ondragenter` (en-US)

`dragenter` 事件的`全局事件处理`。

`GlobalEventHandlers.ondragexit` (en-US)

`dragleave` 事件的`全局事件处理`。

`GlobalEventHandlers.ondragover` (en-US)

`dragover` 事件的`全局事件处理`。

`GlobalEventHandlers.ondragstart` (en-US)

`dragstart` 事件的`全局事件处理`。

`GlobalEventHandlers.ondrop`

`drop` 事件的`全局事件处理`。

示例
--

每个属性，构造函数，事件类型和全局事件处理程序的示例都包含在它们各自的参考页中。

规范
--

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

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

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


CSS 属性和值 API - Web API 接口参考

CSS 属性和值 API
============

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

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

* Learn more
* See full compatibility
* Report feedback
**CSS 属性和值 API**（CSS Properties and Values API）——CSS Houdini API 的一部分——允许开发者显式地定义它们的 `CSS 自定义属性`，允许设置属性类型检查、默认值以及是否可继承其值。

接口
--

`CSS.registerProperty` (en-US)

定义了浏览器应该如何解析 `CSS custom properties`。通过 JavaScript 中的 `CSS.registerProperty` (en-US) 访问该接口。

`@property`

定义了浏览器应该如何解析 `CSS custom properties`。通过 CSS 中的 `@property` at 规则访问该接口。

示例
--

以下代码在 JavaScript 中使用 `CSS.registerProperty` (en-US) 输入一个 `CSS 自定义属性`，`--my-color`，将其作为一个颜色，然后为其设置一个默认值，并且不允许继承它的值。

```js
window.CSS.registerProperty({
  name: "--my-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "#c0ffee",
});
```

可以在 CSS 中使用 `@property` at-rule 进行相同的注册：

```css
@property --my-color {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}
```

规范
--

| Specification |
| --- |
| CSS Properties and Values API Level 1 # the-css-property-rule-interface |
| CSS Properties and Values API Level 1 # the-registerproperty-function |

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

### api.CSSPropertyRule

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

### api.CSS.registerProperty\_static

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

参见
--

* 使用 CSS 属性和值 API (en-US)
* CSS Painting API (en-US)
* CSS 类型对象模型 (en-US)
* Houdini API


Attr - Web API 接口参考

Attr
====

**`Attr`** 接口将一个元素的属性（attribute）表示为一个对象。在大多数情况下，你可以直接以字符串形式检索属性值（例如 `Element.getAttribute()`），但某些函数（例如 `Element.getAttributeNode()`）或迭代方法则返回 `Attr` 实例。

EventTarget

Node

Attr
`Attr` 对象的核心思想是将*名称*和*值*关联起来。属性也可能属于一个*命名空间*，在这种情况下，它还有一个表示命名空间的 URI，以及一个作为命名空间的缩写的前缀。

当该名称忽略最终的命名空间前缀时，则认为该名称是*本地的*；当该名称包含命名空间的前缀时，则认为该名称是被*限定的*，如果存在前缀，则将其通过冒号（`:`）与本地名分隔。一共有三种情况：属性不在命名空间中、属性在命名空间中但没有定义前缀、属性在命名空间中且定义了前缀：

| 属性 | 命名空间名 | 命名空间前缀 | 属性的本地名 | 属性的限定名 |
| --- | --- | --- | --- | --- |
| `myAttr` | *无* | *无* | `myAttr` | `myAttr` |
| `myAttr` | `mynamespace` | *无* | `myAttr` | `myAttr` |
| `myAttr` | `mynamespace` | `myns` | `myAttr` | `myns:myAttr` |

**备注：** 该接口仅表示 `Element` 树中存在的属性（attribute），无论是 SVG、HTML 还是 MathML 元素。它不表示与此类元素相关的接口的*属性*（property），例如 `<table>` 元素的 `HTMLTableElement`。（有关元素属性（attribute）及其如何*反射*到接口属性（property）的更多信息，请参见这篇文章。）

实例属性
----

*此接口还从其父接口 `Node`、`EventTarget` 基础属性。*

`localName` 只读

一个表示属性限定名的本地部分的字符串。

`name` (en-US) 只读

该属性的*限定名*。如果该属性不在命名空间中，则其与 `localName` 属性相同。

`namespaceURI` 只读

一个表示该属性的命名空间 URI 的字符串，如果没有命名空间，则返回 `null`。

`ownerElement` (en-US) 只读

该属性所附属的元素。

`prefix` 只读

一个表示该属性的命名空间前缀的字符串，如果命名空间没有前缀或没有指定命名空间则返回 `null`。

`specified` (en-US) 只读
已弃用

该属性总是返回 `true`。

`value` (en-US)

属性的值，其为一个可以通过接口属性进行设置和获取的字符串。

实例方法
----

*此接口无具体方法，但继承了其父接口 `Node`、`EventTarget` 的方法。*

规范
--

| Specification |
| --- |
| DOM Standard # interface-attr |

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

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

参见
--

* 其他的节点有 `CDATASection`、`CharacterData`、`Comment`、`Document`、`Element`、`ProcessingInstruction` (en-US) 和 `Text` (en-US)。


WebGLShaderPrecisionFormat - Web API 接口参考

WebGLShaderPrecisionFormat
==========================

**WebGLShaderPrecisionFormat** 接口是WebGL API 的一部分，它表示通过调用`WebGLRenderingContext.getShaderPrecisionFormat()` (en-US)返回信息的信息。

属性
--

`WebGLShaderPrecisionFormat.rangeMin` (en-US)

以 2 为底的最小值的绝对值的对数。

`WebGLShaderPrecisionFormat.rangeMax` (en-US)

可以表示的最大值的绝对值的底数为 2 的对数。

`WebGLShaderPrecisionFormat.precision` (en-US)

可以表示的精度位的数目。对于整数类型，这个值总是 0。

示例
--

`WebGLShaderPrecisionFormat` 对象通过`WebGLRenderingContext.getShaderPrecisionFormat()` (en-US) 方法来返回。

```js
var canvas = document.getElementById("canvas");
var gl = canvas.getContext("webgl");
gl.getShaderPrecisionFormat(gl.VERTEX\_SHADER, gl.MEDIUM\_FLOAT);
// WebGLShaderPrecisionFormat { rangeMin: 127, rangeMax: 127, precision: 23 }
```

规格
--

| Specification |
| --- |
| WebGL Specification # 5.12 |

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

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

参见
--

* `WebGLRenderingContext.getShaderPrecisionFormat()` (en-US)


DOMException - Web API 接口参考

DOMException
============

**`DOMException`** 接口代表调用方法或访问 Web API 属性时发生的不正常事件（被称为**异常**，**exception**）。这就是 Web API 中描述错误条件的方式。

每个异常都有一个**名称**（name），一个采用驼峰命名法的简短字符串，用于描述识别错误或异常情况。

`DOMException` 是一个可序列化对象，因此可以使用 `structuredClone()` 克隆，或使用 `postMessage()` 在 Worker 之间复制。

构造函数
----

`DOMException()`

返回一个包含指定消息和名称的 `DOMException` 对象。

实例属性
----

`DOMException.code`
已弃用
 只读

返回任意一个遗留错误代码常量，如果不匹配则返回 `0`。

`DOMException.message` 只读

返回一个字符串，代表与给定的错误名称有关的信息或描述。

`DOMException.name` 只读

返回一个字符串，包含与错误名称相关的字符串。

错误名称
----

常见的错误名称列在这里。一些 API 定义了它们自己的名称组，所以这未必是一个完整的列表。

请注意，以下已废弃的历史错误没有错误名称，而只有遗留常量代码值和遗留常量名称：

* 遗留代码值：`2`，遗留常量名称：`DOMSTRING_SIZE_ERR`
* 遗留代码值：`6`，遗留常量名称：`NO_DATA_ALLOWED_ERR`
* 遗留代码值：`16`，遗留常量名称：`VALIDATION_ERR`

**备注：** 由于历史上错误是通过一个数值来识别的，该数值与定义为该数值的命名变量相对应，因此下面的一些条目指出了过去使用的历史代码值和常量名称。

`IndexSizeError`

索引不在允许的范围内。例如，这可以被 `Range` 对象抛出。（遗留代码值：`1`，遗留常量名称：`INDEX_SIZE_ERR`）

`HierarchyRequestError`

节点树层次结构有误。（遗留代码值：`3`，遗留常量名称：`HIERARCHY_REQUEST_ERR`）

`WrongDocumentError`

对象在错误的 `Document` 中。（遗留代码值：`4`，遗留常量名称：`WRONG_DOCUMENT_ERR`）

`InvalidCharacterError`

字符串包含无效字符。（遗留代码值：`5`，遗留常量名称：`INVALID_CHARACTER_ERR`）

`NoModificationAllowedError`

对象不能被修改。（遗留代码值：`7`，遗留常量名称：`NO_MODIFICATION_ALLOWED_ERR`）

`NotFoundError`

找不到对象。（遗留代码值：`8`，遗留常量名称：`NOT_FOUND_ERR`）

`NotSupportedError`

不支持的操作。（遗留代码值：`9`，遗留常量名称：`NOT_SUPPORTED_ERR`）

`InvalidStateError`

对象是一个无效的状态。（遗留代码值：`11`，遗留常量名称：`INVALID_STATE_ERR`）

`SyntaxError`

字符串不匹配预期的模式。（遗留代码值：`12`，遗留常量名称：`SYNTAX_ERR`）

`InvalidModificationError`

对象不能被这种方式修改。（遗留代码值：`13`，遗留常量名称：`INVALID_MODIFICATION_ERR`）

`NamespaceError`

操作在 XML 名称空间是不允许的。（遗留代码值：`14`，遗留常量名称：`NAMESPACE_ERR`）

`InvalidAccessError`

对象不支持此操作或参数。（遗留代码值：`15`，遗留常量名称：`INVALID_ACCESS_ERR`）

`TypeMismatchError`
已弃用

对象的类型不匹配预期的类型。（遗留代码值：`17`，遗留常量名称：`TYPE_MISMATCH_ERR`）。这个值已被弃用，现在会抛出 JavaScript `TypeError` 异常而不是含有该值的 `DOMException`。

`SecurityError`
实验性

操作不安全。（遗留代码值：`18`，遗留常量名称：`SECURITY_ERR`）

`NetworkError`
实验性

网络错误发生。（遗留代码值：`19`，遗留常量名称：`NETWORK_ERR`）

`AbortError`
实验性

操作中止。（遗留代码值：`20`，遗留常量名称：`ABORT_ERR`）

`URLMismatchError`
实验性

给定的 URL 不匹配另一个 URL。（遗留代码值：`21`，遗留常量名称：`URL_MISMATCH_ERR`）

`QuotaExceededError`
实验性

超出给定配额。（遗留代码值：`22`，遗留常量名称：`QUOTA_EXCEEDED_ERR`）

`TimeoutError`
实验性

操作超时。（遗留代码值：`23`，遗留常量名称：`TIMEOUT_ERR`）

`InvalidNodeTypeError`
实验性

这个操作的节点是不正确的或祖先是不正确的。（遗留代码值：`24`，遗留常量名称：`INVALID_NODE_TYPE_ERR`）

`DataCloneError`
实验性

对象不可被克隆。（遗留代码值：`25`，遗留常量名称：`DATA_CLONE_ERR`）

`EncodingError`
实验性

编码或解码操作失败（没有遗留代码值和常量的名字）。

`NotReadableError`
实验性

输入/输出读操作失败（没有遗留代码值和常量的名字）。

`UnknownError`
实验性

因未知的瞬态的原因使操作失败（例如内存不足）（没有遗留代码值和常量的名字）。

`ConstraintError`
实验性

条件没满足而导致事件失败的异常操作（没有遗留代码值和常量的名字）。

`DataError`
实验性

提供的数据不足（没有遗留代码值和常量的名字）。

`TransactionInactiveError`
实验性

请求被当前不活跃的事件或已完成事件阻止（没有遗留代码值和常量的名字）。

`ReadOnlyError`
实验性

尝试操作“只读”事件（没有遗留代码值和常量的名字）。

`VersionError`
实验性

尝试打开一个比现有版本更低的数据库（没有遗留代码值和常量的名字）。

`OperationError`
实验性

因特定操作失败原因而失败（没有遗留代码值和常量的名字）。

`NotAllowedError`
实验性

当前上下文中的用户代理或平台不允许该请求，可能是因为用户拒绝了授权（没有遗留代码值和常量的名字）。

规范
--

| Specification |
| --- |
| Web IDL Standard # idl-DOMException |

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

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

参见
--

* `DOMError`


CharacterData - Web API 接口参考

CharacterData
=============

**`CharacterData`** 抽象接口（abstract interface）代表 `Node` 对象包含的字符。这是一个抽象接口，意味着没有 `CharacterData` 类型的对象。它是在其他接口中被实现的，如 `Text` (en-US)、`Comment` 或 `ProcessingInstruction` (en-US) 这些非抽象接口。

属性
--

*从其父级 `Node` 继承属性，并且实现了 `ChildNode` 和 `NonDocumentTypeChildNode` (en-US) 接口。*

`CharacterData.data` (en-US)

一个 `DOMString`，表示该对象中包含的文本数据。

`CharacterData.length` (en-US) 只读

返回一个 `unsigned long` 的表示 `CharacterData.data` 包含的字符串的大小。

`NonDocumentTypeChildNode.nextElementSibling` 只读

返回其父节点所在的子节点列表（children list）中紧跟着的元素节点 `Element`，或者 `null`。

`NonDocumentTypeChildNode.previousElementSibling` 只读

返回其父节点所在的子节点列表（children list）中前一个元素节点 `Element`，或者 `null`。

方法
--

*从其父级 `Node` 继承方法，并且实现了 `ChildNode` 和*`NonDocumentTypeChildNode` (en-US) 接口。

`CharacterData.appendData()` (en-US)

为 `CharacterData.data` 字符串追加指定的 `DOMString` ；当方法返回时，`data` 包含的是已合并的 `DOMString`.

`CharacterData.deleteData()` (en-US)

在 `CharacterData.data` 字符串中，从指定位置开始，删除指定数量的字符；当方法返回时，`data` 包含的是缩短了的 `DOMString`.

`CharacterData.insertData()` (en-US)

在 `CharacterData.data` 字符串中，在指定的位置，插入指定的字符；当方法返回时，`data` 包含的是已修改的 `DOMString`.

`ChildNode.remove()` (en-US)
实验性

把对象从其父节点的 children list 中删除。

`CharacterData.replaceData()` (en-US)

在 `CharacterData.data` 字符串中，从指定位置开始，把指定数量的字符替换为指定的 `DOMString`; 当方法返回时，`data` 包含的是已修改的 `DOMString`.

`CharacterData.substringData()` (en-US)

返回一个包含了从`CharacterData.data` 中的指定位置开始，指定长度的 `DOMString` 。

规范
--

| Specification |
| --- |
| DOM Standard # interface-characterdata |

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

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

参见
--

* The DOM interfaces index (en-US).


FileSystemWritableFileStream - Web API 接口参考

FileSystemWritableFileStream
============================

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

文件系统 API 的 **`FileSystemWritableFileStream`** 接口是一类附加了便于操作磁盘上单个文件的方法的 `WritableStream` 对象。这个接口通过 `FileSystemFileHandle.createWritable()` 方法来访问。

WritableStream

FileSystemWritableFileStream实例属性
----

*继承父接口 `WritableStream` 的属性。*

实例方法
----

*继承父接口 `WritableStream` 的方法。*

`FileSystemWritableFileStream.write()`

向调用此方法的文件写入内容，写入到文件当前指针偏移处。

`FileSystemWritableFileStream.seek()`

更新文件当前指针偏移到指定位置（以字节为单位）。

`FileSystemWritableFileStream.truncate()`

将与流相关联的文件调整为指定的字节大小。

示例
--

下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 `FileSystemFileHandle`。由此，使用 `FileSystemFileHandle.createWritable()` 方法创建一个写入流。

然后向流中写入一个文本字符串，随后关闭该流。

```js
async function saveFile() {
  // 创建一个新句柄。
  const newHandle = await window.showSaveFilePicker();

  // 创建一个 FileSystemWritableFileStream 用于写入。
  const writableStream = await newHandle.createWritable();

  // 写入我们的文件。
  await writableStream.write("This is my file content");

  // 关闭文件并将内容写入磁盘。
  await writableStream.close();
}
```

下面的例子展示能够向 `write()` 方法传递的不同选项。

```js
// 只传递数据（没有选项）
writableStream.write(data);

// 向流中指定位置写入数据
writableStream.write({ type: "write", position, data });

// 将文件当前的指针更新到指定的偏移位置
writableStream.write({ type: "seek", position });

// 调整文件至指定字节长度
writableStream.write({ type: "truncate", size });
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemwritablefilestream |

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

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

参见
--

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


URL - Web API 接口参考

URL
===

**`URL`** 接口用于解析，构造，规范化和编码 URL。它通过提供允许你轻松阅读和修改 URL 组件的属性来工作。通常，通过在调用 URL 的构造函数时将 URL 指定为字符串或提供相对 URL 和基本 URL 来创建新的 URL 对象。然后，你可以轻松读取 URL 的已解析组成部分或对 URL 进行更改。

如果浏览器尚不支持`URL()`构造函数，则可以使用`Window`中的`Window.URL` (en-US)属性。确保检查你的任何目标浏览器是否要求对此添加前缀。

**备注：** 此特性在 Web Worker 中可用

构造器
---

`new URL()`

创建并返回一个`URL`对象，该 URL 对象引用使用绝对 URL 字符串，相对 URL 字符串和基本 URL 字符串指定的 URL。

属性
--

`hash`

包含`'#'`的`USVString`，后跟 URL 的片段标识符。

`host`

一个`USVString`，其中包含域（即主机名），后跟（如果指定了端口）“：”和 URL 的端口。

`hostname`

包含 URL 域名的 `USVString`。

`href`

包含完整 URL 的 `USVString`。

`origin` 只读

返回一个包含协议名、域名和端口号的 `USVString`。

`password`

包含在域名前面指定的密码的 `USVString` 。

`pathname`

以 '/' 起头紧跟着 URL 文件路径的 `DOMString`。

`port`

包含 URL 端口号的 `USVString`。

`protocol`

包含 URL 协议名的 `USVString`，末尾带 `':'`。

`search`

一个`USVString` ，指示 URL 的参数字符串；如果提供了任何参数，则此字符串包括所有参数，并以开头的“？”开头 字符。

`searchParams` 只读

`URLSearchParams`对象，可用于访问`search`中找到的各个查询参数。

`username`

包含在域名前面指定的用户名的 `USVString`。

方法
--

`toString()`

返回包含整个 URL 的`USVString`。它是`URL.href`的同义词，尽管它不能用于修改值。

`toJSON()`

返回包含整个 URL 的`USVString`。它返回与`href`属性相同的字符串。

静态方法
----

`createObjectURL()`

返回一个`DOMString` ，包含一个唯一的 blob 链接（该链接协议为以 blob:，后跟唯一标识浏览器中的对象的掩码）。

`revokeObjectURL()`

销毁之前使用`URL.createObjectURL()`方法创建的 URL 实例。

使用说明
----

如果`url`参数是相对 URL，则构造函数将使用`url`参数和可选的`base`参数作为基础。
```

const url = new URL('../cats', 'http://www.example.com/dogs');
console.log(url.hostname); // "www.example.com"
console.log(url.pathname); // "/cats"
```

可以设置 URL 属性以构造 URL：
```

url.hash = 'tabby';
console.log(url.href); // "http://www.example.com/cats#tabby"
```

URL 根据 RFC 3986中的规则进行编码。例如：
```

url.pathname = 'démonstration.html';
console.log(url.href); // "http://www.example.com/d%C3%A9monstration.html"
```

`URLSearchParams`接口可用于构建和处理 URL 查询字符串。

要从当前窗口的 URL 获取搜索参数，可以执行以下操作：
```

// https://some.site/?id=123
const parsedUrl = new URL(window.location.href);
console.log(parsedUrl.searchParams.get("id")); // "123"
```

URL 的`toString()`方法仅返回`href` 属性的值，因此构造函数可以 用于直接对 URL 进行规范化和编码。
```

const response = await fetch(new URL('http://www.example.com/démonstration.html'));
```

规范
--

| Specification |
| --- |
| URL Standard # url |

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

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

参见
--

* `core-js` 中针对 `URL` 的 polyfill
* URL API
* 什么是 URL？
* 获取 `URL` 对象的属性：`URL`
* `URLSearchParams`


FileList - Web API 接口参考

FileList
========

一个 FileList 对象通常来自于一个 HTML `<input>` 元素的 `files` 属性，你可以通过这个对象访问到用户所选择的文件。该类型的对象还有可能来自用户的拖放操作，查看 `DataTransfer` (en-US) 对象了解详情。

**备注：** 在 Gecko 1.9.2 之前，通过 `input` 元素，每次只能选择一个文件，这意味着该 `input` 元素的 `files` 属性上的 FileList 对象无论如何都只能包含一个文件。从 Gecko 1.9.2 开始，如果一个 `input` 元素拥有 `multiple` 属性，则可以用它来选择多个文件。

使用 FileList
-----------

所有 type 属性 (attribute) 为 file 的 `<input>` 元素都有一个 files 属性 (property),用来存储用户所选择的文件。例如：
```

<input id="fileItem" type="file">
```

下面的一行代码演示如何获取到一个 FileList 对象中的第一个文件 (`File` 对象):

```js
var file = document.getElementById("fileItem").files[0];
```

方法概述
----
```

File item(index);
```

属性
--

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| `length` | `integer` | 一个只读的整数值，用来返回列表中的文件数量。 |

方法
--

### `item()`

根据给定的索引值，返回 FileList 对象中对应的 `File` 对象。
```

 File item(
   index
 );
```

###### 参数

`index`

File 对象在 FileList 对象中的索引值，从 0 开始。

###### 返回值

所请求的`File`对象。

示例
--

这个例子迭代了用户通过一个 `input` 元素选择的多个文件：

```js
// fileInput 是一个 HTML input 元素：<input type="file" id="myfileinput" multiple>
var fileInput = document.getElementById("myfileinput");

// files 是一个 FileList 对象 (类似于 NodeList 对象)
var files = fileInput.files;
var file;

// 遍历所有文件
for (var i = 0; i < files.length; i++) {
  // 取得一个文件
  file = files.item(i);
  // 这样也行
  file = files[i];
  // 取得文件名
  alert(file.name);
}
```

下面是一个更完整的例子。

```html
<!doctype html>
<html>
  <head> </head>
  <body>
    <!-- multiple 属性允许用户选择多个文件 -->

    <input id="myfiles" multiple type="file" />
  </body>

  <script>
 var pullfiles = function () {
 // love the query selector
 var fileInput = document.querySelector("#myfiles");
 var files = fileInput.files;
 // 获取所选文件数量
 var fl = files.length;
 var i = 0;

 while (i < fl) {
 // localize file var in the loop
 var file = files[i];
 alert(file.name);
 i++;
 }
 };

 // 设置 change 事件处理函数
 document.querySelector("#myfiles").onchange = pullfiles;
 </script>
</html>
```

规范
--

| Specification |
| --- |
| File API # filelist-section |
| HTML Standard # dom-input-files-dev |

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

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

参见
--

* 如何在 Web 应用程序中使用文件
* `File`
* `FileReader`


AudioBuffer - Web API 接口参考

AudioBuffer
===========

AudioBuffer 接口表示存在内存里的一段短小的音频资源，利用`AudioContext.decodeAudioData()`方法从一个音频文件构建，或者利用 `AudioContext.createBuffer()`从原始数据构建。把音频放入 AudioBuffer 后，可以传入到一个 `AudioBufferSourceNode`进行播放。

这些类型对象被设计来控制小音频片段，往往短于 45 秒。对于更长的声音，通过 `MediaElementAudioSourceNode`来实现更为合适。缓存区（buffer）包含以下数据：不间断的 IEEE754 32 位线性 PCM，从 -1 到 1 的范围额定，就是说，32 位的浮点缓存区的每个样本在 -1.0 到 1.0 之间。如果`AudioBuffer`有不同的频道，他们通常被保存在独立的缓存区。

属性
--

`AudioBuffer.sampleRate` 只读

存储在缓存区的 PCM 数据的采样率：浮点数，单位为 sample/s。

`AudioBuffer.length` 只读

返回存储在缓存区的 PCM 数据的采样帧数：整型。

`AudioBuffer.duration` 只读

返回存储在缓存区的 PCM 数据的时长：双精度型（单位为秒）。

`AudioBuffer.numberOfChannels` 只读

返回存储在缓存区的 PCM 数据的通道数：整型。

方法
--

`AudioBuffer.getChannelData()`

返回一个 `Float32Array`，包含了带有频道的 PCM 数据，由频道参数定义（有 0 代表第一个频道）

`AudioBuffer.copyFromChannel()`

从 AudioBuffer 的指定频道复制到数组终端。

`AudioBuffer.copyToChannel()` (en-US)

复制样品到原数组的 AudioBuffer 的指定频道

例子
--

以下的例子展示了如何构建一个 AudioBuffer 以及随机用白噪音填充。你可以在 audio-buffer 演示库发现完整的源代码；也可以获得一个实时运行的的版本。

```js
// Stereo
var channels = 2;

// Create an empty two second stereo buffer at the
// sample rate of the AudioContext
var frameCount = audioCtx.sampleRate \* 2.0;
var myArrayBuffer = audioCtx.createBuffer(
  channels,
  frameCount,
  audioCtx.sampleRate,
);

button.onclick = function () {
  // Fill the buffer with white noise;
  // just random values between -1.0 and 1.0
  for (var channel = 0; channel < channels; channel++) {
    // This gives us the actual array that contains the data
    var nowBuffering = myArrayBuffer.getChannelData(channel);
    for (var i = 0; i < frameCount; i++) {
      // Math.random() is in [0; 1.0]
      // audio needs to be in [-1.0; 1.0]
      nowBuffering[i] = Math.random() \* 2 - 1;
    }
  }

  // Get an AudioBufferSourceNode.
  // This is the AudioNode to use when we want to play an AudioBuffer
  var source = audioCtx.createBufferSource();

  // set the buffer in the AudioBufferSourceNode
  source.buffer = myArrayBuffer;

  // connect the AudioBufferSourceNode to the
  // destination so we can hear the sound
  source.connect(audioCtx.destination);

  // start the source playing
  source.start();
};
```

规格参数
----

| Specification |
| --- |
| Web Audio API # AudioBuffer |

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

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

可查看
---

* 应用 Web Audio API


OES_vertex_array_object - Web API 接口参考

OES\_vertex\_array\_object
==========================

拓展**OES\_vertex\_array\_object**是WebGL API的一部分，它提供了顶点数组对象 (VAOs) 可以用来封装顶点数组的状态。These objects keep pointers to vertex data and provide names for different sets of vertex data.

WebGL extensions are available using the `WebGLRenderingContext.getExtension()` method. 更多详细信息，参见 Using Extensions in the WebGL tutorial.

**备注：** **Availability:** 此拓展只在WebGL1中有效。在WebGL2当中，这些功能可以被直接使用，且去掉了前缀 "`OES`"。

常量
--

这个拓展提供了一个新的常量，它可以在`gl.getParameter()` 当中作为一个参数传递：

`ext.VERTEX_ARRAY_BINDING_OES`

当作为`gl.getParameter()`中的`pname`参数传递时，返回一个`WebGLVertexArrayObject` 对象。

函数
--

这个拓展提供了四个新的函数。

`ext.createVertexArrayOES()` (en-US)

创建一个新的 `WebGLVertexArrayObject`。

`ext.deleteVertexArrayOES()` (en-US)

删除一个给定的 `WebGLVertexArrayObject`。

`ext.isVertexArrayOES()` (en-US)

如果参数是一个 `WebGLVertexArrayObject`则返回 `true` 。

`ext.bindVertexArrayOES()` (en-US)

绑定一个给定的`WebGLVertexArrayObject`到缓冲区。

Examples
--------

```js
var oes_vao_ext = gl.getExtension("OES\_vertex\_array\_object");
var vao = oes_vao_ext.createVertexArrayOES();
oes_vao_ext.bindVertexArrayOES(vao);

// ...
// calls to bindBuffer or vertexAttribPointer
// which will be "recorded" in the VAO
// ...
```

Specifications
--------------

| Specification |
| --- |
| WebGL OES\_vertex\_array\_object Khronos Ratified Extension Specification  |

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

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

参见
--

* `WebGLRenderingContext.getExtension()`
* `WebGLRenderingContext.vertexAttribPointer()`
* WebGL2 equivalent methods:
    + `WebGL2RenderingContext.createVertexArray()`
    + `WebGL2RenderingContext.deleteVertexArray()` (en-US)
    + `WebGL2RenderingContext.isVertexArray()` (en-US)
    + `WebGL2RenderingContext.bindVertexArray()` (en-US)


HTMLCanvasElement - Web API 接口参考

HTMLCanvasElement
=================

\*\*`HTMLCanvasElement`\*\*接口提供用于操纵`<canvas>`元素的布局和表示的属性和方法。 \*\*`HTMLCanvasElement`\*\*接口还继承了`HTMLElement`接口的属性和方法。

属性
--

*从其父项`HTMLElement`继承属性。*

`HTMLCanvasElement.height`

是一个正整数，反映了`<canvas>` 元素的`height` HTML 属性，以 CSS 像素表示。如果未指定属性，或者将其设置为无效值（例如负数），则使用默认值 150。

`HTMLCanvasElement.width`

是一个正整数，反映了`<canvas>` 元素的`width` HTML 属性，以 CSS 像素表示。如果未指定属性，或者将其设置为无效值（例如负数），则使用默认值 300。

`HTMLCanvasElement.mozOpaque`
非标准

已弃用

是反映 `<canvas>`元素的`moz-opaque` 属性的`Boolean`。它让画布知道半透明性是否会成为一个因素。如果画布知道没有透明感，则可以优化绘画性能。仅基于 Mozilla 的浏览器支持此功能，可以使用标准化的`canvas.getContext('2d', { alpha: false })` 代替。

`HTMLCanvasElement.mozPrintCallback`
非标准

是最初为空的函数。Web 内容可以将其设置为 JavaScript 函数，该函数将在打印页面时重新绘制画布时调用。调用时，回调将传递一个实现了MozCanvasPrintState接口的“printState”对象。回调可以从 printState 对象获取要绘制的上下文，然后必须在完成时在其上调用 done() 。 `mozPrintCallback` 的目的是在所使用打印机的分辨率下获得较高分辨率的画布渲染。 请参阅此博客文章。

方法
--

*从其父项`HTMLElement`继承方法。*

`HTMLCanvasElement.captureStream()`
实验性

返回`CanvasCaptureMediaStream` ，它是对画布表面的实时视频捕获。

`HTMLCanvasElement.getContext()`

返回画布上的绘图上下文；如果不支持上下文 ID，则返回 null。绘图上下文可让你在画布上绘图。调用 getContext 传入`"2d"` 可以返回一个`CanvasRenderingContext2D`对象，也可以传入`"webgl"`（或`"experimental-webgl"`）返回一个`WebGLRenderingContext` 对象。此上下文仅在实现WebGL的浏览器上可用。

`HTMLCanvasElement.toDataURL()`

返回一个数据 URL，该 URL 包含由类型参数指定的格式的图像（默认为`png`）。返回的图像分辨率为 96dpi。

`HTMLCanvasElement.toBlob()`

创建一个`Blob` 对象，表示 canvas 中包含的图像；该文件可以由用户代理决定是否缓存在磁盘上或存储在内存中。

`HTMLCanvasElement.transferControlToOffscreen()`
实验性

将控制权转移到主线程或辅助线程上的 `OffscreenCanvas`对象。

### 过时的方法

`HTMLCanvasElement.mozGetAsFile()` (en-US)
非标准

已弃用

返回代表画布中包含的图像的 `File` 对象；该文件是基于内存的文件，具有指定的名称。如果未指定类型，则图像类型为 image/png。

事件
--

使用`addEventListener()`监听这些事件。

`webglcontextcreationerror` (en-US)

如果用户代理无法创建`WebGLRenderingContext` 或`WebGL2RenderingContext` 上下文，则触发该事件。

`webglcontextlost`

如果用户代理检测到与`WebGLRenderingContext` 或`WebGL2RenderingContext` 对象关联的绘图缓冲区已丢失，则触发此事件。

`webglcontextrestored` (en-US)

如果用户代理为`WebGLRenderingContext` 或`WebGL2RenderingContext` 对象恢复绘图缓冲区，则触发该事件。

规范
--

| Specification |
| --- |
| HTML Standard # htmlcanvaselement |

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

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


Beacon API - Web API 接口参考

Beacon API
==========

**`Beacon`** API 用于发送异步和非阻塞请求到服务器。这类请求不需要响应。与 `XMLHttpRequest` 或 Fetch API 请求不同，浏览器会保证在页面卸载前，将信标请求初始化并运行完成。

Beacon API 主要的使用场景是将分析数据发送给服务器，如：客户端事件、会话数据等。在过去，网站使用 `XMLHttpRequest` 来做这件事，但是浏览器无法保证在某些情况发送这些请求（如：页面将被卸载）。为了解决这个问题，网站采取了各种各样的技术，例如使用同步请求，但是这样对性能造成了很糟糕的影响。因为信标请求是异步的并且保证发送，所以它们结合了良好的性能特征和可靠性。

如需了解 Beacon API 更多的细节和用例，请参考 `navigator.sendBeacon()` 方法。

**备注：** Beacon API 在 Web Worker 中是不可用的（没有通过 `WorkerNavigator` (en-US) 暴露出来）。

接口
--

Beacon API 定义了一个独立的方法：`navigator.sendBeacon()`。

该方法接受 2 个参数，URL 和要在请求中发送的数据（data）。data 参数是可选的，其类型可以是 `TypedArray`、`DataView`、`Blob`、字符串字面量、普通对象或 `FormData` 对象。如果浏览器成功地将请求排队交付，则该方法返回“`true`”，否则返回“`false`”。

规范
--

| Specification |
| --- |
| Beacon # sendbeacon-method |

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

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

参见
--

* 信标标准（Beacon standard）
* 信标 CanIUse 数据
* 通过服务程序拦截信标（Intercepting beacons through service workers）; Ehsan Akhgari; 2015-Apr-08
* https://webkit.org/blog/8821/link-click-analytics-and-privacy/
* 信标实践


PeriodicWave - Web API 接口参考

PeriodicWave
============

**`PeriodicWave`** 接口定义了一个可用于对 `OscillatorNode`(振荡节点) 的输出进行构造（描述）的周期性波形。

`PeriodicWave` (周期波) 没有输入或输出；它用于调用 `OscillatorNode.setPeriodicWave()` 时定义自定义振荡器。 `PeriodicWave` 自身由 `AudioContext.createPeriodicWave()` (en-US) 创建/返回。

构造函数
----

`PeriodicWave.PeriodicWave()` (en-US)

使用所有属性的默认值创建一个新的 `PeriodicWave` 对象实例。如果你想一开始就建立自定义属性值，请使用 `AudioContext.createPeriodicWave()` (en-US) 工厂方法替代。

属性
--

*None; 而且，`PeriodicWave` 不继承任何属性。*

方法
--

*None; 而且，`PeriodicWave` 继承任何属性。*

例子
--

参见 `BaseAudioContext.createPeriodicWave` 以获取简单的示例代码，其展示了如何创建一个包含简单的正弦波的 `PeriodicWave` 对象。

规格
--

| Specification |
| --- |
| Web Audio API # PeriodicWave |

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

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

参见
--

* Using the Web Audio API (en-US)


MediaStream Recording API - Web API 接口参考

MediaStream Recording API
=========================

**MediaStream Recording API** 有时简称为 *Media Recording API* 或者 *MediaRecorder API*，与媒体捕捉与媒体流 API 和 WebRTC API 密切相关。MediaStream Recording API 使得捕获通过 `MediaStream` 或者`HTMLMediaElement` 对象产生的用于分析、加工或者保存到硬盘的数据成为可能。它也非常容易让人们使用。

基本概念
----

MediaStream Recording API 由一个主接口`MediaRecorder`组成，这个接口负责的所有工作是从`MediaStream`获取数据并将其传递给你进行处理。数据通过一系列 `dataavailable` 事件传递，这些数据已经成为你创建 `MediaRecorder` 时所声明的格式。然后，你可以进一步处理数据，或者根据需要将其写入文件。

### 录制过程概述

记录一个流的过程是非常容易的：

1. 建立一个 `MediaStream`或者`HTMLMediaElement` (以 `<audio>` 或 `<video>` 元素的形式) 来充当媒体数据的源。
2. 创建一个 `MediaRecorder` 对象，指定源以及任何有需求的的选项 (比如容器的 MIME 类型或它轨道所需的比特率).
3. 给 `dataavailable` 事件设置`MediaRecorder.ondataavailable` 事件处理函数; 会在数据可利用时候调用。
4. 一旦媒体源播放，你已经准备好录制，使用 `MediaRecorder.start()` (en-US) 开始录制。
5. `dataavailable` 事件处理函数正如你所愿的在每次数据准备好时调用; 这个事件有一个值为包含媒体数据的`Blob` 类型的 `data` 属性。你可以强制 `dataavailable` 事件发生，因此会给你传递最新的声音以至于可以让你过滤、保存或者做一些其他的事情。
6. 当源媒体停止播放时候，录制自动结束。
7. 你可以随时结束录制通过使用 `MediaRecorder.stop()` (en-US).

**备注：** 单单使用包含已经录制好媒体切片的`Blob`s 将大可不能单独播放。媒体在重放之前需要重新组装。

如果在录制过程中出错，`error` 事件将会传给`MediaRecorder`. 你可以设置`onerror` (en-US)去监听 `error` 事件。

例子中，我们使用 Canvas 作为`MediaStream`的源，在 9 秒后停止录音。

```js
var canvas = document.querySelector("canvas");

// Optional frames per second argument.
var stream = canvas.captureStream(25);
var recordedChunks = [];

console.log(stream);
var options = { mimeType: "video/webm; codecs=vp9" };
mediaRecorder = new MediaRecorder(stream, options);

mediaRecorder.ondataavailable = handleDataAvailable;
mediaRecorder.start();

function handleDataAvailable(event) {
  console.log("data-available");
  if (event.data.size > 0) {
    recordedChunks.push(event.data);
    console.log(recordedChunks);
    download();
  } else {
    // ...
  }
}
function download() {
  var blob = new Blob(recordedChunks, {
    type: "video/webm",
  });
  var url = URL.createObjectURL(blob);
  var a = document.createElement("a");
  document.body.appendChild(a);
  a.style = "display: none";
  a.href = url;
  a.download = "test.webm";
  a.click();
  window.URL.revokeObjectURL(url);
}

// demo: to download after 9sec
setTimeout((event) => {
  console.log("stopping");
  mediaRecorder.stop();
}, 9000);
```

### 检查 and 控制记录器的状态

你也可以使用 `MediaRecorder` 对象的属性去决定录制过程的状态，用 `pause()` (en-US) 和 `resume()` (en-US) 方法暂停或者继续媒体源的录制。

如果你需要检查一个特殊的 MIME 类型是否被支持，使用`MediaRecorder.isTypeSupported()`.

### 检查潜在的输入源

如果你的目标是记录摄像头或麦克风输入，你可能希望在构建 `MediaRecorder` 之前检查可用的输入设备。这时，你需要调用 `navigator.mediaDevices.enumerateDevices()` 来得到可使用的媒体设备。你可以检查此列表，发现潜在的设备，甚至在有需要的时候过滤掉设备。

在这块代码中，`enumerateDevices()` 被用来检查可利用的设备，找到那些音频输入设备，创建`<option>` 元素，之后添加到`<select>`元素，代表输入源选择器 .

```js
navigator.mediaDevices.enumerateDevices().then(function (devices) {
  devices.forEach(function (device) {
    let menu = document.getElementById("inputdevices");
    if (device.kind == "audioinput") {
      let item = document.createElement("option");
      item.innerHTML = device.label;
      item.value = device.deviceId;
      menu.appendChild(item);
    }
  });
});
```

类似的代码可以用来让用户限制他们希望使用的设备。

### 更多信息

更多关于 MediaStream Recording API 的使用，查看 Using the MediaStream Recording API, 这个显示了如何使用 API 来记录音频剪辑。另一篇文章，Recording a media element (en-US), 介绍了如何从 `<audio>` 或`<video>` 元素 接收信息流和如何使用接收到的信息流（这个案例中，接收、存到硬盘）。

参考
--

`BlobEvent` (en-US)

Each time a chunk of media data is finished being recorded, it's delivered to consumers in `Blob` form using a `BlobEvent` (en-US) of type `dataavailable`.

`MediaRecorder`

The primary interface that implements the MediaStream Recording API.

`MediaRecorderErrorEvent` (en-US)

The interface that represents errors thrown by the MediaStream Recording API. Its `error` (en-US) property is a `DOMException` that specifies that error occurred.

规范
--

| Specification |
| --- |
| MediaStream Recording  |

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

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

参阅
--

* Using the MediaStream Recording API
* Recording a media element (en-US)
* simpl.info MediaStream Recording demo, by Sam Dutton
* `navigator.mediaDevices.getUserMedia()` (en-US)
* HTML5’s Media Recorder API in Action on Chrome and Firefox
* MediaRecorder polyfill for Safari and Edge
* TutorRoom: HTML5 video capture/playback/download using getUserMedia and the MediaRecorder API (source on GitHub)
* FingerSpell: Sign Language Fingerspelling practice using getUserMedia and the MediaRecorder API to create and download recordings, MediaRecorder API supported desktop browsers only (source on GitHub)
* Simple video recording demo
* Advanced media stream recorder sample
* OpenLang: HTML5 video language lab web application using MediaDevices and the MediaStream Recording API for video recording (source on GitHub)


XMLSerializer - Web API 接口参考

XMLSerializer
=============

`XMLSerializer`接口提供`serializeToString()` (en-US) 方法来构建一个代表 DOM 树的 XML 字符串。方法
--

`serializeToString()` (en-US)

返回 DOM 子树序列化后的字符串。

`serializeToStream()`
非标准

已弃用

将指定元素的每个子树按照特定的字符集序列化成字节流。

示例
--

### 把 XML 序列化为字符串

首先，最基本的例子是将整个 document 对象序列化为一个 XML 字符串。

```js
var s = new XMLSerializer();
var d = document;
var str = s.serializeToString(d);
saveXML(str);
```

这里新建了一个 `XMLSerializer` 对象实例，然后将待序列化的 `Document` 对象实例传入返回等价 XML 的 `serializeToString()` (en-US) 方法。

### 向一个基于 XML 的 DOM 对象中

本例使用 {domxref("Element.insertAdjacentHTML()")}} 方法将一个新的 DOM `Node` 插入 基于序列化 `Document` 对象创建的 XML 中。

**备注：** 在真实场景下，你通常应该通过调用 `importNode()` 方法将新节点加入 DOM 中，然后通过调用以下方法将目标节点添加到 DOM 树：

* `Document` 和 `Element` 方法 `append()` (en-US) 和 `prepend()` (en-US)
* `Node.replaceWith()` (en-US) 方法 (替换现有节点)
* `Document.insertAdjacentElement()` 和 `Element.insertAdjacentElement()` 方法。

因为`insertAdjacentHTML()` 的第二个参数是一个字符串而不是 `Node` 节点对象，所以这里先要使用 `XMLSerializer` 将节点转换为字符串。

```js
var inp = document.createElement("input");
var XMLS = new XMLSerializer();
var inp_xmls = XMLS.serializeToString(inp); // 先将一个 DOM 节点转换为字符串。

// 将新建的节点添加到 DOM 中。
document.body.insertAdjacentHTML("afterbegin", inp_xmls);
```

以上代码通过调用 `Document.createElement()` 方法新建一个 {HTMLElement("input")}} 对象 , 然后通过 `serializeToString()` (en-US) 方法将该对象序列化为 XML.

做完以上工作之后，使用 `insertAdjacentHTML()` 方法将 `<input>` 元素加入 DOM.

规范
--

| Specification |
| --- |
| DOM Parsing and Serialization # the-xmlserializer-interface |

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

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

参见
--

* Parsing and serializing XML
* `XMLHttpRequest`
* `DOMParser`


Gamepad API - Web API 接口参考

Gamepad API
===========

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

**Gamepad API** 可以给予开发者一种简单、统一的方式来识别并响应游戏控制器（手柄）。其中包含了三个接口、两个事件、一个特殊函数，用来响应控制器的连接与断开、获取其他关于控制器的信息以及识别当前是哪个按键或是哪个控制器被按下了。

接口
--

`Gamepad`

表示已连接的游戏控制器。

`GamepadButton`

表示已连接手柄上的一个按键。

`GamepadEvent`

表示与控制器相关的事件的事件对象。

### 实验性 Gamepad 扩展

`GamepadHapticActuator` (en-US)

表示控制器中的硬件，用于向用户提供触觉反馈（如果可用）最常见的是振动硬件。

`GamepadPose`

表示控制器的位置方向（例如，在 3D 空间中的位置和方向）于 WebVR 控制器中。

另请参阅 Gamepad 接口扩展，来获取上方的功能的相关信息。

### 其他接口扩展

#### Navigator

`Navigator.getGamepads()`

于 `Navigator` 对象中的一个扩展。会返回一个 名为`Gamepad` 的数组对象，其中每个数组元素对应一个已连接的控制器。

#### Window 事件

`Window.ongamepadconnected`

表示当控制器连接时（当`gamepadconnected` 事件触发时）运行的处理程序。

`Window.ongamepaddisconnected` (en-US)

表示当控制器断开连接时（当`gamepaddisconnected` (en-US) 事件触发时）运行的处理程序。

教程与指南
-----

* 使用 Gamepad API
* 使用 Gamepad API 实现控制
规范
--

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

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

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

参见
--

* The Gamepad API by Ted Mielczarek and Robert Nyman
* 简单的 API 演示页面 (源码)


TreeWalker - Web API 接口参考

TreeWalker
==========

**`TreeWalker`** 对象用于表示文档子树中的节点和它们的位置。

`TreeWalker` 可以使用 `Document.createTreeWalker()` 方法创建。

属性
--

*这个接口不继承任何属性。*

`TreeWalker.root` (en-US) 只读

返回一个 `Node` ，表示新建 `TreeWalker` 时所声明的根节点。

`TreeWalker.whatToShow` (en-US) 只读

返回一个 `unsigned long` 类型的常量位掩码，表示需要筛选的`Node` 类型。不匹配的节点会跳过，但其子节点，如果符合条件，则也会被包含。可能的值如下：

| 常量 | 数字值 | 描述 |
| --- | --- | --- |
| `NodeFilter.SHOW_ALL` | `4294967295`（`unsigned long` 类型的最大值） | 显示所有节点。 |
| `NodeFilter.SHOW_ATTRIBUTE`
已弃用
 | `2` | 显示`Attr`节点，这意味着使用`TreeWalker`访问 `Attr`节点时，需要让这些节点处于遍历的开始位置。这是因为这些节点不是任何节点的后代，并不处于文档树之上。 |
| `NodeFilter.SHOW_CDATA_SECTION`
已弃用
 | `8` | 显示 `CDATASection`节点。 |
| `NodeFilter.SHOW_COMMENT` | `128` | 显示 `Comment` 节点。 |
| `NodeFilter.SHOW_DOCUMENT` | `256` | 显示 `Document` 节点。 |
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `1024` | 显示 `DocumentFragment` 节点。 |
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `512` | 显示 `DocumentType` 节点。 |
| `NodeFilter.SHOW_ELEMENT` | `1` | 显示 `Element` 节点。 |
| `NodeFilter.SHOW_ENTITY`
已弃用
 | `32` | 遗留属性，不再可用。 |
| `NodeFilter.SHOW_ENTITY_REFERENCE`
已弃用
 | `16` | 遗留属性，不再可用。 |
| `NodeFilter.SHOW_NOTATION`
已弃用
 | `2048` | 遗留属性，不再可用。 |
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `64` | 显示 `ProcessingInstruction` (en-US) 节点。 |
| `NodeFilter.SHOW_TEXT` | `4` | 显示 `Text` (en-US) 节点。 |

`TreeWalker.filter` (en-US) 只读

返回一个实现 `NodeFilter` 接口的对象，这个对象用来挑选相关的节点。

`TreeWalker.currentNode` (en-US)

返回 `TreeWalker` 当前指向的`Node`。

方法
--

*这个接口不继承任何方法。*

**备注：** 对于 `TreeWalker`，一个节点是否*可见*只取决于 `whatToShow` 和 `filter` 两个参数。（和元素是否在屏幕上可见无关。）

`TreeWalker.parentNode()` (en-US)

移动当前 `Node` 到文档顺序中的第一个“可见”的祖先节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

`TreeWalker.firstChild()` (en-US)

移动当前 `Node` 到当前节点的第一个“可见”子节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

```html
<!DOCTYPE html>
<html lang="en">
  <head><title>Demo</title>
  <body>
    <div id="container"></div>
  </body>
</html>
```

```js
let walker = document.createTreeWalker(document.body, NodeFilter.SHOW\_ALL);
let node = walker.firstChild(); // nodeName: "#text"
```

但如果我们这样做：

```js
let walker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW\_ELEMENT,
);
let node = walker.firstChild(); // nodeName: "DIV"
```

这同样应用于 `nextSibling()`、`previousSibling()`、`firstChild()` 和 `lastChild()`。

`TreeWalker.lastChild()` (en-US)

移动当前 `Node` 到当前节点的最末一个“可见”子节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

`TreeWalker.previousSibling()` (en-US)

移动当前 `Node` 到当前节点的前一个兄弟节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

`TreeWalker.nextSibling()` (en-US)

移动当前 `Node` 到当前节点的后一个兄弟节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

`TreeWalker.previousNode()` (en-US)

移动当前 `Node` 到文档顺序中前一个节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

`TreeWalker.nextNode()` (en-US)

移动当前 `Node` 到文档顺序中下一个节点，并返回该节点。如果没有这样的节点，则会返回 null，同时也不会发生移动。

规范
--

| Specification |
| --- |
| DOM Standard # interface-treewalker |

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

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

参见
--

* 构造函数：`Document.createTreeWalker()`。
* 相关接口：`NodeFilter`、`NodeIterator`。


Web Animations API - Web API 接口参考

Web Animations API
==================

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

**Web Animations API** 允许同步和定时更改网页的呈现，即 DOM 元素的动画。它通过组合两个模型来实现：时序模型和动画模型。

概念和用法
-----

Web Animations API 为浏览器和开发人员提供了一种用于描述 DOM 元素的动画的通用语言。要获得有关 API 背后的概念以及如何使用它的更多信息，请阅读使用 Web Amimations API。

网页动画接口
------

`Animation`

提供播放控制、动画节点或源的时间轴。可以接受使用`KeyframeEffect.KeyframeEffect` (en-US)构造函数创建的对象作为参数。

`KeyframeEffect` (en-US)

描述动画属性的集合，调用**keyframes**及`Animation Effect Timing Properties`。然后可以使用 `Animation` 构造函数进行播放。

`AnimationTimeline`

表示动画的时间轴。此接口用以定义时间轴功能（继承自`DocumentTimeline` (en-US)和`future timeline`），并且本身不被开发人员访问。

`DocumentTimeline` (en-US)

表示动画时间轴，包括默认的`DocumentTimeline` (en-US)（通过`Document.timeline`访问）。

`AnimationEffectTiming`

包含`KeyframeEffect` (en-US)的`timing`返回的定时属性对象。它从`AnimationEffectTimingReadOnly`继承其属性，但是以非只读形式。

`SharedKeyframeList`

表示可在`KeyframeEffect` (en-US)对象之间共享的关键帧序列。通过使用该对象，多个`KeyframeEffect` (en-US)对象可以重用相同的关键帧，而无需支付多次解析它们的成本。

`AnimationEffectTimingProperties` (en-US)

`Element.animate()`, `KeyframeEffectReadOnly.KeyframeEffectReadOnly()` (en-US)和 `KeyframeEffect.KeyframeEffect()` (en-US)的定时属性对象。

扩展的其他接口
-------

The Web Animations API 向\*\*`document`**和**`element`\*\* 添加了一些新的功能。

### 扩展到 `Document` 的接口

`document.timeline`

`DocumentTimeline` 表示默认文档时间轴

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

返回当前对文档中的元素有效的`Animation`对象的数组。

### 扩展到 `Element` 的接口

`Element.animate()`

用于在元素上创建和播放动画的快捷方式。它返回创建的`Animation`对象实例。

Web 动画只读接口
----------

规格中包括以下接口，用于定义在多个其他位置使用的功能。你不会在 Web 开发工作中直接使用这些接口，但他们能帮助库或框架作者了解这些接口如何工作，使他们的库的实现可以更有效，或者浏览器工程师寻找一个比规范提供的内容更容易的参考。

`AnimationEffectTimingReadOnly`

A dictionary object of timing properties, which are inherited by the mutable `AnimationEffectTiming` interface associated with `KeyframeEffect` (en-US).

`AnimationEffectReadOnly` (en-US)

Defines current and future "Animation Effects" like `KeyframeEffect` (en-US), which can be passed to `Animation.Animation` objects for playing, and `KeyframeEffectReadOnly` (en-US) which is used by `KeyframeEffect` (en-US) (inherited by CSS Animations and Transitions).

`KeyframeEffectReadOnly` (en-US)

Describes sets of animatable properties and values that can be played using the `Animation.Animation()` constructor, and which are inherited by `KeyframeEffect` (en-US).

规范
--

| Specification |
| --- |
| Web Animations  |

相关内容
----

* Using the Web Animations API
* Web Animations demos
* Polyfill
* Firefox's current implementation: AreWeAnimatedYet
* Browser support test


crossOriginIsolated - Web API 接口参考

crossOriginIsolated
===================

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

**`crossOriginIsolated`** 是 `WindowOrWorkerGlobalScope` 的一个只读属性，返回一个布尔值，该值指示是否可以通过 `Window.postMessage()` 调用发送 `SharedArrayBuffer`。

该值取决于响应中存在的`Cross-Origin-Opener-Policy` (en-US) 和`Cross-Origin-Embedder-Policy` 头。

语法
--
```

var myCrossOriginIsolated = self.crossOriginIsolated; // 或直接 crossOriginIsolated
```

### 类型

布尔类型

示例
--

```js
if (crossOriginIsolated) {
  // post SharedArrayBuffer
} else {
  // Do something else
}
```

规范
--

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

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

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

参见
--

* Service Workers (en-US)
* Web Workers


KeyboardEvent - Web API 接口参考

KeyboardEvent
=============

**`KeyboardEvent`** 对象描述了用户与键盘的交互。每个事件都描述了用户与一个按键（或一个按键和修饰键的组合）的单个交互；事件类型`keydown`， `keypress` 与 `keyup` 用于识别不同的键盘活动类型。

**备注：** `KeyboardEvent` 只在低级别提示用户与一个键盘按键的交互是什么，不涉及这个交互的上下文含义。当你需要处理文本输入的时候，使用 `input` 事件代替。用户使用其他方式输入文本时，如使用平板电脑的手写系统或绘图板，键盘事件可能不会触发。

构造函数
----

`KeyboardEvent()`

创建一个 `KeyboardEvent` 对象。

常量
--

`KeyboardEvent` 接口定义了以下常量。

### 键盘定位

下述常量用于识别产生按键事件的键盘位置，以类似 `KeyboardEvent.DOM_KEY_LOCATION_STANDARD` 的形式来访问。

| 常量 | 值 | 描述 |
| --- | --- | --- |
| `DOM_KEY_LOCATION_STANDARD` | 0x00 | The key described by the event is not identified as being located in a particular area of the keyboard; it is not located on the numeric keypad (unless it's the NumLock key), and for keys that are duplicated on the left and right sides of the keyboard, the key is, for whatever reason, not to be associated with that location.Examples include alphanumeric keys on the standard PC 101 US keyboard, the NumLock key, and the space bar. |
| `DOM_KEY_LOCATION_LEFT` | 0x01 | The key is one which may exist in multiple locations on the keyboard and, in this instance, is on the left side of the keyboard.Examples include the left Control key, the left Command key on a Macintosh keyboard, or the left Shift key. |
| `DOM_KEY_LOCATION_RIGHT` | 0x02 | The key is one which may exist in multiple positions on the keyboard and, in this case, is located on the right side of the keyboard.Examples include the right Shift key and the right Alt key (Option on a Mac keyboard). |
| `DOM_KEY_LOCATION_NUMPAD` | 0x03 | The key is located on the numeric keypad, or is a virtual key associated with the numeric keypad if there's more than one place the key could originate from. The NumLock key does not fall into this group and is always encoded with the location `DOM_KEY_LOCATION_STANDARD`.Examples include the digits on the numeric keypad, the keypad's Enter key, and the decimal point on the keypad. |

属性
--

*此接口从 `UIEvent` 和 `Event` 中继承属性。*

`KeyboardEvent.altKey` 只读

返回一个 `Boolean`，如果按键事件产生时，

`Alt`

（OS X 中是

`Option`

或

`⌥`

）键被按下，则该值为 `true` 。

`KeyboardEvent.code` 只读

返回一个 `DOMString`，其 code 值代表触发事件的物理按键。

**警告：** 这个属性会忽略用户的键盘布局，所以如果用户在 QWERTY 布局的键盘上按下“Y”位置（第一行字母按键的中间）的按键时，这个属性会返回“KeyY”，即使用户使用 QWERTZ 布局的键盘（此时用户输入的就是“Z”，其他属性也会提示“Z”）或 Dvorak 键盘（此时用户输入的就是“F”）也是如此。

`KeyboardEvent.ctrlKey` 只读

返回一个 `Boolean`，如果按键事件发生时 `Ctrl` 键被按下，则该值为 `true` 。

`KeyboardEvent.isComposing` 只读

Returns a `Boolean` that is `true` if the event is fired between after `compositionstart` and before `compositionend`.

`KeyboardEvent.key` 只读

Returns a `DOMString` representing the key value of the key represented by the event.

`KeyboardEvent.locale` 只读

Returns a `DOMString` representing a locale string indicating the locale the keyboard is configured for. This may be the empty string if the browser or device doesn't know the keyboard's locale.

**备注：** This does not describe the locale of the data being entered. A user may be using one keyboard layout while typing text in a different language.

`KeyboardEvent.location` (en-US) 只读

Returns a `Number` representing the location of the key on the keyboard or other input device. A list of the constants identifying the locations is shown above in Keyboard locations.

`KeyboardEvent.metaKey` 只读

 Returns a `Boolean` that is `true` if the `Meta` key (on Mac keyboards, the
 `⌘ Command` key; on Windows keyboards, the Windows key (`⊞`)) was active when the key event was generated.

`KeyboardEvent.repeat` 只读

Returns a `Boolean` that is `true` if the key is being held down such that it is automatically repeating.

`KeyboardEvent.shiftKey` 只读

Returns a `Boolean` that is `true` if the `Shift` key was active when the key event was generated.

方法
--

*此接口从 `UIEvent` 和 `Event` 中继承方法。*

`KeyboardEvent.getModifierState()` (en-US)

Returns a `Boolean` indicating if a modifier key such as

`Alt`

,

`Shift`

,

`Ctrl`

, or

`Meta`

, was pressed when the event was created.

过时方法
----

`KeyboardEvent.initKeyEvent()`
已弃用

Initializes a `KeyboardEvent` object. This was implemented only by Firefox, and is no longer supported even there; instead, you should use the `KeyboardEvent()` constructor.

`KeyboardEvent.initKeyboardEvent()` (en-US)
已弃用

Initializes a `KeyboardEvent` object. This is now deprecated. You should instead use the `KeyboardEvent()` constructor.

过时属性
----

`KeyboardEvent.char`
非标准

已弃用
只读

Returns a `DOMString` representing the character value of the key. If the key corresponds to a printable character, this value is a non-empty Unicode string containing that character. If the key doesn't have a printable representation, this is an empty string.

**备注：** If the key is used as a macro that inserts multiple characters, this attribute's value is the entire string, not just the first character.

`KeyboardEvent.charCode`
已弃用
只读

Returns a `Number` representing the Unicode reference number of the key; this attribute is used only by the `keypress` event. For keys whose `char` attribute contains multiple characters, this is the Unicode value of the first character in that attribute. In Firefox 26 this returns codes for printable characters.

**警告：** This attribute is deprecated; you should use `KeyboardEvent.key` instead, if available.

`KeyboardEvent.keyCode`
已弃用
只读

Returns a `Number` representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key.

**警告：** This attribute is deprecated; you should use `KeyboardEvent.key` instead, if available.

`KeyboardEvent.keyIdentifier` (en-US)
非标准

已弃用
只读

This property is non-standard and has been deprecated in favor of `KeyboardEvent.key`. It was part of an old version of DOM Level 3 Events.

`KeyboardEvent.keyLocation`
非标准

已弃用
只读

This is a non-standard deprecated alias for `KeyboardEvent.location` (en-US). It was part of an old version of DOM Level 3 Events.

`KeyboardEvent.which`
已弃用
 只读

Returns a `Number` representing a system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as `keyCode`.

**警告：** This attribute is deprecated; you should use `KeyboardEvent.key` instead, if available.

事件
--

The following events are based on the `KeyboardEvent` type. They can be delivered to any object which implements `GlobalEventHandlers`, including `Element`, `Document`, and `Window`. In the list below, each event links to the documentation for the `Document` handler for the event, which applies generally to all of the recipients.

`keydown` (en-US)

A key has been pressed.

`keyup` (en-US)

A key has been released.

### 过时事件

`keypress`
已弃用

通常在一个按键被按下时触发，并产生一个字符串值，这个事件高度依赖硬件 (highly device-dependent ) 且废弃，你不应该使用它

用法说明
----

There are three types of keyboard events: `keydown`, `keypress`, and `keyup`. For most keys, Gecko dispatches a sequence of key events like this:

1. When the key is first pressed, the `keydown` event is sent.
2. If the key is not a modifier key, the `keypress` event is sent.
3. When the user releases the key, the `keyup` event is sent.
### 特殊情况

Some keys toggle the state of an indicator light; these include keys such as Caps Lock, Num Lock, and Scroll Lock. On Windows and Linux, these keys dispatch only the `keydown` and `keyup` events.

**备注：** On Linux, Firefox 12 and earlier also dispatched the `keypress` event for these keys.

However, a limitation of the macOS event model causes Caps Lock to dispatch only the `keydown` event. Num Lock was supported on some older laptop models (2007 models and older), but since then, macOS hasn't supported Num Lock even on external keyboards. On older MacBooks with a Num Lock key, that key doesn't generate any key events. Gecko does support the Scroll Lock key if an external keyboard which has an F14 key is connected. In certain older versions of Firefox, this key generated a `keypress` event; this inconsistent behavior was Firefox bug 602812.

### Auto-repeat handling

When a key is pressed and held down, it begins to auto-repeat. This results in a sequence of events similar to the following being dispatched:

1. `keydown`
2. `keypress`
3. `keydown`
4. `keypress`
5. <<repeating until the user releases the key>>
6. `keyup`

This is what the DOM Level 3 specification says should happen. There are some caveats, however, as described below.

#### Auto-repeat on some GTK environments such as Ubuntu 9.4

In some GTK-based environments, auto-repeat dispatches a native key-up event automatically during auto-repeat, and there's no way for Gecko to know the difference between a repeated series of keypresses and an auto-repeat. On those platforms, then, an auto-repeat key will generate the following sequence of events:

1. `keydown`
2. `keypress`
3. `keyup`
4. `keydown`
5. `keypress`
6. `keyup`
7. <<repeating until the user releases the key>>
8. `keyup`

In these environments, unfortunately, there's no way for web content to tell the difference between auto-repeating keys and keys that are just being pressed repeatedly.

#### Auto-repeat handling prior to Gecko 5.0

Before Gecko 5.0, keyboard handling was less consistent across platforms.

Windows

Auto-repeat behavior is the same as in Gecko 4.0 and later.

Mac

After the initial keydown event, only keypress events are sent until the keyup event occurs; the inter-spaced keydown events are not sent.

Linux

The event behavior depends on the specific platform. It will either behave like Windows or Mac depending on what the native event model does.

**Note:** Manually firing an event does *not* generate the default action associated with that event. For example, manually firing a key event does not cause that letter to appear in a focused text input. In the case of UI events, this is important for security reasons, as it prevents scripts from simulating user actions that interact with the browser itself.

示例
--

```js
<!DOCTYPE html>
<html>
<head>
<script>
'use strict';

document.addEventListener('keydown', (event) => {
  const keyName = event.key;

  if (keyName === 'Control') {
    // do not alert when only Control key is pressed.
    return;
  }

  if (event.ctrlKey) {
    // Even though event.key is not 'Control' (e.g., 'a' is pressed),
    // event.ctrlKey may be true if Ctrl key is pressed at the same time.
    alert(`Combination of ctrlKey + ${keyName}`);
  } else {
    alert(`Key pressed ${keyName}`);
  }
}, false);

document.addEventListener('keyup', (event) => {
  const keyName = event.key;

  // As the user releases the Ctrl key, the key is no longer active,
  // so event.ctrlKey is false.
  if (keyName === 'Control') {
    alert('Control key was released');
  }
}, false);

</script>
</head>

<body>
</body>
</html>
```

规范
--

| Specification |
| --- |
| UI Events # interface-keyboardevent |

The `KeyboardEvent` interface specification went through numerous draft versions, first under DOM Events Level 2 where it was dropped as no consensus arose, then under DOM Events Level 3. This led to the implementation of non-standard initialization methods, the early DOM Events Level 2 version, `KeyboardEvent.initKeyEvent()` by Gecko browsers and the early DOM Events Level 3 version, `KeyboardEvent.initKeyboardEvent()` (en-US) by others. Both have been superseded by the modern usage of a constructor: `KeyboardEvent()`.

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

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

### 兼容性说明

* As of Firefox 65, the `keypress` event is no longer fired for non-printable keys (Firefox bug 968056), except for the
 `Enter`
 key, and the
 `Shift`
 +
 `Enter`
 and
 `Ctrl`
 +
 `Enter`
 key combinations (these were kept for cross-browser compatibility purposes).
参见
--

* `KeyboardEvent.code`.
* `KeyboardEvent.key`.
* `KeyboardEvent.getModifierState()` (en-US)


Touch - Web API 接口参考

Touch
=====

**`Touch`** 对象表示在触控设备上的触摸点。通常是指手指或者触控笔在触屏设备或者触摸板上的操作。

对象属性 `Touch.radiusX`, `Touch.radiusY`, 和 `Touch.rotationAngle` 表示用户触摸操作所作用的区域，即*触摸区域*。这些属性对于处理类似于手指触摸之类的不精确操作很有帮助。这些属性可以表示出一个尽可能匹配触控区域的椭圆形（例如用户的指尖触控）。
实验性

**备注：** 以下很多属性的值需要依赖硬件设备去获取，例如，如果设备本身不支持侦测压感，那么 `force` 属性的值将始终是 0，对于 `radiusX` 和 `radiusY` 来说同样可能有这种情况，如果设备认为触点只是一个点而不是一个面，它们始终为 1。

构造函数
----

`Touch()`
实验性

创建一个 Touch 对象。

属性
--

*这个接口没有父类，不继承任何属性。*

### 基本属性

`Touch.identifier`只读

此 `Touch` 对象的唯一标识符。一次触摸动作 (例如手指触摸) 在平面上移动的整个过程中，该标识符不变。可以根据它来判断跟踪的是否是同一次触摸过程。

**`Touch.screenX`**只读

触点相对于屏幕左边缘的 X 坐标。

**`Touch.screenY`**只读

触点相对于屏幕上边缘的 Y 坐标。

**`Touch.clientX`**只读

触点相对于可见视区 (visual viewport) 左边缘的 X 坐标。不包括任何滚动偏移。

**`Touch.clientY`**只读

触点相对于可见视区 (visual viewport) 上边缘的 Y 坐标。不包括任何滚动偏移。

`Touch.pageX`只读

触点相对于 HTML 文档左边缘的 X 坐标。当存在水平滚动的偏移时，这个值包含了水平滚动的偏移。

`Touch.pageY`只读

触点相对于 HTML 文档上边缘的 Y 坐标。当存在垂直滚动的偏移时，这个值包含了垂直滚动的偏移。

`Touch.target`只读

返回触摸点最初接触的 `Element`，即使这个触摸点已经移出那个元素的交互区域。需要注意的是，如果这个元素在触摸过程中被移除，这个事件仍然会指向它，因此这个事件也不会冒泡到 `window` 或 `document` 对象。因此，如果有元素在触摸过程中可能被移除，最佳实践是将触摸事件的监听器绑定到这个元素本身，防止元素被移除后，无法再从它的上一级元素上侦测到从该元素冒泡的事件。

### 触摸区域

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

`Touch.radiusX`只读
实验性

返回能够包围接触区域的最小椭圆的水平轴 (X 轴) 半径。这个值的单位和 `screenX` 相同\*\*。\*\*

`Touch.radiusY`只读
实验性

返回能够包围接触区域的最小椭圆的垂直轴 (Y 轴) 半径。这个值的单位和 `screenY` 相同。

`Touch.rotationAngle`只读
实验性

返回一个角度值，表示上述由`radiusX` 和 `radiusY` 描述的椭圆为了尽可能精确地覆盖用户与平面之间的接触区域而需要顺时针旋转的角度。

`Touch.force`只读
实验性

返回用户对触摸平面的压力大小，是一个从 0.0(没有压力) 到 1.0(最大压力) 的浮点数。

Methods
-------

*这个接口没有方法，也没有父类，不继承任何方法。*

示例
--

请看 example on the main Touch events article。

规范
--

| Specification |
| --- |
| Touch Events # touch-interface |

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

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

相关链接
----

* Touch events
* `Touch Events Overview`
* `Document.createTouch()` (en-US)
* `Touch`
* `TouchList`
* `TouchEvent`


InputEvent - Web API 接口参考

InputEvent
==========

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

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

<
**`InputEvent`** 接口用来构造和字符输入相关的事件对象。

构造函数
----

`InputEvent()`

创建一个 `InputEvent` 对象。

属性
--

除继承自 `UIEvent` 和 `Event` 接口的属性外，还有以下属性：

`InputEvent.data` 只读

返回当前输入的字符串，如果是删除操作，则该值为空字符串。

`InputEvent.isComposing`只读

返回一个布尔值，表明该事件是在触发 `compositionstart` 事件之后且触发 `compositionend` 事件之前触发的，也就是表明当前输入的字符是输入法的中途输入。

方法
--

除继承自 `UIEvent` 和 `Event` 接口的方法外，没有其他自身方法。

规范
--

| Specification |
| --- |
| Input Events Level 2 # interface-InputEvent |
| UI Events # interface-inputevent |

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

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

参见
--

* `beforeinput` 事件
* `input` 事件


HTMLInputElement - Web API 接口参考

HTMLInputElement
================

**`HTMLInputElement`** 接口提供了特定的属性和方法，用于管理 `<input>` 元素的选项、布局和外观。

EventTarget

Node

Element

HTMLElement

HTMLInputElement实例属性
----

*还从其父接口 `HTMLElement` 继承属性。*

某些属性仅适用于支持相应属性的输入元素类型。

`align`
已弃用

一个表示元素对齐方式的字符串。*请改用 CSS。*

`defaultValue`

一个表示元素默认值的字符串，该值最初是在创建此对象的 HTML 中指定的。

`dirName`

一个表示元素方向的字符串。

`incremental`
非标准

一个表示搜索事件触发模式的布尔值，如果为 `true`，则在每次按键或单击取消按钮时触发；否则在按下 `Enter` 键时触发。

`labels` 只读

返回一个 `<label>` 元素的列表，这些元素是当前元素的标签。

`list` 只读

返回由 `list` 属性指向的元素。如果在同一树中找不到 HTML 元素，则该属性可能为 `null`。

`multiple`

一个表示元素的 `multiple` 属性的布尔值，表示是否可能有多个值（例如，多个文件）。

`name`

一个表示元素的 `name` 属性的字符串，包含在提交表单时标识元素的名称。

`popoverTargetAction` (en-US)

获取或设置要在由 `type="button"` 的 `<input>` 元素控制的弹出窗口元素上执行的操作（`"hide"`、`"show"` 或 `"toggle"`）。它反映了 `popovertargetaction` HTML 属性的值。

`popoverTargetElement` (en-US)

获取或设置要通过 `type="button"` 的 `<input>` 元素控制的弹出窗口元素。它反映了 `popovertarget` HTML 属性的值。

`step`

一个表示元素的 `step` 属性的字符串，它与 `min` 和 `max` 一起使用，以限制可以设置数字或日期时间值的增量。它可以是字符串 `any` 或正浮点数。如果不设置为 `any`，则控件仅接受大于最小值的步长值的倍数。

`type`

一个表示元素的 `type` 属性的字符串，表示要显示的控件类型。请参阅 `type` 属性的文档，以了解其可能的值。

`useMap`
已弃用

一个表示客户端图像映射的字符串。

`value`

一个表示控件当前值的字符串。如果用户输入与预期不同的值，则可能返回空字符串。

`valueAsDate`

一个表示元素的值的 `Date`，以日期形式解释，如果无法转换，则为 `null`。

`valueAsNumber`

一个表示元素的值的数字，以以下顺序解释：时间值、数字或 `NaN`（如果无法转换）。

### 与父表单相关的实例属性

`form` 只读

返回一个父表单（`<form>`）元素的引用。

`formAction`

一个表示元素的 `formaction` 属性的字符串，包含处理元素提交信息程序的 URI。这会覆盖父表单的 `action` 属性。

`formEnctype`

一个表示元素的 `formenctype` 属性的字符串，包含将表单提交到服务器的内容类型。这会覆盖父表单的 `enctype` 属性。

`formMethod`

一个表示元素的 `formmethod` 属性的字符串，包含浏览器用于提交表单的 HTTP 方法。这会覆盖父表单的 `method` 属性。

`formNoValidate`

一个表示元素的 `formnovalidate` 属性的布尔值，表示在提交表单时不对其进行验证。这会覆盖父表单的 `novalidate` 属性。

`formTarget`

一个表示元素的 `formtarget` 属性的字符串，包含一个名称或关键字，表示在提交表单后接收响应的显示位置。这会覆盖父表单的 `target` 属性。

### 适用于任何类型的非隐藏输入元素的实例属性

`disabled` (en-US)

一个表示元素的 `disabled` 属性的布尔值，表示该控件不可用于交互。输入值将不会与表单一起提交。参见 `readonly`。

`required`

一个表示元素的 `required` 属性的布尔值，表示用户必须在提交表单之前填写值。

`validationMessage` 只读

返回一条描述控件不满足时的验证约束的本地化消息。如果控件不是约束验证的候选项（`willValidate` (en-US) 为 `false`），或者它满足其约束，则为空字符串。此值可以通过 `setCustomValidity()` (en-US) 方法设置。

`validity` 只读

返回元素当前的有效状态。

`willValidate` 只读

返回元素是否是约束验证的候选项。如果任何条件阻止它进行约束验证，则为 `false`，包括：它的 `type` 是 `hidden`、`reset` 或 `button` 之一，它的祖先中有 `<datalist>` 或者它的 `disabled` 属性为 `true`。

### 仅适用于复选框和单选按钮元素的实例属性

`checked`

一个表示元素当前状态的布尔值。

`defaultChecked`

一个表示单选按钮或复选框的默认状态的布尔值，该值最初是在创建此对象的 HTML 中指定的。

`indeterminate`

一个表示复选框或单选按钮是否处于不确定状态的布尔值。对于复选框，效果是复选框的外观被某种方式遮挡/变灰，以表示其状态是不确定的（既不选中也不未选中）。不会影响 `checked` 属性的值，单击复选框将其值设置为假。

### 仅适用于图像类型的元素的实例属性

`alt`

一个表示元素的 `alt` 属性的字符串，包含要使用的替代文本。

`height`

一个表示元素的 `height` 属性的字符串，包含要显示为按钮的图像的高度。

`src`

一个表示元素的 `src` 属性的字符串，包含要显示为图形提交按钮上的图像的位置的 URI。

`width`

一个表示元素的 `width` 属性的字符串，包含要显示为按钮的图像的宽度。

### 仅适用于文件类型的元素的实例属性

`accept`

一个表示元素的 `accept` 属性的字符串，包含可以选择的文件类型的以逗号分隔的列表。

`files` (en-US)

一个 `FileList`，表示选择的要上传的文件。

`webkitdirectory`

一个表示 `webkitdirectory` 属性的布尔值。如果为 `true`，则文件系统选择器接口仅接受目录而不是文件。

`webkitEntries` (en-US) 只读

描述当前选择的文件或目录。

### 仅适用于包含文本或数字的可见元素的实例属性

`autocomplete`

一个表示元素的 `autocomplete` 属性的字符串，表示控件的值是否可以由浏览器自动填充。

`capture`

一个表示元素的 `capture` 属性的字符串，指示文件上传控件中的媒体捕获输入方法。

`max`

一个表示元素的 `max` 属性的字符串，包含此项的最大（数字或日期时间）值，该值不能小于其最小（`min` 属性）值。

`maxLength`

一个表示元素的 `maxlength` 属性的数字，包含值可以具有的最大字符数（以 Unicode 码点表示）。

`min`

一个表示元素的 `min` 属性的字符串，包含此项的最小（数字或日期时间）值，该值不能大于其最大（`max` 属性）值。

`minLength`

一个表示元素的 `minlength` 属性的数字，包含值可以具有的最小字符数（以 Unicode 码点表示）。

`pattern`

一个表示元素的 `pattern` 属性的字符串，包含要检查控件值的正则表达式。使用 `title` 属性来描述模式以帮助用户。此属性仅适用于 `type` 属性的值为 `text`、`search`、`tel`、`url` 或 `email` 的情况。

`placeholder`

一个表示元素的 `placeholder` 属性的字符串，包含一个提示，告诉用户可以在控件中输入什么。占位符文本不能包含回车或换行符。此属性仅适用于 `type` 属性的值为 `text`、`search`、`tel`、`url` 或 `email` 的情况。

`readOnly`

一个表示元素的 `readonly` 属性的布尔值，指示用户无法修改控件的值。如果 `type` 为 `hidden`、`range`、`color`、`checkbox`、`radio`、`file` 或按钮类型，则忽略此属性。

`selectionDirection`

一个表示选择发生的方向的字符串。可能的值为：`forward`（选择是从当前区域设置的起始到结束方向上执行的）、`backward`（相反的方向）或 `none`（方向未知）。

`selectionEnd`

一个表示选择文本的结束索引的数字。当没有选择时，它返回当前文本输入光标位置后面的字符的偏移量。

`selectionStart`

一个表示选择文本的开始索引的数字。当没有选择时，它返回当前文本输入光标位置的偏移量。

`size`

一个表示元素的 `size` 属性的数字，包含控件的可视大小。此值以像素为单位，除非 `type` 的值为 `text` 或 `password`，在这种情况下，它是一个整数字符数。仅当 `type` 设置为 `text`、`search`、`tel`、`url`、`email` 或 `password` 时才适用。

实例方法
----

*也从其父接口 `HTMLElement` 继承方法。*

`checkValidity()` (en-US)

返回一个布尔值，如果元素是约束验证的候选项，并且它不满足其约束，则为 `false`。在这种情况下，它还会在元素上触发 `invalid` 事件。如果元素不是约束验证的候选项，或者它满足其约束，则返回 `true`。

`reportValidity()` (en-US)

运行 `checkValidity()` 方法，如果它返回 false（对于无效输入或未提供模式属性），则以与提交表单相同的方式向用户报告输入无效。

`select()`

选择输入元素中的所有文本，并将其聚焦，以便用户随后可以替换其所有内容。

`setCustomValidity()` (en-US)

设置元素的自定义有效性消息。如果此消息不是空字符串，则元素存在自定义有效性错误，且其值无效。

`setRangeText()` (en-US)

替换输入元素中的一段文本为新文本。

`setSelectionRange()`

选择输入元素中的一段文本（但不聚焦）。

`showPicker()`

显示浏览器的日期、时间、颜色和文件选择器。

`stepDown()` (en-US)

按 `step` \* n 递减 `value`，其中 n 默认为 1（如果未指定）。

`stepUp()` (en-US)

按 `step` \* n 递增 `value`，其中 n 默认为 1（如果未指定）。

事件
--

*也从其父接口 `HTMLElement` 继承事件。*

使用 `addEventListener()` 或通过将事件监听器赋值给此接口的 `oneventname` 属性来监听这些事件：

`invalid` 事件

当元素在约束验证期间不满足其约束时触发。

`search` (en-US) 事件
非标准

当在 `type="search"` 的 `<input>` 上开始搜索时触发。

`select` 事件

当选中了一些文本时触发。

`selectionchange` 事件
实验性

在 `<input>` 元素中的文本选择发生更改后触发。

规范
--

| Specification |
| --- |
| HTML Standard # htmlinputelement |

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

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

参见
--

* 实现了该接口的 HTML 元素：`<input>`


BeforeUnloadEvent - Web API 接口参考

BeforeUnloadEvent
=================

**`beforeunload`** 事件触发于 window、document 和它们的资源即将卸载时。

当事件属性 `returnValue` 被赋值为非空字符串时，会弹出一个对话框，让用户确认是否离开页面（示例如下）。否则，事件被静默处理。一些浏览器实现仅在框架或内置框架接收到用户手势或交互时才显示对话框。在 浏览器兼容性 中查看更多信息。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | Yes |
| Target objects | defaultView |
| Interface | `Event` |

示例
--

```js
window.addEventListener("beforeunload", function (event) {
  event.returnValue = "\\o/";
});

//等同于
window.addEventListener("beforeunload", function (event) {
  event.preventDefault();
});
```

基于 Webkit 的浏览器没有遵循该弹窗规范。以下是一个基本跨浏览器运行的例子。

```js
window.addEventListener("beforeunload", function (e) {
  var confirmationMessage = "\\o/";

  (e || window.event).returnValue = confirmationMessage; //Gecko + IE
  return confirmationMessage; //Webkit, Safari, Chrome etc.
});
```

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

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

参见
--

* `DOMContentLoaded`
* `readystatechange`
* `load`
* `beforeunload`
* `unload`
* 卸载文档 — 提示卸载文档


Houdini API - Web API 接口参考

Houdini API
===========

Houdini 是一组底层 API，它们公开了 CSS 引擎的各个部分，从而使开发人员能够通过加入浏览器渲染引擎的样式和布局过程来扩展 CSS。Houdini 是一组 API，它们使开发人员可以直接访问 CSS 对象模型（CSSOM），使开发人员可以编写浏览器可以解析为 CSS 的代码，从而创建新的 CSS 功能，而无需等待它们在浏览器中本地实现。

Houdini 的优点
-----------

当样式改变时 Houdini 相比 JavaScript.style (en-US) 的方式能够能够更快的解析。浏览器在应用脚本中发现的任何样式更新之前，会对 CSSOM 进行解析——包括布局、绘制和合成过程。此外，对于 JavaScript 样式更新，布局、绘制和复合过程也会重复进行。Houdini 代码不会等待第一个渲染周期完成。相反，它被包含在第一个周期中——创建可渲染的、可理解的样式。Houdini 为在 JavaScript 中使用 CSS 值提供了一个基于对象的 API。

Houdini 的 CSS Typed OM 是一个包含类型和方法的 CSS 对象、并且暴露出了作为 JavaScript 对象的值。比起先前基于字符串的，对 `HTMLElement.style` 进行操作的方案，对 JavaScript 对象进行操作更符合直觉。每个元素和样式表规则都拥有一个样式对应表，该对应表可以通过 `StylePropertyMap` 来获得。

一个 CSS Houdini 的特性就是 Worklet (en-US)。在它的帮助下，你可以通过引入一行 JavaScript 代码来引入配置化的组件，从而创建模块式的 CSS。不依赖任何前置处理器、后置处理器或者 JavaScript 框架。

```js
<script>CSS.paintWorklet.addModule('csscomponent.js');</script>
```

以上添加进的模块包含一个 `registerPaint()` (en-US)函数，这个模块是完全通过可配置的 worklets 来注册的。

这个 CSS `paint()` 函数的参数包括 worklet 的名字，以及其他可选的参数。worklet 同时能够访问元素的自定义属性：它们不需要作为函数参数传递。

```css
li {
  background-image: paint(myComponent, stroke, 10px);
  --hilights: blue;
  --lowlights: green;
}
```

**备注：** 能力越大，责任越大！在 Houdini 的帮助下你能够在 css 中实现你自己的布局、栅格、或者区域特性，但是这么做并不是最佳实践。CSS 工作组已经做了许多努力来确保 CSS 中的每一项特性都能正常运行，覆盖各种边界情况，同时考虑到了安全、隐私，以及可用性方面的表现。如果你要深入使用 Houdini，确保你也把以上这些事项考虑在内！并且先从小处开始，再把你的自定义 Houdini 推向一个富有雄心的项目。

Houdini APIs
------------

在下面，你能够找到一些链接。这些链接指向 Houdini 范围下的 API 的主列表页面，同时链接到一些指导页来帮助你，如果你需要指导如何去使用这些 API。

CSS Parser API

 这是一个更直接地暴露出 CSS 解析器的 API，能够把任意 CSS 类语言解析成为一种中间类型。
 目前还没有该 API 的教程或参考。

CSS Properties and Values API

定义了一个用来注册新的 CSS 属性的 API。通过该 API 注册的属性必须用一种特定的解析语法书写，以定义其类型、继承行为以及初始值。

CSS Properties and Values API reference
CSS Properties and Values API guide (en-US)

CSS Typed OM

该 API 将 CSSOM 字符串转化为有类型意义的 JavaScript。这将对后续的一个重要的表现打下基础。CSS Typed OM 将 CSS 值以类型化处理的 JavaScript 对象的形式暴露出来，以使其表现可以被控制。

CSS Typed OM reference (en-US)
CSS Typed OM guide (en-US)

CSS Layout API

作为一个被设计来提升 CSS 扩展性的 API，该 API 能够让开发者去书写他们自己的布局算法，比如 masonry 或者 line snapping。该 API 目前还没有原生支持。目前还没有该 API 的教程或参考。

CSS Painting API

作为一个被设计来提升 CSS 扩展性的 API，该 API 允许开发者通过 `paint()` 方法书写 JavaScript 函数，以控制绘制元素的背景、边框或者内容区域。

CSS Painting API reference (en-US)
CSS Painting API guide (en-US)

Worklets

该 API 允许脚本独立于 JavaScript 执行环境，运行在渲染流程的各个阶段。Worklets 在概念上很接近于 Web Workers ，它由渲染引擎调用，并扩展了渲染引擎。

Worklets reference (en-US)

其他
--

以下主题你可能会感兴趣，它们可能在你使用 Houdini API 的时候起一些有趣的作用。

Composite Scrolling and Animation

TBD


HTMLDialogElement - Web API 接口参考

HTMLDialogElement
=================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

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

**`HTMLDialogElement`** 接口提供操作`<dialog>` 元素的方法.。此接口的方法和属性继承自 `HTMLElement` 接口。

属性
--

*继承自父接口， `HTMLElement`。*

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `open` | `Boolean` (en-US) | 来自`open` HTML 属性，表示这个对话框可以进行互动。 |
| `returnValue` | `DOMString` | 用户获取对话框的值 |

方法
--

*继承自父接口， `HTMLElement`。*

| 名称和参数 | 类型 | 描述 |
| --- | --- | --- |
| `close()` | `void` | 关闭对话框。可选传入类型为 `DOMString` 的参数，用来更新对话框的 returnValue。 |
| `show()` | `void` | 非模式化的显示这个对话框，即：打开这个对话框之后依然可以和其他内容进行交互。可选传入类型为 `Element` 或者 `MouseEvent` 的参数，用来定义对话框的显示位置。 |
| `showModal()` | `void` | 模式化的显示这个对话框，并且将会至于所有其他对话框的顶层（屏蔽其他对话框的交互）。可选传入类型为`Element` 或者 `MouseEvent` 的参数，用来定义对话框的显示位置。 |

Examples
--------

### Example 1

```html
<!-- Anchor point example -->
<dialog id="bronteDialog">
  <p>That was part of a poem by Emily Brontë!</p>
</dialog>

<blockquote>
  <p>
    "Then art thou glad to seek repose?<br />
    Art glad to leave the sea,<br />
    And <strong id="anchor">anchor</strong> all thy weary woes<br />
    In calm Eternity?"
  </p>
</blockquote>

<menu>
  <button id="showDialogButton">Show dialog</button>
</menu>

<script>
 (function () {
 var showDialogButton = document.getElementById("showDialogButton");

 // 'Show dialog' button opens dialog, anchored at third line of quote
 showDialogButton.addEventListener("click", function () {
 var bronteDialog = document.getElementById("bronteDialog");
 var anchorPoint = document.getElementById("anchor");
 bronteDialog.show(anchorPoint);
 });
 })();
</script>
```

### Example 2

```html
<!-- Simple pop-up dialog box, containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <section>
      <p>
        <label for="favAnimal">Favorite animal:</label>
        <select id="favAnimal" name="favAnimal">
          <option></option>
          <option>Brine shrimp</option>
          <option>Red panda</option>
          <option>Spider monkey</option>
        </select>
      </p>
    </section>
    <menu>
      <button id="cancel" type="reset">Cancel</button>
      <button type="submit">Confirm</button>
    </menu>
  </form>
</dialog>

<menu>
  <button id="updateDetails">Update details</button>
</menu>

<script>
 (function () {
 var updateButton = document.getElementById("updateDetails");
 var cancelButton = document.getElementById("cancel");

 // Update button opens a modal dialog
 updateButton.addEventListener("click", function () {
 document.getElementById("favDialog").showModal();
 });

 // Form cancel button closes the dialog box
 cancelButton.addEventListener("click", function () {
 document.getElementById("favDialog").close();
 });
 })();
</script>
```

规范
--

| Specification |
| --- |
| HTML Standard # htmldialogelement |

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

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

See also
--------

* The HTML element implementing this interface: `<dialog>`.


HTMLFieldSetElement - Web API 接口参考

HTMLFieldSetElement
===================

HTML Field Set Element
----------------------

DOM `fieldset` elements expose the HTMLFieldSetElement (HTMLFieldSetElement) interface, which provides special properties and methods (beyond the regular element object interface they also have available to them by inheritance) for manipulating the layout and presentation of field-set elements.

属性
--

属性继承自其父级 `HTMLElement`。

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `disabled` | `Boolean` | 读取 HTML 属性 `disabled`,表明用户是否可以操作该控件。 |
| `elements` | `readonly HTMLFormControlsCollection` | The elements belonging to this field set. |
| `form` 只读  | An `HTMLFormControlsCollection` (en-US) or `HTMLCollection` referencing the containing form element, if this element is in a form. If the field set is not a descendant of a form element, then the attribute can be the ID of any form element in the same document it is related to, or the `null` value if none matches. |  |
| `name` | `DOMString` | Reflects the `name` HTML attribute, containing the name of the field set, used for submitting the form. |
| `type` | `readonly DOMString` | 一定为字符串`fieldset`. |
| `validationMessage` | `readonly DOMString` | A localized message that describes the validation constraints that the element does not satisfy (if any). This is the empty string if the element is not a candidate for constraint validation (**willValidate** is false), or it satisfies its constraints. |
| `validity` | `readonly ValidityState` | The validity states that this element is in. |
| `willValidate` | `boolean` | Always false because `fieldset` objects are never candidates for constraint validation. |

方法
--

| 名称 & 参数 | 返回值 | 描述 |
| --- | --- | --- |
| `checkValidity`() | `Boolean` | 如果元素的值没有有效性问题，则返回 `true`，否则返回 `false` 并触发 `invalid` 事件。 |
| `setCustomValidity(in` DOMString `error)` | `void` | 设置一个自定义错误，则该元素将无法通过有效性验证。参数指定的字符串就是在向用户报告错误时显示的消息。如果为空字符串，则清除这个自定义错误。 |


HTMLDetailsElement - Web API 接口参考

HTMLDetailsElement
==================

**`HTMLDetailsElement`** 接口提供了特殊的属性 (除了常规的 `HTMLElement` 接口之外，它还可以通过继承获得这些属性) 用于操作 `<details>` 元素。

属性
--

*从其父级 `HTMLElement` 继承属性.*

`HTMLDetailsElement.open` (en-US)

是一个 `boolean` (en-US) 反射 `open` HTML 属性，指示是否向用户显示元素的内容 (不包括 `<summary>`)

方法
--

*没有特定的方法；继承其父方法 `HTMLElement`.*

规格
--

* HTML Living Standard
* HTML 5.2 (W3C Proposed Recommendation)
浏览器兼容性
------

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

另见
--

* 实现此接口的 HTML 元素： `<details>`


DOMRect - Web API 接口参考

DOMRect
=======

一个 **`DOMRect`** 代表一个矩形。

`DOMRect` 表示的盒子的类型由返回它的方法或属性指定。例如，WebVR API 的 `VREyeParameters.renderRect` (en-US) 指定了头戴式显示器的一只眼睛应该呈现的影像所在的 canvas 的视口。

它继承自它的父类，`DOMRectReadOnly`。

DOMRectReadOnly

DOMRect构造函数
----

`DOMRect()`

创建一个新的 `DOMRect` 对象。

属性
--

`DOMRect` 从其父类 *`DOMRectReadOnly`* 继承属性。不同之处在于它们不再是只读的。

`DOMRectReadOnly.x` (en-US)

`DOMRect` 原点的 x 坐标。

`DOMRectReadOnly.y` (en-US)

`DOMRect` 原点的 y 坐标。

`DOMRectReadOnly.width` (en-US)

`DOMRect` 的宽度。

`DOMRectReadOnly.height` (en-US)

`DOMRect` 的高度。

`DOMRectReadOnly.top` (en-US)

返回 `DOMRect` 的顶坐标值（与 `y` 具有相同的值，如果 `height` 为负值，则为 `y + height` 的值）。

`DOMRectReadOnly.right` (en-US)

返回 `DOMRect` 的右坐标值（与 `x + width` 具有相同的值，如果`width` 为负值，则为 `x` 的值）。

`DOMRectReadOnly.bottom` (en-US)

返回 `DOMRect` 的底坐标值（与 `y + height` 具有相同的值，如果 `height` 为负值，则为 `y` 的值）。

`DOMRectReadOnly.left` (en-US)

返回 `DOMRect` 的左坐标值（与 `x` 具有相同的值，如果 `width` 为负值，则为 `x + width` 的值）。

静态方法
----

`DOMRectReadOnly.fromRect()` (en-US)

创建一个具有指定位置和尺寸的新 `DOMRect` 对象。

规范
--

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

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

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

更多
--

* `DOMPoint`


IDBCursor - Web API 接口参考

IDBCursor
=========

IndexedDB API 中的 `IDBCursor` 接口表示一个游标，用于遍历或迭代数据库中的多条记录。

游标有一个源，指示需要遍历哪一个索引或者对象存储区。它在所属区间范围内有一个位置，根据记录健（存储字段）的顺序递增或递减方向移动。游标使应用程序能够异步处理在游标范围内的所有记录。

你可以在同一时间拥有无数个游标。你总会获得表示给定游标的同样的 `IDBCursor` 对象。在基础索引或对象存储上执行操作。

方法
--

`IDBCursor.advance` (en-US)

设置光标向前移动位置的次数。

`IDBCursor.continue` (en-US)

将游标按它的方向移动到下一个位置，到其健与可选健参数匹配的项。

`IDBCursor.delete` (en-US)

返回一个 `IDBRequest` 对象，并且在一个单独的线程中，删除游标位置记录，而不改变游标的位置。这个可以用作删除一些特定的记录。

`IDBCursor.update` (en-US)

返回一个 `IDBRequest` 对象，并且在一个单独的线程中，更新对象存储中当前游标位置的值。这个可以用来更新特定的记录。

属性
--

`IDBCursor.source` (en-US) 只读

返回一个游标正在迭代的 `IDBObjectStore` 或者 `IDBIndex` 。这个方法永远不会返回一个空或者抛出异常，即使游标当前正在被迭代，已迭代超过其结束，再或者其事务没有处于活动状态。

`IDBCursor.direction` 只读

返回光标遍历方向。请查看 常数 中可能的值。

`IDBCursor.key` 只读

返回记录中游标位置的有效主键。如果游标在区间之外，将会设置成 `undefined`。游标主键可以是任意的数据类型（data type）。

`IDBCursor.primaryKey` (en-US) 只读

返回游标当前有效的主键。如果游标当前正在被迭代或者已经在迭代在区间范围外，将会被设置成 `undefined` 。游标主键可以是任意的时间类型（data type）。

常量
--

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

**警告：** 这些常量不再被支持。你应该使用字符串常量。(Firefox bug 891944)

* `NEXT`: `"next"` :游标展示所有记录，包括重复的记录。它从主键区间下届开始逐步上升（按键的顺序单调递增）。
* `NEXTUNIQUE` : `"nextunique"` : 游标展示所有记录，不包括重复的记录。如果同一个主键存在重复的记录，只有第一条迭代记录被取出。它从主键区间的下界开始逐步上升
* `PREV`: `"prev"` : 游标展示所有记录，包括重复的记录。它从主键区间上界开始逐步往下移动（按主键的顺序单调递减）
* `PREVUNIQUE`: `"prevunique"` :游标展示所有记录，不包括重复的记录。如果主键存在重复记录，只有第一个迭代记录被取出。它从主键区间上界开始逐步往下移动。
示例
--

在这个简单的代码片段中，我们创建了一个事务和检索一个对象存储，之后使用一个游标遍历存储对象中所有的记录。游标不是必须使用主键来选则数据库，我们可以把它全部拿出来。同时需要注意在每次循环遍历中，你可以在当前记录下的游标对象中使用 `cursor.value.foo` 抓取数据。对于完整的工作示例，请查看我们的 IDBCursor example (在线查看示例)。

```js
function displayData() {
  var transaction = db.transaction(["rushAlbumList"], "readonly");
  var objectStore = transaction.objectStore("rushAlbumList");

  objectStore.openCursor().onsuccess = function (event) {
    var cursor = event.target.result;
    if (cursor) {
      var listItem = document.createElement("li");
      listItem.innerHTML = cursor.value.albumTitle + ", " + cursor.value.year;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log("Entries all displayed.");
    }
  };
}
```

Specifications
--------------

| Specification |
| --- |
| Indexed Database API 3.0 # cursor-interface |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (view example live.)


NamedNodeMap - Web API 接口参考

NamedNodeMap
============

**`NamedNodeMap`** 接口表示属性节点 `Attr` 对象的集合。尽管在 `NamedNodeMap` 里面的对象可以像数组一样通过索引来访问，但是它和 `NodeList` 不一样，对象的顺序没有指定。

`NamedNodeMap` 对象是即时的 (*live*)，因此，如果它内部包含的对象发生改变的话，该对象会自动更新到最新的状态。

**备注：** 尽管被称为 `NamedNodeMap`，但这个接口不是用来处理节点对象 (`Node`)，而是用来处理属性节点对象 (`Attr`)，属性节点原来是一种特殊的节点 (`Node`)，仍然在某些实现环境（浏览器）中有效。

属性
--

*该接口没有继承任何属性。*

`NamedNodeMap.length` (en-US) 只读

返回映射 (map) 中对象的数量。

方法
--

*该接口没有继承任何方法。*

`NamedNodeMap.getNamedItem()`

返回一个给定名字对应的属性节点（`Attr`）。

`NamedNodeMap.setNamedItem()` (en-US)

替换或添加一个属性节点（`Attr`）到映射（map）中。

`NamedNodeMap.removeNamedItem()` (en-US)

移除一个属性节点（`Attr`）。

`NamedNodeMap.item()` (en-US)

返回指定索引处的属性节点（`Attr`），或者，当索引超出或等于属性节点的数量时，返回 `null`。

`NamedNodeMap.getNamedItemNS()` (en-US)

根据给定的命名空间参数和 name 参数返回一个 `Attr` 对象。

`NamedNodeMap.setNamedItemNS()` (en-US)

替换、添加给定命名空间参数和 name 参数的 `Attr` 对象。

`NamedNodeMap.removeNamedItemNS()` (en-US)

删除给定命名空间参数和 name 参数的 `Attr` 对象。

规范
--

| Specification |
| --- |
| DOM Standard # interface-namednodemap |

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

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

相关链接
----

* `Element.attributes`