HTMLMediaElement - Web API 接口参考

HTMLMediaElement
================

HTML 媒体元素接口在属性和方法中添加了 HTML 元素来支持基础的媒体相关的能力，就像音频和视频一样。HTML 视频元素和HTML 音频元素元素都继承自此接口。

特性
--

*从父级 `HTMLElement`、`Element`、`Node` 和 `EventTarget` 继承属性。*

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `audioTracks` | `AudioTrackList` (en-US) | 表示在该元素中包含的`AudioTrack`对象列表 |
| `autoplay` | `Boolean` (en-US) |
 表示 `autoplay`
 的 HTML 属性，表明在视频加载可用时是否不中断地自动播放资源
  |
| `buffered` 只读  | `TimeRanges` | `buffered`属性会告诉浏览器哪一部分的媒体已经被下载（如果浏览器支持的话），按照标准会返回一个`TimeRanges`对象 |
| `controller` | `MediaController` | 返回当前媒体控制器的 MediaController 对象，如果没有连接就返回 null |
| `controls` | `Boolean` (en-US) |
 映射在 HTML
 标签。`controls`
 属性控制是否显示用户播放界面的控制 HTML
  |
| `crossOrigin` | `DOMString` |
 一个表示媒体元素
 CORS 设置的`DOMString`。从
 CORS settings attributes (en-US)
 查看更多详情
  |
| `currentSrc` 只读  | `DOMString` |
 用`DOMString`表示媒体文件的绝对 URL。如果`networkState`
 为`EMPTY，`那么值为空字符串。
  |
| `currentTime` | `double` | 当前播放时间，单位为秒。为其赋值将会使媒体跳到一个新的时间。 |
| `defaultMuted` | `Boolean` (en-US) |
 映射在 HTML 标签上。`muted`
 属性表示媒体声音被播放时是否应该被静音。这个属性不能动态设置静音/不静音，如果希望设置静音/不静音，请使用
 `muted` 属性
  |
| `defaultPlaybackRate` | `double` |
 控制媒体的播放速度。1.0 表示正常的播放速度，如果值小于
 1.0，则播放速度会比”正常速度“慢，如果值大于
 1.0，则播放速度会比”正常速度“快。0.0 是一个无效的值，并且会抛出
 `NOT_SUPPORTED_ERR` 错误。
  |
| `duration` 只读  | `double` |
 媒体以秒为单位的总长度时间，如果媒体不可用，则为 0.
 如果媒体可用，但时间长度未知，值为 NAN. 如果媒体是以 stream
 形式传输并且没有预定长度，则值为 Inf。
  |
| `ended` 只读  | `Boolean` (en-US) | 表示媒体是否已经播放完毕。 |
| `error` 只读  | `MediaError` (en-US) | `MediaError` (en-US) 对象表示最近的错误，如果没有错误则值为
 `null`。
  |
| `initialTime` 只读

非标准

已弃用
 | `double` | 初始播放位置（以秒为单位）。 |
| `loop` | `Boolean` (en-US) |
 会映射在 HTML 标签 `loop` 属性
 , 决定该媒体是否循环播放。
  |
| `mediaGroup` | `DOMString` |
 反映在 HTML `mediagroup`
 标签上。
 表示元素所归属的分组，同一组的媒体元素会共享同一个控制器（`controller`）。
  |
| mediaKeys
实验性
只读  | `MediaKeys` (en-US) |
 Returns a reference to the `MediaKeys` (en-US) interface,
 which is a set of keys that an associated HTMLMediaElement can use for
 decription of media data during playback.
  |
| `mozAudioChannelType`
非标准
 | `DOMString` |
 Can be used to set the audio channel that the sound coming from an
 `<audio>` or `<video>`
 element will play in, on a Firefox OS device. See
 Using the AudioChannels API
 for more details.
  |
| `mozChannels` 只读

非标准
 | `long` | 声道数 (比如 `2` 是立体声). |
| `mozFrameBufferLength`
非标准
 | `long` |
 Indicates the number of samples that will be returned in the
 framebuffer of each `MozAudioAvailable` event. This number
 is a total for all channels, and by default is set to be the number of
 channels \* 1024 (e.g., 2 channels \* 1024 samples = 2048 total).

 The `mozFrameBufferLength` property can be set to a new
 value, for lower latency, or larger amounts of data, etc. The size
 given *must* be a number between 512 and 16384. Using any other
 size results in an exception being thrown. The best time to set a new
 length is after the `loadedmetadata` event fires, when the
 audio info is known, but before the audio has started or
 `MozAudioAvailable` events have begun firing.
  |
| `mozSampleRate`只读

非标准
 | `long` | 播放内容的采样率（每秒采样次数）。比如，44100 就是一张 CD 的采样率。 |
| `mozSrcObject`
非标准
 | `MediaStream` |
 Lets you set or get the
 Media Stream (en-US) to be
 played or being played.
  |
| `muted` | `Boolean` (en-US) | `静音时为 true` ，否则是`false` . |
| `networkState` | `unsigned short` | 获取媒体时的网络状态

|  |  |  |
| --- | --- | --- |
| 常量定义 | 值 | 描述 |
| `NETWORK_EMPTY` | 0 | 还没数据。`readyState` 是 `HAVE_NOTHING`. |
| `NETWORK_IDLE` | 1 |  |
| `NETWORK_LOADING` | 2 | 正在加载。 |
| `NETWORK_NO_SOURCE` | 3 |  |

 |
| `paused` 只读  | `Boolean` (en-US) | 指示媒体元素是否被暂停。 |
| `playbackRate` | `double` |
 The current rate at which the media is being played back. This is used
 to implement user controls for fast forward, slow motion, and so
 forth. The normal playback rate is multiplied by this value to obtain
 the current rate, so a value of 1.0 indicates normal speed.

 If the `playbackRate` is negative, the media is played
 backwards.The audio is muted when the media plays backwards or
 if the fast forward or slow motion is outside a useful range (E.g.
 Gecko mute the sound outside the range `0.25` and
 `5.0`).

 The pitch of the audio is corrected by default and is the same for
 every speed. Some browsers implement the non-standard
 `preservespitch` property to control this.
  |
| `played` 只读  | `TimeRanges` | 媒体可被播放的范围。 |
| `preload` | `DOMString` |
 Reflects the `preload` HTML
 attribute, indicating what data should be preloaded, if any. Possible
 values are: `none`, `metadata`, `auto`.
 See `preload` attribute
 documentation for details.
  |
| `readyState` 只读  | `unsigned short` | The readiness state of the media.

|  |  |  |
| --- | --- | --- |
| Constant | Value | Description |
| `HAVE_NOTHING` | 0 | No information is available about the media resource. |
| `HAVE_METADATA` | 1 |
 Enough of the media resource has been retrieved that the
 metadata attributes are initialized. Seeking will no longer
 raise an exception.
  |
| `HAVE_CURRENT_DATA` | 2 |
 Data is available for the current playback position, but not
 enough to actually play more than one frame.
  |
| `HAVE_FUTURE_DATA` | 3 |
 Data for the current playback position as well as for at least a
 little bit of time into the future is available (in other words,
 at least two frames of video, for example).
  |
| `HAVE_ENOUGH_DATA` | 4 |
 Enough data is available—and the download rate is high
 enough—that the media can be played through to the end without
 interruption.
  |

 |
| `seekable` 只读  | `TimeRanges` | The time ranges that the user is able to seek to, if any**.** |
| `seeking` 只读  | `Boolean` (en-US) |
 Indicates whether the media is in the process of seeking to a new
 position.
  |
| `sinkId`
只读
实验性
 | `DOMString` |
 The unique ID of the audio device delivering output, or an empty string
 if it is using the user agent default. This ID should be one of the
 `MediaDeviceInfo.deviceid` values returned from
 `MediaDevices.enumeratedDevices()`,
 `id-multimedia`, or `id-communications`.
  |
| `src` | `DOMString` |
 Reflects the `src` HTML
 attribute, containing the URL of a media resource to use. Gecko
 implements a similar functionality for streams:
 `mozSrcObject`.
  |
| `textTracks` | `TextTrackList` (en-US) |
 Represents the list of `TextTrack` (en-US) objects
 contained in the element.
  |
| `videoTracks` | `VideoTrackList` (en-US) |
 Represents the list of `VideoTrack` (en-US) objects
 contained in the element.

**Note:** Yet Gecko supports only single track
 playback, and the parsing of tracks' metadata is only available for
 media with Ogg container foramt.

 |
| `volume` | `double` | 表示音频的音量。值从 0.0（静音）到 1.0（最大音量）。 |

Methods
-------

*Inherits methods from its parent,* *`HTMLElement`.*

| Name & Arguments | Return | Description |
| --- | --- | --- |
| `canPlayType(in` `DOMString``type)` | `DOMString`* `probably`: if the specified type appears to be playable.
* `maybe`: if it's impossible to tell whether the type is
 playable without playing it.
* The *empty string*: if the specified type definitely cannot
 be played.
 | Determines whether the specified media type can be played back.

**Note:** Previously
 `canPlayType('video/webm')` returned
 `'probably'`. Starting with Gecko 28,
 it returns `'maybe'`.
 (Firefox bug 884275)

 |
| `fastSeek(double time)` | `void` | Directly seek to the given time. |
| `load()` | `void` |
 Reset the media element and restart selecting the media resource. Any
 pending events are discarded. How much media data is fetched is still
 affected by the `preload` attribute. This method can be
 useful for releasing resources after any `src` attribute and
 `source` element descendants have been removed. Otherwise, it
 is usually unnecessary to use this method, unless required to rescan
 `source` element children after dynamic changes.
  |
| `mozGetMetadata()`
非标准
 | `Object` |
 The `mozGetMetadata` method returns a javascript object whose
 properties represent metadata from the playing media resource as {key:
 value} pairs. A separate copy of the data is returned each time the
 method is called.This method must be called after the
 `loadedmetadata` event fires.
  |
| `mozLoadFrom(HTMLMediaElement other)`
非标准

已弃用
 | `void` |
 This method, available only in old Mozilla's implementation, loads data
 from another media element. This works similarly to
 `load()` except that instead of running the normal resource
 selection algorithm, the source is simply set to the
 `other` element's `currentSrc`.This is
 optimized so this element gets access to all of the
 `other` element's cached and buffered data; in fact, the two
 elements share downloaded data so that data downloaded by either element
 is available to both.
  |
| `pause()` | `void` | 暂停播放。 |
| `play()` | `void` | 开始播放。 |
| setMediaKeys
实验性
 | `Promise` |
 Sets the `MediaKeys` (en-US) keys to use when decrypting
 media during playback.
  |
| setSinkId
实验性
 | `Promise` |
 Sets the ID of the audio device through which audio output should be
 rendered if the application is authorized to play out of a given device.
  |

Events
------

Audio and Video elements can fire quite a few different events (en-US).

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

| Specification |
| --- |
| HTML Standard # htmlmediaelement |

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

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

See also
--------

* References
    + `<video>` and `<audio>` HTML elements.
    + `HTMLVideoElement` and `HTMLAudioElement` interfaces, derived from `HTMLMediaElement`.
* Articles
    + Using HTML5 audio and video (en-US)
    + Media formats supported by the audio and video elements (en-US)
    + Web Audio API (en-US)


structuredClone() - Web API 接口参考

structuredClone()
=================

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
全局的 **`structuredClone()`** 方法使用结构化克隆算法将给定的值进行深拷贝。

 该方法还支持把原始值中的可转移对象转移到新对象，而不是把属性引用拷贝过去。
 可转移对象与原始对象分离并附加到新对象;它们不可以在原始对象中访问被访问到。

语法
--

```js
structuredClone(value)
structuredClone(value, { transfer })
```

### 参数

`value`

被克隆的对象。可以是任何结构化克隆支持的类型。

`transfer` 可选

是一个可转移对象的数组，里面的 `值` 并没有被克隆，而是被转移到被拷贝对象上。

### 返回值

返回值是原始`值`的深拷贝。

### 异常

`DataCloneError` `DOMException`

如果输入值的任一部分不可序列化，则抛出该异常。

附注
--

 这个函数可以用来进行深拷贝 JavaScript 变量。
 也支持循环引用，如下所示：

```js
// Create an object with a value and a circular reference to itself.
const original = { name: "MDN" };
original.itself = original;

// Clone it
const clone = structuredClone(original);

console.assert(clone !== original); // the objects are not the same (not same identity)
console.assert(clone.name === "MDN"); // they do have the same values
console.assert(clone.itself === clone); // and the circular reference is preserved
```

### Transferring values

 使用可选参数 `transfer` 里的值，可以使可转移对象（仅）被传递，不被克隆。
 传输导致原始对象（里的属性）无法继续使用。

**备注：** 一个可能有用的场景是在保存 buffer 之前先异步的校验里面的数据。为了避免 buffer 在保存之前有其他修改，你可以先克隆这个 buffer 然后校验数据。为了防止意外的错误引用，在传输数据时，任何修改 buffer 的尝试都会失败。

 以下演示了如何把一个数组的属性转义到新对象。
 返回结果时，原始对象里的 `uInt8Array.buffer` 会被清除掉。

```js
var uInt8Array = new Uint8Array(1024 \* 1024 \* 16); // 16MB
for (var i = 0; i < uInt8Array.length; ++i) {
  uInt8Array[i] = i;
}

const transferred = structuredClone(uInt8Array, {
  transfer: [uInt8Array.buffer],
});
console.log(uInt8Array.byteLength); // 0
```

 你可以克隆任意数量的对象，并传输对象的任意子集。
 例如 以下代码会把 `arrayBuffer1` 作为值传输 但不是 `arrayBuffer2`。

```js
const transferred = structuredClone(
  { x: { y: { z: arrayBuffer1, w: arrayBuffer2 } } },
  { transfer: [arrayBuffer1] },
);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-structuredclone |

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

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

参见
--

* `core-js` 已经支持 `structuredClone` 的 polyfill
* 结构化克隆算法
* 结构化克隆的 polyfill


EventSource - Web API 接口参考

EventSource
===========

**`EventSource`** 接口是 web 内容与服务器发送事件通信的接口。

一个 `EventSource` 实例会对 HTTP 服务器开启一个持久化的连接，以 `text/event-stream` 格式发送事件，此连接会一直保持开启直到通过调用 `EventSource.close()` 关闭。

EventTarget

EventSource
一旦连接开启，来自服务端传入的消息会以事件的形式分发至你代码中。如果接收消息中有一个 event 字段，触发的事件与 event 字段的值相同。如果不存在 event 字段，则将触发通用的 `message` 事件。

与 WebSocket 不同的是，服务器发送事件是单向的。数据消息只能从服务端到发送到客户端（如用户的浏览器）。这使其成为不需要从客户端往服务器发送消息的情况下的最佳选择。例如，对于处理如社交媒体状态更新、消息来源（news feed）或将数据传递到客户端存储机制（如 IndexedDB 或 web 存储）之类的，`EventSource` 无疑是一个有效方案。

**警告：** 当**不使用 HTTP/2** 时，服务器发送事件（SSE）受到打开连接数的限制，这个限制是*对于浏览器*的，并且设置为非常低的数字（6），打开多个选项卡时可能会特别痛苦。在 Chrome 和 Firefox 中，这个问题已被标记为“不会修复”。这个限制是每个浏览器和域名的，这意味着你可以在所有标签页中打开 6 个 SSE 连接到 `www.example1.com`，以及另外 6 个 SSE 连接到 `www.example2.com`（来源：Stackoverflow）。当使用 HTTP/2 时，最大并发 *HTTP 流*的数量是由服务器和客户端协商的（默认为 100）。

构造函数
----

`EventSource()`

创建一个新的 `EventSource`，用于从指定的 URL 接收服务器发送事件，可以选择开启凭据模式。

实例属性
----

*此接口从其父接口 `EventTarget` 继承属性。*

`EventSource.readyState` (en-US) 只读

一个代表连接状态的数字。可能值是 `CONNECTING`（`0`）、`OPEN`（`1`）或 `CLOSED`（`2`）。

`EventSource.url` (en-US) 只读

一个表示事件源的 URL 字符串。

`EventSource.withCredentials` (en-US) 只读

一个布尔值，表示 `EventSource` 对象是否使用跨源资源共享（CORS）凭据来实例化（`true`），或者不使用（`false`，即默认值）。

### 实例方法

*此接口也从其父接口 `EventTarget` 继承了方法。*

`EventSource.close()`

关闭连接（如果有），并将 `readyState` 属性设置为 `CLOSED`。如果连接已经关闭，则该方法不执行任何操作。

事件
--

`error`

在事件源连接未能打开时触发。

`message`

在从事件源接收到数据时触发。

`open`

在与事件源的连接打开时触发。

此外，事件源本身可以发送具有 event 字段的消息，这将创建一个以该值为键的特定事件。

示例
--

在这个基本的例子中，创建了一个 `EventSource` 来从服务器接收未命名的事件；一个名为 `sse.php` 的页面负责生成这些事件。

```js
const evtSource = new EventSource("sse.php");
const eventList = document.querySelector("ul");

evtSource.onmessage = (e) => {
  const newElement = document.createElement("li");

  newElement.textContent = `message: ${e.data}`;
  eventList.appendChild(newElement);
};
```

每个接收到的事件都会导致我们的 `EventSource` 对象的 `onmessage` 事件处理程序运行。它会创建一个新的 `<li>` 元素，并将消息的数据写入其中，然后将新元素附加到文档中已有的列表元素中。

**备注：** 你可以在 Github 上找到完整的示例——使用 PHP 语言的简单 SSE 示例。

要监听具名事件，你需要为每种类型的事件添加一个监听器。

```js
const sse = new EventSource("/api/v1/sse");

/\*
 \* 这将仅监听类似下面的事件
 \*
 \* event: notice
 \* data: useful data
 \* id: someid
 \*/
sse.addEventListener("notice", (e) => {
  console.log(e.data);
});

/\*
 \* 同理，以下代码将监听具有字段 `event: update` 的事件
 \*/
sse.addEventListener("update", (e) => {
  console.log(e.data);
});

/\*
 \* “message”事件是一个特例，因为它可以捕获没有 event 字段的事件，
 \* 以及具有特定类型 `event：message` 的事件。
 \* 它不会触发任何其他类型的事件。
 \*/
sse.addEventListener("message", (e) => {
  console.log(e.data);
});
```

规范
--

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

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

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

参见
--

* 服务器发送事件
* 使用服务器发送事件


AmbientLightSensor - Web API 接口参考

AmbientLightSensor
==================

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

**环境光传感器 API (en-US)** 的 `AmbientLightSensor` 返回一个用于访问 `AmbientLightSensorReading` (en-US) 的接口。

实例
--

`AmbientLightSensor.AmbientLightSensor()`

`创建一个新的 AmbientLightSensor` 对象。

属性
--

`AmbientLightSensor.reading`

返回一个 `AmbientLightSensorReading` (en-US) 接口，包含当前光的亮度级别。

### Examples

```js
// TBD
```

规范
--

| Specification |
| --- |
| Ambient Light Sensor # ambient-light-sensor-interface |

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

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


TimeRanges - Web API 接口参考

TimeRanges
==========

`TimeRanges` 接口用来表示一组时间范围，主要目的是跟踪供`<audio>` 和`<video>` 元素加载使用的媒体哪些部分已经被缓冲。
一个 `TimeRanges` 对象包括一个或多个时间范围，其中每个都由一个开始偏移量和结束偏移量指定。你可以将你想要检索的时间范围的索引值传递给 `start()` 和 `end()` 方法来引用每个时间范围。

术语"normalized TimeRanges object"指出这种对象中的范围时有序的，不重叠的，不为空并且不接触的（相邻范围被折叠成更大的范围）。

属性
--

`TimeRanges.length` 只读

返回一个 `unsigned long` 类型的数字。表示由 time range 对象表示的 time ranges 的数量。

方法
--

`TimeRanges.start()`

返回具有指定索引的范围的开始时间。

`TimeRanges.end()`

返回指定范围的结束时间。

规范
--

| Specification |
| --- |
| HTML Standard # time-ranges |

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

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


ReadableStreamDefaultController - Web API 接口参考

ReadableStreamDefaultController
===============================

Stream API 中的 **`ReadableStreamDefaultController`** 接口是一个控制器，该控制器允许控制 `ReadableStream` 的状态和内部队列。默认控制器用于不是字节流的流。

构造函数
----

无。`ReadableStreamDefaultController` 实例会在构造 `ReadableStream` 时被自动创造。

实例属性
----

`ReadableStreamDefaultController.desiredSize` 只读

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

实例方法
----

`ReadableStreamDefaultController.close()`

关闭关联的流。

`ReadableStreamDefaultController.enqueue()`

将给定的块排入关联的流。

`ReadableStreamDefaultController.error()`

导致未来任何与关联流交互都会出错。

示例
--

在下面的简单示例中，使用构造函数创建一个自定义的 `ReadableStream` （有关完整代码，参见我们的简单随机流展示）。`start()` 函数每秒生成一个随机字符串并且将他们送入流中。`cancel()` 函数用于在 `ReadableStream.cancel()` 被调用时停止随机字符串的生成。

请注意，`ReadableStreamDefaultController` 对象应作为参数传递给 `start()` 和 `pull()` 函数。

当按下按钮时，将停止生成，使用 `ReadableStreamDefaultController.close()` 关闭流，并运行另一个将数据读回流中的函数。

```js
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();
      // 将随机字符串添加到流
      controller.enqueue(string);
      // 在屏幕上展示
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);
    button.addEventListener("click", function () {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // 在这个例子中不使用 pull
  },
  cancel() {
    // 如果取消了 reader，则会调用该函数，
    // 所以我们应该在这里停止生成字符串
    clearInterval(interval);
  },
});
```

规范
--

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

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

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

参见
--

* Stream API 概念
* 使用可读流
* `ReadableStream`
* WHATWG Stream Visualiser，用于可读、可写和转换流的基本可视化。
* Web-streams-polyfill 或 sd-streams——polyfill


TransitionEvent - Web API 接口参考

TransitionEvent
===============

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

TransitonEvent 接口指那些提供了与 transition 有关信息的事件。

属性
--

*同时也继承了父类 `Event`* 的属性。

`TransitionEvent.propertyName` (en-US) 只读

是一个`DOMString`，代表与这个 transition 有关的 CSS 属性名。

`TransitionEvent.elapsedTime` (en-US) 只读

是一个 float 值，代表从这个事件触发开始，这个 transition 运行的时间（以秒为单位）。这个值不受 `transition-delay` 属性的影响。

`TransitionEvent.pseudoElement` (en-US) 只读

是一个以 '::' 开头的 `DOMString`, 代表这个过渡运行于其上的伪元素的名字。如果这个过渡不是在一个伪元素上而是在一个元素上运行的，这个值就是一个空值''。

构造函数
----

`TransitionEvent()` (en-US)

用给定的参数创建一个 TransitionEvent 事件。

方法
--

\*同时也继承了父类 `Event`\*的方法。

`TransitionEvent.initTransitionEvent()` (en-US)
非标准

已弃用

使用已经废弃的`Document.createEvent("TransitionEvent")` 方法初始化已经创建的 TransitonEvent 事件。

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

| Specification |
| --- |
| CSS Transitions # interface-transitionevent |

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

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

See also
--------

* Using CSS transitions
* CSS properties: `transition`, `transition-delay`, `transition-duration`, `transition-property`, `transition-timing-function`.


DynamicsCompressorNode - Web API 接口参考

DynamicsCompressorNode
======================

`DynamicsCompressorNode` 接口提供了一个压缩效果器，用以降低信号中最响部分的音量，来协助避免在多个声音同时播放并叠加在一起的时候产生的削波失真。通常用于音乐创作和游戏音效中。`DynamicsCompressorNode` 是一个 `AudioNode` ，只有一路输入和一路输出，使用 `AudioContext.createDynamicsCompressor()` (en-US) 方法创建。

|  |  |
| --- | --- |
| Number of inputs | `1` |
| Number of outputs | `1` |
| Channel count mode | `"explicit"` |
| Channel count | `2` |
| Channel interpretation | `"speakers"` |

构造方法
----

`DynamicsCompressorNode()` (en-US)

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

属性
--

*由父类 `AudioNode` 派生。*

`DynamicsCompressorNode.threshold` (en-US) 只读

比例系数 (en-US) `AudioParam` 型。分贝高于此值时，将会进行压缩。

`DynamicsCompressorNode.knee` (en-US) 只读

比例系数 (en-US) `AudioParam` 型。当超出 threshold 设置的值之后，曲线在哪个点开始朝着 ratio 设置的部分平滑变换。

`DynamicsCompressorNode.ratio` (en-US) 只读

比例系数 (en-US) `AudioParam` 型。输入增益变化多少来产生 1 dB 的输出。

`DynamicsCompressorNode.reduction` (en-US) 只读

`float` 型。表示当前压缩器使用的增益压缩值。

`DynamicsCompressorNode.attack` (en-US) 只读

比例系数 (en-US) `AudioParam` 型。降低增益 10 dB 的时间（单位为秒）。

`DynamicsCompressorNode.release` (en-US) 只读

比例系数 (en-US) `AudioParam` 型。提升增益 10 dB 的时间（单位为秒）。

方法
--

*没有自定义的方法，继承父类 `AudioNode` 中的方法。*

示例
--

参见 `BaseAudioContext.createDynamicsCompressor()` (en-US) 以查看示例代码。

规范
--

| Specification |
| --- |
| Web Audio API # DynamicsCompressorNode |

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

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

参见
--

* Using the Web Audio API (en-US)


EventTarget - Web API 接口参考

EventTarget
===========

`EventTarget` 接口由可以接收事件、并且可以创建侦听器的对象实现。换句话说，任何事件目标都会实现与该接口有关的这三个方法。

`Element` 及其子项、`document` 和 `window` 是最常见的事件目标，但其他对象也可以是事件目标。比如 `XMLHttpRequest`、`AudioNode` 和 `AudioContext` 等等。

许多事件目标（包括 `element`、`document` 和 `window`）都支持通过 `onevent` 特性和属性设置事件处理程序 (en-US)。

构造函数
----

`EventTarget()`

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

方法
--

`EventTarget.addEventListener()`

在 `EventTarget` 上注册特定事件类型的事件处理程序。

`EventTarget.removeEventListener()`

`EventTarget` 中删除事件侦听器。

`EventTarget.dispatchEvent()`

将事件分派到此 `EventTarget`。

规范
--

| Specification |
| --- |
| DOM Standard # interface-eventtarget |

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

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

参见
--

* 事件参考——站点中列出的事件
* 事件介绍
* `Event` 接口


LockManager - Web API 接口参考

LockManager
===========

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

Web Locks API 的 **`LockManager`** 接口提供了请求新的 `Lock` 对象以及枚举现有的 `Lock` 对象的方法。要获取 `LockManager` 实例，请访问 `navigator.locks` 属性。

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

实例方法
----

`LockManager.request()`

请求一个指定其名称和模式参数的 `Lock` 对象。

`LockManager.query()`

返回一个 `Promise`，兑现一个包含持有的锁以及等待的锁请求的对象。

规范
--

| Specification |
| --- |
| Web Locks API # api-lock-manager |

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

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


HTMLBodyElement - Web API 接口参考

HTMLBodyElement
===============

**`HTMLBodyElement`** 接口提供了用于操作 `<body>` 元素的特定属性（除继承自 `HTMLElement` 接口的属性以外）。

EventTarget

Node

Element

HTMLElement

HTMLBodyElement实例属性
----

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

`HTMLBodyElement.aLink`
已弃用

一个表示活动链接颜色的字符串。

`HTMLBodyElement.background`
已弃用

一个表示背景图片资源位置的字符串。注意，这不是 URI，尽管一些旧版浏览器可能会期望它是。

`HTMLBodyElement.bgColor`
已弃用

一个表示文档背景颜色的字符串。

`HTMLBodyElement.link`
已弃用

一个表示未访问链接颜色的字符串。

`HTMLBodyElement.text`
已弃用

一个表示文本前景色的字符串。

`HTMLBodyElement.vLink`
已弃用

一个表示已访问链接颜色的字符串。

实例方法
----

*无特定方法；从其父接口 `HTMLElement` 继承方法。*

事件处理器
-----

从 `HTMLElement` 继承事件。

以下以 `Window` 为目标的 `onXYZ` 事件处理器属性同样在 `window` 对象这一别名目标上可用。但建议直接在 `window` 对象上监听这些事件，而不是在 `HTMLBodyElement` 上。

**备注：** 对于以下的 `onXYZ` 事件处理器，在 `HTMLBodyElement` 上使用 `addEventListener()` 将不会生效。请在 `window` 对象上监听这些事件。

`HTMLBodyElement.onafterprint`

在关联的文档开始打印或打印预览关闭后触发。

`HTMLBodyElement.onbeforeprint`

在关联的文档即将打印或预览打印时触发。

`HTMLBodyElement.onbeforeunload`

在窗口、文档及其资源即将被卸载时触发。

`HTMLBodyElement.ongamepadconnected`

在浏览器检测到游戏手柄已连接或首次使用游戏手柄的按钮/轴时触发。

`HTMLBodyElement.ongamepaddisconnected` (en-US)

在浏览器检测到游戏手柄已断开连接时触发。

`HTMLBodyElement.onhashchange`

在 URL 的片段标识符（URL 中以 `#` 符号开头和紧跟的部分）发生变化时触发。

`HTMLBodyElement.onlanguagechange` (en-US)

在用户首选语言发生变更时触发。

`HTMLBodyElement.onmessage`

在窗口接收到消息时触发，例如来自另一个浏览上下文的 `Window.postMessage()` 调用。

`HTMLBodyElement.onmessageerror`

在窗口接收到无法反序列化的消息时触发。

`HTMLBodyElement.onoffline`

在浏览器失去网络连接且 `Navigator.onLine` (en-US) 的值变为 `false` 时触发。

`HTMLBodyElement.ononline`

在浏览器获得网络连接且 `Navigator.onLine` (en-US) 的值变为 `true` 时触发。

`HTMLBodyElement.onpagehide`

在浏览器在呈现会话历史中的不同页面而隐藏当前页面时触发。

`HTMLBodyElement.onpageshow`

在浏览器由于导航而显示窗口的文档时触发。

`HTMLBodyElement.onpopstate`

在用户导航会话历史而使活动历史条目发生变化时触发。

`HTMLBodyElement.onrejectionhandled`

在 JavaScript `Promise` 被拒绝且拒绝已被处理时触发。

`HTMLBodyElement.onstorage`

在另一个文档的上下文中修改存储区（`localStorage`）时触发。

`HTMLBodyElement.onunhandledrejection`

在 JavaScript `Promise` 被拒绝且拒绝未被处理时触发。

`HTMLBodyElement.onunload`

在文档被卸载时触发。

规范
--

| Specification |
| --- |
| HTML Standard # htmlbodyelement |

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

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

参见
--

* 实现了此接口的 HTML 元素：`<body>`


SVGSVGElement - Web API 接口参考

SVGSVGElement
=============

该 **`SVGSVGElement`** 接口提供对`<svg>`元素的属性的访问，以及操作它们的方法。此接口还包含各种常用的实用方法，例如矩阵操作和控制可视渲染设备上重绘时间的功能。

属性
--

*此接口还从其父* *`SVGGraphicsElement`* *继承属性，并且还实现* *`SVGZoomAndPan`* *，* *`SVGFitToViewBox`* *中的属性。*

`SVGSVGElement.x` 只读

`SVGAnimatedLength` (en-US) 对应于给定 `<svg>` 元素的 `x` 属性

`SVGSVGElement.y` 只读

`SVGAnimatedLength` (en-US)对应于给定`<svg>`元素的`y`属性。

`SVGSVGElement.width` 只读

`SVGAnimatedLength` (en-US)对应于给定`<svg>`元素的`width`属性。

`SVGSVGElement.height` 只读

`SVGAnimatedLength` (en-US)对应于给定`<svg>`元素的`height`属性。

`SVGSVGElement.contentScriptType`

`SVGAnimatedLength` (en-US)对应于给定`<svg>`元素的`contentScriptType`属性。

`SVGSVGElement.contentStyleType`

`SVGAnimatedLength` (en-US)对应于给定`<svg>`元素的`contentStyleType`属性。

`SVGSVGElement.viewport`

一个`SVGRect` (en-US)，包含与给定`<svg>`元素对应的视口（隐式或显式）的位置和大小。当浏览器实际呈现内容时，位置和大小值表示呈现时的实际值。位置和大小值是父元素坐标系中的无单位值。如果不存在父元素（即`<svg>`元素表示文档树的根），如果此 SVG 文档作为另一文档的一部分嵌入（例如，通过 HTML  object element），然后位置和大小是父文档坐标系中的无单位值。（如果父级使用 CSS 或 XSL 布局，

`SVGSVGElement.pixelUnitToMillimeterX`
已弃用

一个浮点数，表示沿视口 x 轴的像素单位（由 CSS2 定义）的大小，表示 70dpi 到 120dpi 范围内的某个单位，并且在支持此功能的系统上，可能实际上与特征匹配目标媒体。在不可能知道像素大小的系统上，提供合适的默认像素大小。

`SVGSVGElement.pixelUnitToMillimeterY`
已弃用

浮点数，表示沿视口 y 轴的像素单位大小。

`SVGSVGElement.screenPixelToMillimeterX`
已弃用

DOM 级别 2 中的用户界面（UI）事件指示给定 UI 事件发生的屏幕位置。当浏览器实际知道“屏幕单元”的物理尺寸时，此浮动属性将表示该信息; 否则，用户代理将提供合适的默认值，例如.28mm。

`SVGSVGElement.screenPixelToMillimeterY`
已弃用

沿着视口的 y 轴的屏幕像素的对应大小。

`SVGSVGElement.useCurrentView`

当前最内层 SVG 文档片段的初始视图（即放大和平移之前）可以是“标准”视图，即基于`<svg>`元素的属性，例如`viewBox`）或“自定义”视图（即指向特定`<view>`或其他元素的超链接）。如果初始视图是“标准”视图，则此属性为`false`。如果初始视图是“自定义”视图，则此属性为`true`。

`SVGSVGElement.currentView`

`SVGViewSpec`定义当前最里面的 SVG 文档片段的初始视图（即，放大和平移之前）。意义取决于具体情况：如果初始视图是“标准”视图，则：

* `viewBox`，`preserveAspectRatio`和`currentView`中的`zoomAndPan (en-US)`的值将与值匹配对于`SVGSVGElement`直接打开的相应 DOM 属性
* } `currentView`中的`transform`和`viewTarget`的值将为 null

如果初始视图是`<view>`元素的链接，那么：

* 在`currentView`中`viewBox`，`preserveAspectRatio`和`zoomAndPan (en-US)`的值将对应于给定`<view>`元素的相应属性
* } `currentView`中的`transform`和`viewTarget`的值将为 null

如果初始视图是指向另一个元素的链接（即，除了`<view>`之外的其他元素，则：

* `viewBox`，`preserveAspectRatio`和`currentView`中的`zoomAndPan (en-US)`的值将与值匹配对于`SVGSVGElement`直接用于最近祖先`<svg>`元素的相应 DOM 属性
* `currentView`中`transform`的值将为 null
* `currentView`中的`viewTarget`将代表链接的目标

如果初始视图是使用 SVG 视图规范片段标识符（即#svgView（...））链接到 SVG 文档片段，则：

* the values for `viewBox`, `preserveAspectRatio`, `zoomAndPan (en-US)`, `transform` and `viewTarget` within `currentView` will correspond to the values from the SVG view specification fragment identifier

`SVGSVGElement.currentScale`

On an outermost `<svg>` element, this float attribute indicates the current scale factor relative to the initial view to take into account user magnification and panning operations. DOM attributes `currentScale` and `currentTranslate` are equivalent to the 2x3 matrix `[a b c d e f] = [currentScale 0 0 currentScale currentTranslate.x currentTranslate.y]`. If "magnification" is enabled (i.e., `zoomAndPan="magnify"`), then the effect is as if an extra transformation were placed at the outermost level on the SVG document fragment (i.e., outside the outermost `<svg>` element).

`SVGSVGElement.currentTranslate` 只读

An `SVGPoint` (en-US) representing the translation factor that takes into account user "magnification" corresponding to an outermost `<svg>` element. The behavior is undefined for <svg> elements that are not at the outermost level.

Methods
-------

*This interface also inherits methods from its parent, `SVGGraphicsElement` and also implements the ones from `SVGZoomAndPan`, `SVGFitToViewBox`.*

`SVGSVGElement.suspendRedraw()`
已弃用

Takes a time-out value which indicates that redraw shall not occur until:

the corresponding unsuspendRedraw() call has been made, an unsuspendRedrawAll() call has been made, or its timer has timed out.

In environments that do not support interactivity (e.g., print media), then redraw shall not be suspended. Calls to `suspendRedraw()` and `unsuspendRedraw()` should, but need not be, made in balanced pairs.

To suspend redraw actions as a collection of SVG DOM changes occur, precede the changes to the SVG DOM with a method call similar to:

```js
suspendHandleID = suspendRedraw(maxWaitMilliseconds);
```

and follow the changes with a method call similar to:

```js
unsuspendRedraw(suspendHandleID);
```

Note that multiple suspendRedraw calls can be used at once and that each such method call is treated independently of the other suspendRedraw method calls.

`SVGSVGElement.unsuspendRedraw()`
已弃用

Cancels a specified `suspendRedraw()` by providing a unique suspend handle ID that was returned by a previous `suspendRedraw()` call.

`SVGSVGElement.unsuspendRedrawAll()`
已弃用

Cancels all currently active `suspendRedraw()` method calls. This method is most useful at the very end of a set of SVG DOM calls to ensure that all pending `suspendRedraw()` method calls have been cancelled.

`SVGSVGElement.forceRedraw()`
已弃用

In rendering environments supporting interactivity, forces the user agent to immediately redraw all regions of the viewport that require updating.

`SVGSVGElement.pauseAnimations()`

Suspends (i.e., pauses) all currently running animations that are defined within the SVG document fragment corresponding to this `<svg>` element, causing the animation clock corresponding to this document fragment to stand still until it is unpaused.

`SVGSVGElement.unpauseAnimations()`

Unsuspends (i.e., unpauses) currently running animations that are defined within the SVG document fragment, causing the animation clock to continue from the time at which it was suspended.

`SVGSVGElement.animationsPaused()`

Returns true if this SVG document fragment is in a paused state.

`SVGSVGElement.getCurrentTime()`

Returns the current time in seconds relative to the start time for the current SVG document fragment. If getCurrentTime is called before the document timeline has begun (for example, by script running in a `<script>` element before the document's SVGLoad event is dispatched), then 0 is returned.

`SVGSVGElement.setCurrentTime()`

Adjusts the clock for this SVG document fragment, establishing a new current time. If `setCurrentTime` is called before the document timeline has begun (for example, by script running in a `<script>` element before the document's SVGLoad event is dispatched), then the value of seconds in the last invocation of the method gives the time that the document will seek to once the document timeline has begun.

`SVGSVGElement.getIntersectionList()`

Returns a `NodeList` of graphics elements whose rendered content intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in `pointer-events` processing.

`SVGSVGElement.getEnclosureList()`

Returns a `NodeList` of graphics elements whose rendered content is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in `pointer-events` processing.

`SVGSVGElement.checkIntersection()`

Returns `true` if the rendered content of the given element intersects the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in `pointer-events` processing.

`SVGSVGElement.checkEnclosure()`

Returns `true` if the rendered content of the given element is entirely contained within the supplied rectangle. Each candidate graphics element is to be considered a match only if the same graphics element can be a target of pointer events as defined in `pointer-events` processing.

`SVGSVGElement.deselectAll()`

Unselects any selected objects, including any selections of text strings and type-in bars.

`SVGSVGElement.createSVGNumber()`

Creates an `SVGNumber` (en-US) object outside of any document trees. The object is initialized to a value of zero.

`SVGSVGElement.createSVGLength()`

Creates an `SVGLength` (en-US) object outside of any document trees. The object is initialized to a value of zero user units.

`SVGSVGElement.createSVGAngle()`

Creates an `SVGAngle` (en-US) object outside of any document trees. The object is initialized to a value of zero degrees (unitless).

`SVGSVGElement.createSVGPoint()`

Creates an `SVGPoint` (en-US) object outside of any document trees. The object is initialized to the point (0,0) in the user coordinate system.

`SVGSVGElement.createSVGMatrix()`

Creates an `SVGMatrix` object outside of any document trees. The object is initialized to the identity matrix.

`SVGSVGElement.createSVGRect()`

Creates an `SVGRect` (en-US) object outside of any document trees. The object is initialized such that all values are set to 0 user units.

`SVGSVGElement.createSVGTransform()`

Creates an `SVGTransform` (en-US) object outside of any document trees. The object is initialized to an identity matrix transform (`SVG_TRANSFORM_MATRIX`).

`SVGSVGElement.createSVGTransformFromMatrix()`

Creates an `SVGTransform` (en-US) object outside of any document trees. The object is initialized to the given matrix transform (i.e., `SVG_TRANSFORM_MATRIX`). The values from the parameter matrix are copied, the matrix parameter is not adopted as `SVGTransform::matrix`.

`SVGSVGElement.getElementById()`

Searches this SVG document fragment (i.e., the search is restricted to a subset of the document tree) for an Element whose id is given by *elementId*. If an Element is found, that Element is returned. If no such element exists, returns null. Behavior is not defined if more than one element has this id.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # InterfaceSVGSVGElement |

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

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

参见
--

* `<circle>`


UIEvent - Web API 接口参考

UIEvent
=======

`UIEvent` 接口表示简单的用户界面事件。

`UIEvent` 是从 `Event` 派生出来的。尽管 `UIEvent.initUIEvent()` (en-US) 方法为了向后兼容而一直保留着，但是你应该使用 `UIEvent()` 构造器来创建 `UIEvent` 对象。

某些接口是这个的直接或间接后代：`MouseEvent`, `TouchEvent`, `FocusEvent`, `KeyboardEvent`, `WheelEvent`, `InputEvent`, 和`CompositionEvent`.

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

`UIEvent()`

创建一个 `UIEvent` 对象

属性
--

*也继承了父代 `Event` 的一些属性。*

`UIEvent.cancelBubble` (en-US)
非标准

已弃用

返回一个 `Boolean`，表示该事件的冒泡是否被取消。

`UIEvent.detail`只读

Returns a `long` with details about the event, depending on the event type.

`UIEvent.layerX` (en-US)
非标准
 只读

返回事件相对于当前层的水平坐标。

`UIEvent.layerY` (en-US)
非标准
 只读

返回事件相对于当前层的垂直坐标。

`UIEvent.pageX`
非标准
 只读

返回事件相对于整个文档的水平坐标。

`UIEvent.pageY`
非标准
 只读

返回事件相对于整个文档的垂直坐标。

`UIEvent.sourceCapabilities` (en-US)
非标准
 只读

返回输入设备功能接口的一个实例，它提供有关负责生成 touch 事件的物理设备的信息。

`UIEvent.view`只读

返回一个包含了产生该事件的视图的 `WindowProxy` 。

`UIEvent.which`
非标准
 只读

返回一个对应（键盘）按下的数字类型的 `keyCode` ，或者一个字母数字键按下时的字符码 (`charCode`)。

方法
--

*也继承了父代 `Event` 的一些方法。*

`UIEvent.initUIEvent()` (en-US)
已弃用

初始化一个 `UIEvent` 对象。如果事件已经被分派，这个方法什么都不做。

规范
--

| Specification |
| --- |
| UI Events # idl-uievent |

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

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

相关链接
----

* Introduction to events
* `Event`


Crypto - Web API 接口参考

Crypto
======

**`Crypto`** 接口提供了当前上下文中可用的基本的加密功能。它允许访问一个密码学安全的随机数生成器和密码学原语（cryptographic primitive）。

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

Web Crypto API 可以通过 `crypto` 属性（一个 `Crypto` 对象）来访问。

实例属性
----

*该接口实现的属性定义在 `RandomSource` 中。*

`Crypto.subtle` 只读  安全上下文

返回一个 `SubtleCrypto` 对象，用来访问公共的密码学原语，例如哈希、签名、加密以及解密。

实例方法
----

*该接口实现的方法定义在 `RandomSource` 中。*

`Crypto.getRandomValues()`

使用密码学安全的随机数填充传入的 `TypedArray`。

`Crypto.randomUUID()`

返回一个随机生成的，长度为 36 字符的第四版 UUID。

使用说明
----

即使不安全的上下文中存在 `Crypto` 接口（即 `crypto` 属性），你也应该避免在不安全的上下文中使用 Web Crypto API。`Crypto` 的 `getRandomValues()` 方法在不安全的上下文中可用，而 `subtle` 属性则不可用。

通常，你应该将 `Crypto` 视为仅在安全上下文中可用。

规范
--

| Specification |
| --- |
| Web Cryptography API # crypto-interface |

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

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

参见
--

* Web 安全
* 安全上下文
* 仅限于安全上下文的特性
* 传输层安全
* Strict-Transport-Security


ConvolverNode - Web API 接口参考

ConvolverNode
=============

`ConvolverNode` 接口是一个对给定 `AudioBuffer` 上执行线性卷积的 `AudioNode`，一般用来做音频混响效果。每一个 `ConvolverNode` 都会有一个输入值和输出值。

**备注：** 更多线性卷积理论的相关信息，请参阅Convolution article on Wikipedia.

|  |  |
| --- | --- |
| Number of inputs | `1` |
| Number of outputs | `1` |
| Channel count mode | `"clamped-max"` |
| Channel count | `1`, `2`, or `4` |
| Channel interpretation | `"speakers"` |

构造函数
----

`ConvolverNode()` (en-US)

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

属性
--

继承其父级的属性\*, `AudioNode`\*.

`ConvolverNode.buffer` (en-US)

一个被 `ConvolverNode` 用来产生混响效果的单声道、立体声或四声道的音频缓冲器，包含了 (可能是多声道) 脉冲反应 (IR)。

`ConvolverNode.normalize` (en-US)

布尔值，在设置缓冲区属性时，可绝定是否对来自 `buffer` 的脉冲反应按等功率归一化进行缩放。

方法
--

没有具体的方法，从其父继承方法，*`AudioNode`*.

ConvolverNode 例子
----------------

下面的示例展示了 AudioContext 创建卷积节点的基础用法。

**备注：** 你需要找到一个脉冲反应来完成下面的示例。可查看此处 的实例。

```js
let audioCtx = new window.AudioContext();

async function createReverb() {
    let convolver = audioCtx.createConvolver();

    // 从文件加载脉冲反应
    let response     = await fetch("path/to/impulse-response.wav");
    let arraybuffer  = await response.arrayBuffer();
    convolver.buffer = await audioCtx.decodeAudioData(arraybuffer);

    return convolver;
}

...

let reverb = await createReverb();

// someOtherAudioNode -> reverb -> destination
someOtherAudioNode.connect(reverb);
reverb.connect(audioCtx.destination);
```

规范
--

| Specification |
| --- |
| Web Audio API # ConvolverNode |

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

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

参见
--

* Using the Web Audio API (en-US)


HTMLSpanElement - Web API 接口参考

HTMLSpanElement
===============

The **`HTMLSpanElement`** interface represents a `<span>` element and derives from the `HTMLElement` interface, but without implementing any additional properties or methods.

属性
--

*无特定属性；从其父元素`HTMLElement`继承属性。*

方法
--

*无特定方法；从其父元素`HTMLElement`继承方法。*

规范
--

| Specification |
| --- |
| HTML Standard # htmlspanelement |

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

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

参见
--

* The HTML element implementing this interface: `<span>`.


Web Authentication API - Web API 接口参考

Web Authentication API
======================

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

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

Web Authentication API 继承自 Credential Management API ，使用公钥密码学使得验证更强壮，不需要 SMS 文本就能实现无密码验证和安全的双因素验证。

Web authentication 概念和用例
------------------------

Web Authentication API（也称作 WebAuthn）使用asymmetric (public-key) cryptography （非对称加密）替代密码或 SMS 短信在网站上注册、登录、second-factor authentication（双因素验证）。解决了 phishing（钓鱼）、data breaches（数据破坏）、SMS 文本攻击、其他双因素验证等重大安全问题，同时显著提高了易用性（因为用户不必管理许多越来越复杂的密码）。

许多网站已实现用户注册账号，登录已有账号的页面，WebAuthn 作为这些页面的替代和补充。类似其他形式的 Credential Management API（凭据管理 API)。Web Authentication API 有两个对应于注册和登录的基本方法：

* navigator.credentials.create() (en-US) - 当使用 publicKey 选项时，创建一个新的凭据，无论是用于注册新账号还是将新的非对称密钥凭据与已有的账号关联。
* navigator.credentials.get() (en-US) - 当使用 publicKey 选项时，使用一组现有的凭据进行身份验证服务，无论是用于用户登录还是双因素验证中的一步。

**请注意：** create() 和 get() 都需要在 Secure Context（安全上下文）中执行（例如 - 使用 https 连接，或是使用 localhost），当浏览器不是在安全环境下时它们将不可用。

在基础实现中，create() 和 get() 会从服务器接收一个大随机数，称为挑战。挑战将由私钥签名并返回给服务器。这可以服务器证明用户拥有身份验证所需要的私钥，与此同时没有任何密码在网络上被传输。

为了了解 create() 和 get() 方法在实际中的使用，我们需要理解它们位于浏览器之外的两个部分之间：

1. **服务器** - WebAuthn API 旨在在服务器（也称为服务或依赖方）上注册新的凭据，以供稍后在同一服务器上使用相同的凭据对用户进行身份验证。
2. **认证器** - 凭据将被创建并存储于被称为认证器的设备中。这是认证过程中的一个新概念：使用密码进行身份验证时，密码存储在用户的大脑中而不需要其他设备；使用 WebAuthn 进行身份验证时，密码则被存储在认证器中的密钥对替代。认证器可以被嵌入到操作系统中（例如 Windows Hello），也可以是 USB 或蓝牙安全密钥等物理令牌。
### 注册

一个典型的注册过程包括如图 1 所示的六个步骤，这些在稍后会进一步描述。这是一个注册过程的概览，所需数据已经被简化。所有的必填字段、可选字段及它们在创建注册请求中的含义可以在 `PublicKeyCredentialCreationOptions` (en-US) 字典中找到。类似地，完整的响应字段可以在 `PublicKeyCredential` (en-US) 接口（其中 `PublicKeyCredential.response` (en-US) 是 `AuthenticatorAttestationResponse` (en-US) 的接口）中找到。请注意大多数编写程序的 JavaScript 程序员只会关心第 1 步和第 5 步，分别对应 create() 函数的调用和返回。但是，了解步骤 2 到 4 对于理解在浏览器和认证器中发生了什么以及返回数据的含义至关重要。

![WebAuthn registration component and dataflow diagram](/zh-CN/docs/Web/API/Web_Authentication_API/webauthn_registration_r4.png)

*图 1 - WebAuthn 注册流程及与各个步骤相关的重要数据。*

注册步骤如下：

1. **应用程序请求注册** - 应用程序发出注册请求。这个请求的协议和格式不在 WebAuthn 标准的范围内。
2. **服务器发送挑战、用户信息和依赖方信息** - 服务器将挑战、用户信息和依赖方信息发送回应用程序。在这里，协议和格式不在 WebAuthn 标准的范围内。通常，这可以是基于 HTTPS 连接的 REST（可能会使用 XMLHttpRequest 或 Fetch）API。不过只要在安全连接中，也可以使用 SOAP (en-US)、RFC 2549 或几乎任何其他协议。从服务器接收到的参数将传递给 create() (en-US) ，大部分情况下只需很少修改甚至不需要做任何修改。create() 会返回一个Promise，并返回包含 `AuthenticatorAttestationResponse` (en-US) 的 `PublicKeyCredential` (en-US)。**需要注意的是挑战必须是随机的 buffer（至少 16 字节），并且必须在服务器上生成以确保安全。**
3. **浏览器向认证器调用 authenticatorMakeCredential()** - 在浏览器内部，浏览器将验证参数并用默认值补全缺少的参数，然后这些参数会变为 `AuthenticatorResponse.clientDataJSON` (en-US)。其中最重要的参数之一是 origin，它是 clientData 的一部分，同时服务器将能在稍后验证它。调用 create() 的参数与 clientDataJSON 的 SHA-256 哈希一起传递到身份验证器（只有哈希被发送是因为与认证器的连接可能是低带宽的 NFC 或蓝牙连接，之后认证器只需对哈希签名以确保它不会被篡改）。
4. **认证器创建新的密钥对和证明** - 在进行下一步之前，认证器通常会以某种形式要求用户确认，如输入 PIN，使用指纹，进行虹膜扫描等，以证明用户在场并同意注册。之后，认证器将创建一个新的非对称密钥对，并安全地存储私钥以供将来验证使用。公钥则将成为证明的一部分，被在制作过程中烧录于认证器内的私钥进行签名。这个私钥会具有可以被验证的证书链。
5. **认证器将数据返回浏览器** - 新的公钥、全局唯一的凭证 ID 和其他的证明数据会被返回到浏览器，成为 attestationObject。
6. **浏览器生成最终的数据，应用程序将响应发送到服务器** - create() 的 Promise 会返回一个 `PublicKeyCredential` (en-US)，其中包含全局唯一的证书 ID `PublicKeyCredential.rawId` (en-US) 和包含 `AuthenticatorResponse.clientDataJSON` (en-US) 的响应 `AuthenticatorAttestationResponse` (en-US)。你可以使用任何你喜欢的格式和协议将 `PublicKeyCredential` (en-US) 发送回服务器（注意 ArrayBuffer 类型的属性需要使用 base64 或类似编码方式进行编码）
7. **服务器验证数据并完成注册** - 最后，服务器需要执行一系列检查以确保注册完成且数据未被篡改。步骤包括：
    1. 验证接收到的挑战与发送的挑战相同
    2. 确保 origin 与预期的一致
    3. 使用对应认证器型号的证书链验证 clientDataHash 的签名和证明验证步骤的完整列表可以在 WebAuthn 规范中找到。一旦验证成功，服务器将会把新的公钥与用户帐户相关联以供将来用户希望使用公钥进行身份验证时使用。
### 验证

用户在 WebAuthn 中注册完成之后就可以使用 WebAuthn 进行身份验证（或者说登录）。验证流程与注册相似，图 2 所示的验证流程也与图 1 相似。不过，注册和验证之间的主要区别在于：1) 验证不需要用户或信赖方信息；2) 验证使用之前生成的密钥对创建一个断言，而不是使用在认证器在制造过程中烧录的密钥对创建证明。和上文一样，下面的验证流程图只是一个概况，并非详细描述。验证所需的数据可以在 `PublicKeyCredentialRequestOptions` 字典中找到；返回的数据可以在 `PublicKeyCredential` (en-US) 接口（其中 `PublicKeyCredential.response` (en-US) 是 `AuthenticatorAssertionResponse` (en-US) 的接口）中找到。

![WebAuthn authentication component and dataflow diagram](/zh-CN/docs/Web/API/Web_Authentication_API/mdn_webauthn_authentication_r1.png)

*图 2 - WebAuthn 验证流程及与各个步骤相关的重要数据。*

1. **Application Requests Authentication** - The application makes the initial authentication request. The protocol and format of this request is outside of the scope of WebAuthn.
2. **Server Sends Challenge** - The server sends a challenge JavaScript program. The protocol for communicating with the server is not specified and is outside of the scope of WebAuthn. Typically, server communications would be REST over https (probably using XMLHttpRequest or Fetch), but they could also be SOAP (en-US), RFC 2549 or nearly any other protocol provided that the protocol is secure. The parameters received from the server will be passed to the get() (en-US) call, typically with little or no modification. **Note that it is absolutely critical that the challenge be a large buffer of random information (e.g. - more than 100 bytes) and it MUST be generated on the server in order to ensure the security of the authentication process.**
3. **Browser Call authenticatorGetCredential() on Authenticator** - Internally, the browser will validate the parameters and fill in any defaults, which become the `AuthenticatorResponse.clientDataJSON` (en-US). One of the most important parameters is the origin, which recorded as part of the clientData so that the origin can be verified by the server later. The parameters to the create() call are passed to the authenticator, along with a SHA-256 hash of the clientDataJSON (only a hash is sent because the link to the authenticator may be a low-bandwidth NFC or Bluetooth link and the authenticator is just going to sign over the hash to ensure that it isn't tampered with).
4. **Authenticator Creates an Assertion** - The authenticator finds a credential for this service that matches the Relying Party ID and prompts a user to consent to the authentication. Assuming both of those steps are successful, the authenticator will create a new assertion by signing over the clientDataHash and authenticatorData with the private key generated for this account during the registration call.
5. **Authenticator Returns Data to Browser** - The authenticator returns the authenticatorData and assertion signature back to the browser.
6. **Browser Creates Final Data, Application sends response to Server** - The browser resolves the Promise to a `PublicKeyCredential` (en-US) with a `PublicKeyCredential.response` (en-US) that contains the `AuthenticatorAssertionResponse` (en-US). It is up to the JavaScript application to transmit this data back to the server using any protocol and format of its choice.
7. **Server Validates and Finalizes Authentication** - Upon receiving the result of the authentication request, the server performs validation of the response such as:
    1. Using the public key that was stored during the registration request to validate the signature by the authenticator.
    2. Ensuring that the challenge that was signed by the authenticator matches the challenge that was generated by the server.
    3. Checking that the Relying Party ID is the one expected for this service.A full list of the steps for validating an assertion can be found in the WebAuthn specification. Assuming the validation is successful, the server will note that the user is now authenticated. This is outside the scope of the WebAuthn specification, but one option would be to drop a new cookie for the user session.
Interfaces
----------

`CredentialsContainer`

WebAuthn extends the Credential Management API's create() (en-US) and get() (en-US) methods to take a new option: publicKey. When the publicKey option is passed to create() and / or get(), the Credential Management API will create a new public key pair or get an authentication for a key pair, respectively.

`PublicKeyCredential` (en-US)

A credential for logging in to a service using an un-phishable and data-breach resistant asymmetric key pair instead of a password.

`AuthenticatorResponse` (en-US)

Part of the PublicKeyCredential, the AuthenticatorResponse includes information from the browser (such as the challenge and origin); as well as information from the authenticator such as an AuthenticatorAttestationResponse (for new credentials) or an AuthenticatorAssertionResponse (when authenticating with existing credentials).

`AuthenticatorAttestationResponse` (en-US)

When a PublicKeyCredential has been created with the create() (en-US) call, it will include an AuthenticatorAttestationResponse. This is the authenticator's way of providing a cryptographic root of trust for the new key pair that has been generated.

`AuthenticatorAssertionResponse` (en-US)

When a PublicKeyCredential is the result of a get() (en-US) call, it will include an AuthenticatorAssertionResponse. This is the authenticator's way of proving to a service that it has the key pair and that the authentication request is valid and approved.

Options
-------

`PublicKeyCredentialCreationOptions` (en-US)

The options for creating a credential via navigator.credentials.create() (en-US)

`PublicKeyCredentialRequestOptions`

The options for using a credential via navigator.credentials.get() (en-US)

Examples
--------

Note: as a security feature, any WebAuthn calls (i.e. - create() or get() ) will be cancelled if the browser window loses focus while the call is pending.

```js
// sample arguments for registration
var createCredentialDefaultArgs = {
  publicKey: {
    // Relying Party (a.k.a. - Service):
    rp: {
      name: "Acme",
    },

    // User:
    user: {
      id: new Uint8Array(16),
      name: "john.p.smith@example.com",
      displayName: "John P. Smith",
    },

    pubKeyCredParams: [
      {
        type: "public-key",
        alg: -7,
      },
    ],

    attestation: "direct",

    timeout: 60000,

    challenge: new Uint8Array([
      // must be a cryptographically random number sent from a server
      0x8c, 0x0a, 0x26, 0xff, 0x22, 0x91, 0xc1, 0xe9, 0xb9, 0x4e, 0x2e, 0x17, 0x1a,
      0x98, 0x6a, 0x73, 0x71, 0x9d, 0x43, 0x48, 0xd5, 0xa7, 0x6a, 0x15, 0x7e, 0x38,
      0x94, 0x52, 0x77, 0x97, 0x0f, 0xef,
    ]).buffer,
  },
};

// sample arguments for login
var getCredentialDefaultArgs = {
  publicKey: {
    timeout: 60000,
    // allowCredentials: [newCredential] // see below
    challenge: new Uint8Array([
      // must be a cryptographically random number sent from a server
      0x79, 0x50, 0x68, 0x71, 0xda, 0xee, 0xee, 0xb9, 0x94, 0xc3, 0xc2, 0x15, 0x67,
      0x65, 0x26, 0x22, 0xe3, 0xf3, 0xab, 0x3b, 0x78, 0x2e, 0xd5, 0x6f, 0x81, 0x26,
      0xe2, 0xa6, 0x01, 0x7d, 0x74, 0x50,
    ]).buffer,
  },
};

// register / create a new credential
navigator.credentials
  .create(createCredentialDefaultArgs)
  .then((cred) => {
    console.log("NEW CREDENTIAL", cred);

    // normally the credential IDs available for an account would come from a server
    // but we can just copy them from above...
    var idList = [
      {
        id: cred.rawId,
        transports: ["usb", "nfc", "ble"],
        type: "public-key",
      },
    ];
    getCredentialDefaultArgs.publicKey.allowCredentials = idList;
    return navigator.credentials.get(getCredentialDefaultArgs);
  })
  .then((assertion) => {
    console.log("ASSERTION", assertion);
  })
  .catch((err) => {
    console.log("ERROR", err);
  });
```

* Mozilla Demo website and its source code.
* Google Demo website and its source code.
* webauthn.org and its client source code and server source code
规范
--

| Specification |
| --- |
| Web Authentication: An API for accessing Public Key Credentials - Level 3 # iface-pkcredential |

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

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

参见
--

* WebAuthentication and WebPayment demo on an Android device


BroadcastChannel - Web API 接口参考

BroadcastChannel
================

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
**`BroadcastChannel`** 接口代理了一个命名频道，可以让指定 origin 下的任意 browsing context 来订阅它。它允许同源的不同浏览器窗口，Tab 页，frame 或者 iframe 下的不同文档之间相互通信。通过触发一个 `message` 事件，消息可以广播到所有监听了该频道的 `BroadcastChannel` 对象。

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

构造函数
----

`BroadcastChannel()`

创建一个链接到命名频道的对象。

属性
--

*该接口会从它的父级 `EventTarget` 继承属性。*

`BroadcastChannel.name`

频道名称，返回 `DOMString`。

### 事件处理程序

`BroadcastChannel.onmessage`

事件处理器，用于定义当该对象上触发了 `message` 事件时要执行的函数。

`BroadcastChannel.onmessageerror`

事件处理器，用于定义当该对象上触发了类型为 `MessageError` 的 `MessageEvent` 事件时要执行的函数。当接收到一条无法反序列化的消息时会触发此事件。

方法
--

*该接口会从它的父级 `EventTarget` 继承方法。*

`BroadcastChannel.postMessage()`

向所有监听了相同频道的 `BroadcastChannel` 对象发送一条消息，消息内容可以是任意类型的数据。

`BroadcastChannel.close()`

关闭频道对象，告诉它不要再接收新的消息，并允许它最终被垃圾回收。

事件
--

`message`

 当频道收到一条消息时触发。
 也可以使用 `onmessage` 属性访问。

`messageerror`

 当频道收到一条无法反序列化的消息时触发。
 也可以使用 `onmessageerror` 属性访问。

规范
--

| Specification |
| --- |
| HTML Standard # broadcasting-to-other-browsing-contexts |

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

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

另见
--

* 一种在不同浏览器上下文之间通信的重量级方案：`ServiceWorker`。
* Broadcast Channel API overview


VisualViewport - Web API 接口参考

VisualViewport
==============

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

Visual Viewport API (en-US) 提供了当前页面的视觉视口接口，即 **`VisualViewport`** 。对于每个页面容器来说（如 iframe），都存在有一个独立的 window 对象。每个页面容器的 window 对象都有一个独立的 `VisualViewport` 属性。

你可以使用 `Window.visualViewport` 获得对应 window 的视觉视口 API。

**备注：** 与布局视口（layout viewport）不同的是：只有最上层的 window 才有视觉视口（visual viewport）这一概念。因此只有最上层 window 的 `VisualViewport` 属性才是有效的，其他层的视觉视口属性可看作是布局视口属性的别名。比如，对于一个 `<iframe>` ，其对应的视觉视口属性 `VisualViewport.width` (en-US) 相当于对应的布局视口属性，如 `document.documentElement.clientWidth`.

属性
--

*`VisualViewport`* 从其父元素继承属性 *`EventTarget`*。

`VisualViewport.offsetLeft` (en-US) 只读

返回视觉视口的左边框到布局视口的左边框的 CSS 像素距离。

`VisualViewport.offsetTop` 只读

返回视觉视口的上边框到布局视口的上边框的 CSS 像素距离。

`VisualViewport.pageLeft` (en-US) 只读

返回相对于初始的 viewport 属性的 X 轴坐标所对应的 CSS 像素数。

`VisualViewport.pageTop` (en-US) 只读

返回相对于初始的 viewport 属性的 Y 轴坐标所对应的 CSS 像素数。

`VisualViewport.width` (en-US) 只读

返回视觉视口的宽度所对应的 CSS 像素数。

`VisualViewport.height` (en-US) 只读

返回视觉视口的高度所对应的 CSS 像素数。

`VisualViewport.scale` (en-US) 只读

返回当前视觉视口所应用的缩放比例。

Events
------

通过使用 `addEventListener()` 或者将监听回调函数赋值给对应的 `oneventname` 属性，可以为对应的视口事件添加监听。

`resize` (en-US)

 当视觉视口被改变时触发。
 也可以为 `VisualViewport.onresize` (en-US) 属性赋值来添加监听。

`scroll` (en-US)

 当视觉视口滑动时触发。
 也可以为 `VisualViewport.onscroll` (en-US) 属性赋值来添加监听。

例子
--

### 缩放检测并隐藏元素

这个例子取自 Visual Viewport README，展示了如何在用户缩放时隐藏某个盒子（或元素）。这对于增强一个页面在缩放时的用户体验有重要意义。同样，你也可以查看另一个 例子 。

```js
var bottomBar = document.getElementById("bottombar");
var viewport = window.visualViewport;

function resizeHandler() {
  if (viewport.scale > 1.3) bottomBar.style.display = "none";
  else bottomBar.style.display = "block";
}

window.visualViewport.addEventListener("resize", resizeHandler);
```

### 模拟 position 属性：device-fixed

这个例子同样取自 Visual Viewport README ，展示了如何使用视觉视口 API，从而模拟 `position: device-fixed` 的 CSS 属性。类似于 `position: fixed` ，这一属性可将被设置的元素固定在视觉视口特定位置。此外，你也可以查看另一个 例子 。

```js
var bottomBar = document.getElementById("bottombar");
var viewport = window.visualViewport;
function viewportHandler() {
  var layoutViewport = document.getElementById("layoutViewport");

  // Since the bar is position: fixed we need to offset it by the visual
  // viewport's offset from the layout viewport origin.
  var offsetLeft = viewport.offsetLeft;
  var offsetTop =
    viewport.height -
    layoutViewport.getBoundingClientRect().height +
    viewport.offsetTop;

  // You could also do this by setting style.left and style.top if you
  // use width: 100% instead.
  bottomBar.style.transform =
    "translate(" +
    offsetLeft +
    "px," +
    offsetTop +
    "px) " +
    "scale(" +
    1 / viewport.scale +
    ")";
}
window.visualViewport.addEventListener("scroll", viewportHandler);
window.visualViewport.addEventListener("resize", viewportHandler);
```

**备注：** 应小心使用上述方案，使用这种方式模拟的 `position: device-fixed` 可能会导致其他元素在滚动页面时出现闪烁。

规范
--

| Specification |
| --- |
| CSSOM View Module # the-visualviewport-interface |

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

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

参照
--

* Web 视口说明 — 解释了什么是浏览器视口和视觉视口和布局视口的区别。


Web Speech API - Web API 接口参考

Web Speech API
==============

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

Web Speech API 使你能够将语音数据合并到 Web 应用程序中。Web Speech API 有两个部分：SpeechSynthesis 语音合成（文本到语音 TTS）和 SpeechRecognition 语音识别（异步语音识别）。

Web Speech 的概念及用法
-----------------

Web Speech API 使 Web 应用能够处理语音数据，该项 API 包含以下两个部分：

* 语音识别通过 `SpeechRecognition` (en-US) 接口进行访问，它提供了识别从音频输入（通常是设备默认的语音识别服务）中识别语音情景的能力。一般来说，你将使用该接口的构造函数来构造一个新的 `SpeechRecognition` (en-US) 对象，该对象包含了一系列有效的对象处理函数来检测识别设备麦克风中的语音输入。`SpeechGrammar` 接口则表示了你应用中想要识别的特定文法。文法则通过 JSpeech Grammar Format (**JSGF**.) 来定义。
* 语音合成通过 `SpeechSynthesis` 接口进行访问，它提供了文字到语音（TTS）的能力，这使得程序能够读出它们的文字内容（通常使用设备默认的语音合成器）。不同的声音类类型通过 `SpeechSynthesisVoice` (en-US) 对象进行表示，不同部分的文字则由 `SpeechSynthesisUtterance` (en-US) 对象来表示。你可以将它们传递给 `SpeechSynthesis.speak()` (en-US) 方法来产生语音。

更多关于这些特性的细节请参考 Using the Web Speech API。

Web Speech 的 API 接口
-------------------

### 语音识别

`SpeechRecognition` (en-US)

语音识别服务的控制器接口；它也处理由语音识别服务发来的 `SpeechRecognitionEvent` (en-US) 事件。

`SpeechRecognitionAlternative` (en-US)

表示由语音识别服务识别出的一个词汇。

`SpeechRecognitionError` (en-US)

表示语音识别服务发出的报错信息。

`SpeechRecognitionEvent` (en-US)

`result` (en-US) 和 `nomatch` (en-US) 的事件对象，包含了与语音识别过程中间或最终结果相关的全部数据。

`SpeechGrammar`

我们将要交由语音识别服务进行识别的词汇或者词汇的模式。

`SpeechGrammarList` (en-US)

表示一个由 `SpeechGrammar` 对象构成的列表。

`SpeechRecognitionResult` (en-US)

表示一次识别中的匹配项，其中可能包含多个 `SpeechRecognitionAlternative` (en-US) 对象。

`SpeechRecognitionResultList` (en-US)

表示包含 `SpeechRecognitionResult` (en-US) 对象的一个列表，如果是以 `continuous` (en-US) 模式捕获的结果，则是单个对象。

### 语音合成

`SpeechSynthesis`

语音合成服务的控制器接口，可用于获取设备上可用的合成语音，开始、暂停以及其他相关命令的信息。

`SpeechSynthesisErrorEvent` (en-US)

包含了在发音服务处理 `SpeechSynthesisUtterance` (en-US) 对象过程中的信息及报错信息。

`SpeechSynthesisEvent` (en-US)

包含了经由发音服务处理过的 `SpeechSynthesisUtterance` (en-US) 对象当前状态的信息。

`SpeechSynthesisUtterance` (en-US)

表示一次发音请求。其中包含了将由语音服务朗读的内容，以及如何朗读它（例如：语种、音高、音量）。

`SpeechSynthesisVoice` (en-US)

表示系统提供的一个声音。每个 `SpeechSynthesisVoice` 都有与之相关的发音服务，包括了语种、名称 和 URI 等信息。

`Window.speechSynthesis` (en-US)

由规格文档指定的，被称为 `SpeechSynthesisGetter` 的 `[NoInterfaceObject]` 接口的一部分，在 `Window` 对象中实现，`speechSynthesis` 属性可用于访问 `SpeechSynthesis` 控制器，从而获取语音合成功能的入口。

示例
--

GitHub 上的 Web Speech API repo 的示例程序展示了语音识别及合成。

规范
--

| Specification |
| --- |
| Web Speech API # speechreco-section |
| Web Speech API # tts-section |

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

### api.SpeechRecognition

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

### api.SpeechSynthesis

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

相关链接
----

* Using the Web Speech API
* SitePoint article
* HTML5Rocks article
* Demo [aurelio.audero.it]


画中画（Picture-in-Picture）API - Web API 接口参考

画中画（Picture-in-Picture）API
==========================

**画中画 API** 允许网站总是在其他窗口之上创建一个浮动的视频，以便用户在其他内容站点或者设备上的应用程序交互时可以继续播放媒体。

接口
--

`PictureInPictureWindow`

表示浮动的视频窗口；包含 `width` (en-US) 和 `height` (en-US) 属性，以及一个 `onresize` (en-US) 事件处理器属性。

方法
--

画中画 API 添加了 `HTMLVideoElement` 和 `Document` 接口的方法，以便允许切换浮动视频窗口。

### HTMLVideoElement 接口的方法

`HTMLVideoElement.requestPictureInPicture()`

请求用户代理将视频切换为画中画模式。

### Document 接口的方法

`Document.exitPictureInPicture()`

请求用户代理将元素由画中画模式切换回到它的原始盒子。

属性
--

*画中画 API 添加了* `HTMLVideoElement`、`Document` 和 `ShadowRoot` 接口的属性，这些属性用于决定浮动的视频窗口是否是受支持和可用的、当前画中画模式是否处于激活状态并且哪个视频是浮动的。

### HTMLVideoElement 接口的属性

`HTMLVideoElement.disablePictureInPicture`

`disablePictureInPicture` 属性将指示用户代理是否应该向用户建议画中画的功能。

### Document 接口的属性

`Document.pictureInPictureEnabled`

`pictureInPictureEnabled` 属性告诉你是否可以使用画中画模式。如果画中画模式因任何原因不可用（例如`"画中画"`功能 不被接受，或者不支持画中画模式），则是 `false` 。

### Document 或 ShadowRoot 接口的属性

`Document.pictureInPictureElement` / `ShadowRoot.pictureInPictureElement` (en-US)

`pictureInPictureElement` 属性告诉你当前在浮动窗口（或影子 DOM）显示哪个 `Element`。如果为 `null`，则此文档（或影子 DOM）没有节点处于画中画模式。

事件
--

*画中画 API 定义了三个事件，它们可以用来检测画中画模式何时被切换或者浮动窗口大小何时被调整。*

`enterpictureinpicture`

当 `HTMLVideoElement` 进入画中画模式时触发该事件。

`leavepictureinpicture`

当 `HTMLVideoElement` 离开画中画模式时触发该事件。

`resize` (en-US)

当 `PictureInPictureWindow` 大小改变时触发该事件。

控制样式
----

CSS 伪类 `:picture-in-picture` 匹配当前进入画中画模式的视频元素，并允许你配置样式表，以便视频在画中画或者传统播放模式来回切换时自动调整内容的大小、样式或布局。

控制访问权限
------

可以使用 Feature Policy 控制画中画的可用性。全屏模式的功能由字符串 `"picture-in-picture"` 标识，默认的允许列表的值是 `"self"`，意味着在顶级文档上下文以及从最顶层文档相同的来源加载的嵌套浏览上下文中允许画中画模式。

参见使用 Feature Policy，了解关于使用 Feature Policy 控制对 API 访问的更多信息。

示例
--

在此示例中，视频被展示在 web 页面。点击下面的按钮可以让用户切换浮动视频窗口。

### 切换画中画模式

当使用者点击“Toggle Picture-in-Picture”按钮时，这段代码将会由一个点击处理程序调用：

```js
function togglePictureInPicture() {
  if (document.pictureInPictureElement) {
    document.exitPictureInPicture();
  } else {
    if (document.pictureInPictureEnabled) {
      video.requestPictureInPicture();
    }
  }
}
```

该块首先会查询 `document` `pictureInPictureElement` 属性的值。

如果值不是 `null`，则它是当前处于画中画模式并在浮动窗口的元素。我们调用 `document.exitPictureInPicture()` 将视频带进它初始的盒子。

如果值是 `null`，浮动窗口没有视频。所以我们可以请求视频进入画中画模式。我们可以在 `<video>` 元素上调用 `HTMLVideoElement.requestPictureInPicture()` 来实现。

规范
--

| Specification |
| --- |
| Picture-in-Picture # interface-picture-in-picture-window |

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

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

参见
--

* `HTMLVideoElement.requestPictureInPicture()`
* `HTMLVideoElement.disablePictureInPicture`
* `Document.pictureInPictureEnabled`
* `Document.exitPictureInPicture()`
* `Document.pictureInPictureElement`
* `:picture-in-picture`


DOMStringList - Web API 接口参考

DOMStringList
=============

某些 API 会返回的包含一列DOMString的一种类型

Properties
----------

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

返回列表的长度，

Methods
-------

`DOMStringList.item()` (en-US)

返回一个 `DOMString`.

`DOMStringList.contains()` (en-US)

返回`Boolean` 类型的标示来表明此类型是否包含某字符串。

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

* http://www.w3.org/TR/DOM-Level-3-Cor...#DOMStringList


origin 全局属性 - Web API 接口参考

origin 全局属性
===========

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

**`origin`** 全局只读属性返回全局作用域的来源，序列化为一个字符串。

值
-

一个字符串。

示例
--

在 Worker 脚本中执行以下代码段，每次收到消息时，它都会将 Worker 全局作用域的来源记录到控制台中：

```js
onmessage = () => {
  console.log(self.origin);
};
```

如果来源不是协议/主机/端口元组（例如试图在本地，即通过 `file://` URL 运行脚本），`origin` 将返回字符串 `"null"`。

规范
--

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

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

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


ANGLE_instanced_arrays - Web API 接口参考

ANGLE\_instanced\_arrays
========================

`ANGLE_instanced_arrays`是属于 WebGL API 的一个扩展 API，它允许多次绘制相同的对象或相似对象组，前提是它们共享相同的顶点数据、基本图形的个数和类型。WebGL 的扩展都能使用`WebGLRenderingContext.getExtension()` 这个方法。更多详细信息，请参考 WebGL tutorial*（WebGL 使用教程）里的*Using Extensions *（使用扩展）*。

**备注：** 这个扩展仅仅能使用在 WebGL1 上下文中。在 WebGL2，默认情况下这个扩展的在 WebGL2 的上下文中起作用，它的常量以及方法使用过程中没有“ANGEL”后缀。

尽管名字叫“ANGLE”，只要硬件支持，它可以运行在任意设备上，而不仅是在 Windows 上起作用。 "ANGLE"只是表明了这个扩展是被 ANGLE 这个库的作者书写的，并没有更多的含义。

常量
--

这个扩展提供了一个新常量，它能被 `gl.getVertexAttrib()` (en-US) 这个方法所使用：

`ext.VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE`

当这个常量在`gl.getVertexAttrib()` (en-US)中作为 pname 参数使用时，将返回一个用于实例渲染的频率因子`GLint` (en-US)。

方法
--

这个扩展提供了三个新的方法。

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

作用与`gl.drawArrays()` 相同，除了元素范围的多实例的执行以及每次迭代时的实例扩展。

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

作用与`gl.drawElements()`相同，除了元素集中的多实例的计算以及每个集之间的实例扩展。

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

当用`ext.drawArraysInstancedANGLE()` (en-US)和`ext.drawElementsInstancedANGLE()` (en-US)渲染基本图元的多实例时，会提升通用的顶点属性的速度。

示例
--

启用扩展：

```js
var ext = gl.getExtension("ANGLE\_instanced\_arrays");
```

规范
--

| Specification |
| --- |
| WebGL ANGLE\_instanced\_arrays Khronos Ratified Extension Specification  |

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

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

参见
--

* `WebGLRenderingContext.getExtension()`
* `WebGL2RenderingContext.drawArraysInstanced()` (en-US)
* `WebGL2RenderingContext.drawElementsInstanced()` (en-US)
* `WebGL2RenderingContext.vertexAttribDivisor()` (en-US)


CDATASection - Web API 接口参考

CDATASection
============

**`CDATASection`** 接口用于表示 CDATA 片段（CDATA section）。在 XML 中，CDATA 可以直接包含未经转义的文本。比如 `<` 和 `&`，只要位于 CDATA 片段中，它们就不需要被转义，保持原样就可以了。

在 XML 中，一个 CDATA 片段格式如下：

```xml
<![CDATA[ … ]]>
```

例如：

```html
<foo>
  这是一个 CDATA 片段：<![CDATA[ < > & ]]> 其中包含了一些没有转义的字符。
</foo>
```

唯一的例外就是，在一个 CDATA 片段中不可以使用 CDATA 片段本身的闭合标签片段：

```xml
<![CDATA[ ]]> 会引发错误   ]]>
```

注意，CDATA 片段不应该在 HTML 中被使用；它只在 XML 中有效。

属性
--

这个接口没有特有的属性，但实现了父接口 *`Text` (en-US)* 的属性。

方法
--

这个接口没有特有的方法，但实现了父接口 *`Text` (en-US)* 的方法。

规范
--

| Specification |
| --- |
| DOM Standard # interface-cdatasection |

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

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


WebSocket - Web API 接口参考

WebSocket
=========

`WebSocket` 对象提供了用于创建和管理 WebSocket 连接，以及可以通过该连接发送和接收数据的 API。

使用 `WebSocket()` 构造函数来构造一个 `WebSocket`。

构造函数
----

`WebSocket(url[, protocols])`

返回一个 `WebSocket` 对象。

常量
--

| **Constant** | **Value** |
| --- | --- |
| `WebSocket.CONNECTING` | `0` |
| `WebSocket.OPEN` | `1` |
| `WebSocket.CLOSING` | `2` |
| `WebSocket.CLOSED` | `3` |

属性
--

`WebSocket.binaryType`

使用二进制的数据类型连接。

`WebSocket.bufferedAmount` 只读

未发送至服务器的字节数。

`WebSocket.extensions` 只读

服务器选择的扩展。

`WebSocket.onclose`

用于指定连接关闭后的回调函数。

`WebSocket.onerror`

用于指定连接失败后的回调函数。

`WebSocket.onmessage`

用于指定当从服务器接受到信息时的回调函数。

`WebSocket.onopen`

用于指定连接成功后的回调函数。

`WebSocket.protocol` 只读

服务器选择的下属协议。

`WebSocket.readyState` 只读

当前的链接状态。

`WebSocket.url` 只读

WebSocket 的绝对路径。

方法
--

`WebSocket.close([code[, reason]])`

关闭当前链接。

`WebSocket.send(data)`

对要传输的数据进行排队。

事件
--

使用 `addEventListener()` 或将一个事件监听器赋值给本接口的 `oneventname` 属性，来监听下面的事件。

`close`

 当一个 `WebSocket` 连接被关闭时触发。
 也可以通过 `onclose` 属性来设置。

`error`

 当一个 `WebSocket` 连接因错误而关闭时触发，例如无法发送数据时。
 也可以通过 `onerror` 属性来设置。

`message`

 当通过 `WebSocket` 收到数据时触发。
 也可以通过 `onmessage` 属性来设置。

`open`

 当一个 `WebSocket` 连接成功时触发。
 也可以通过 `onopen` 属性来设置。

示例
--

```js
// Create WebSocket connection.
const socket = new WebSocket("ws://localhost:8080");

// Connection opened
socket.addEventListener("open", function (event) {
  socket.send("Hello Server!");
});

// Listen for messages
socket.addEventListener("message", function (event) {
  console.log("Message from server ", event.data);
});
```

规范
--

| Specification |
| --- |
| WebSockets Standard # the-websocket-interface |

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

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

参见
--

* Writing WebSocket client applications


DataTransfer - Web API 接口参考

DataTransfer
============

`DataTransfer` 对象用于保存拖动并放下（drag and drop）过程中的数据。它可以保存一项或多项数据，这些数据项可以是一种或者多种数据类型。关于拖放的更多信息，请参见 Drag and Drop.

这个对象可以从所有拖动事件 `drag events` 的 `dataTransfer` 属性上获取。

构造函数
----

`DataTransfer()`

生成并且返回一个新的 `DataTransfer` 对象。

属性
--

### 标准属性

`DataTransfer.dropEffect`

获取当前选定的拖放操作类型或者设置的为一个新的类型。值必须为 `none`, `copy`, `link` 或 `move`。

`DataTransfer.effectAllowed`

提供所有可用的操作类型。必须是 `none`, `copy`, `copyLink`, `copyMove`, `link`, `linkMove`, `move`, `all` or `uninitialized` 之一。

`DataTransfer.files`

包含数据传输中可用的所有本地文件的列表。如果拖动操作不涉及拖动文件，则此属性为空列表。

`DataTransfer.items` 只读

提供一个包含所有拖动数据列表的 `DataTransferItemList` 对象。

`DataTransfer.types` 只读

一个提供 `dragstart` 事件中设置的格式的 `strings` 数组。

### Gecko 属性

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

**备注：** 本节中的所有属性为 Gecko 特有。

`DataTransfer.mozCursor`

给出拖动光标的状态。这主要用于在拖动期间控制光标。

`DataTransfer.mozSourceNode` 只读

按下鼠标按钮按下启动拖动操作时鼠标光标所在的 `Node` 。对于外部拖动或调用方无法访问节点，此值为 `null` 。

`DataTransfer.mozUserCancelled` 只读

此属性仅适用于 `dragend` 事件，如果通过用户按下 escape 取消拖动操作，则为 `true` 。在所有其他情况下，这将为 `false` ，包括由于其他原因（如，放置在无效位置）导致的拖动失败。

### 不推荐的属性

`DataTransfer.mozItemCount` 只读
已弃用

提供拖动操作中的项目数。在 Firefox71 中删除。

方法
--

### 标准方法

`DataTransfer.clearData()`

删除与给定类型关联的数据。类型参数是可选的。如果类型为空或未指定，则删除与所有类型关联的数据。如果指定类型的数据不存在，或者 data transfer 中不包含任何数据，则该方法不会产生任何效果。

`DataTransfer.getData()`

检索给定类型的数据，如果该类型的数据不存在或 data transfer 不包含数据，则返回空字符串。

`DataTransfer.setData()`

设置给定类型的数据。如果该类型的数据不存在，则将其添加到末尾，以便类型列表中的最后一项将是新的格式。如果该类型的数据已经存在，则在相同位置替换现有数据。

`DataTransfer.setDragImage()`

用于设置自定义的拖动图像。

### Gecko 方法

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

**备注：** 本节所有方法为 Gecko 专有。

`DataTransfer.addElement()` (en-US)

Sets the drag source to the given element.

### 不推荐的方法

`DataTransfer.mozClearDataAt()`
已弃用

Removes the data associated with the given format for an item at the specified index. The index is in the range from zero to the number of items minus one. Removed in Firefox 71.

`DataTransfer.mozGetDataAt()`
已弃用

Retrieves the data associated with the given format for an item at the specified index, or null if it does not exist. The index should be in the range from zero to the number of items minus one. Removed in Firefox 71.

`DataTransfer.mozSetDataAt()`
已弃用

A data transfer may store multiple items, each at a given zero-based index. `mozSetDataAt()` may only be called with an index argument less than `mozItemCount` in which case an existing item is modified, or equal to `mozItemCount` in which case a new item is added, and the `mozItemCount` is incremented by one. Removed in Firefox 71.

`DataTransfer.mozTypesAt()`
已弃用

Holds a list of the format types of the data that is stored for an item at the specified index. If the index is not in the range from 0 to the number of items minus one, an empty string list is returned. Removed in Firefox 71.

示例
--

本文档中的每个方法和属性都有自己的参考页面，每个参考页面中都直接包含了接口的示例或给出了示例的链接。

规范
--

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

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

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

参见
--

* 拖与放
* 拖动操作
* 推荐拖动类型
* DataTransfer 测试 - 粘贴、拖放


HTMLSlotElement - Web API 接口参考

HTMLSlotElement
===============

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

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

Shadow DOM API 的接口 HTMLSlotElement 使其能够访问到 HTML 元素 <slot> 的名字和分配的节点

属性
--

`HTMLSlotElement.name`

`DOMString`: 可以用来设置和获取 slot 的名字

方法
--

`HTMLSlotElement.assignedNodes()` (en-US)

Returns the sequence of elements assigned to this slot, or alternatively the slot's fallback content.

规范
--

| Specification |
| --- |
| HTML Standard # htmlslotelement |

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

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


文件与目录条目 API - Web API 接口参考

文件与目录条目 API
===========

文件与目录条目（File and Directory Entries）API 模拟一个 web 应用可以导航和访问的本地文件系统。你可以在虚拟的沙箱文件系统中开发一个读、写、创建文件或者目录的应用。

访问文件系统
------

有两种方法可以访问当前规范草案中定义的文件系统：

* 当处理用于拖放的 `drop` 事件时，你可以调用 `DataTransferItem.webkitGetAsEntry()` 来为被放置（dropped）的项获取 `FileSystemEntry` (en-US)。如果结果不是 `null`，那么它就是一个被放置的文件或目录，你可以使用文件系统调用来处理它。
* `HTMLInputElement.webkitEntries` (en-US) 属性允许你访问当前选定文件的 `FileSystemFileEntry` 对象，但前提是将它们拖放到文件选择器（Firefox bug 1326031）。如果 `HTMLInputElement.webkitdirectory` 为真，则 `<input>` 元素是一个目录选择器，你将得到表示每个选择的目录的 `FileSystemDirectoryEntry` 对象。
接口
--

文件与目录条目 API 包含以下接口：

`FileSystem`

表示文件系统。

`FileSystemEntry` (en-US)

表示文件系统中单个条目的基本接口。这是由表示文件或目录的其他接口实现的。

`FileSystemFileEntry`

表示文件系统中的单个文件。

`FileSystemDirectoryEntry`

表示文件系统中的单个目录。

`FileSystemDirectoryReader` (en-US)

该接口通过调用 `FileSystemDirectoryEntry.createReader()` (en-US) 创建，提供了允许读取目录内容的功能。

规范
--

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

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

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

参见
--

* 介绍文件与目录条目 API
* Firefox 中的文件与目录条目 API 支持


DocumentType - Web API 接口参考

DocumentType
============

**`DocumentType`** 接口表示了一个包含文档类型的节点 `Node` .

EventTarget

Node

DocumentType属性
--

*继承自父节点 `Node`, 并实现了 `ChildNode` 接口。*

`DocumentType.entities` 只读
已弃用

一个在文档类型定义 (DTD) 中声明的实体`NamedNodeMap`，在这个映射（map）中的每个节点实现了`Entity`接口

`DocumentType.internalSubset` 只读
已弃用

一个表示内部子集的`DOMString`，如果没有的话则为`null` ，例：`"<!ELEMENT foo (bar)>"`

`DocumentType.name` (en-US) 只读

`DOMString`，文档类型的名称，例：`<!DOCTYPE HTML>`中的“`html`”

`DocumentType.notations` 只读
已弃用

在文档类型定义（DTD）中声明符号的`NamedNodeMap`，在这个映射（map）中的所有节点实现了`Notation`接口

`DocumentType.publicId` (en-US) 只读

一个`DOMString`，例：HTML5 中的空字符串——`"-//W3C//DTD HTML 4.01//EN"`。

`DocumentType.systemId` (en-US) 只读

一个`DOMString`，例：HTML5 中的空字符串——`"http://www.w3.org/TR/html4/strict.dtd"`。

方法
--

*继承方法自父节点，`Node`, 并实现了 `ChildNode` 接口。*

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

从父节点的子节点的列表中移除这个对象。

规范
--

| Specification |
| --- |
| DOM Standard # interface-documenttype |

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

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

参见
--

* DOM 接口索引
* `Entity`
* `Notation`


StorageManager - Web API 接口参考

StorageManager
==============

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

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

Storage API的 **`StorageManager`** 接口提供了用于管理数据本地存储权限和估算可用存储空间的接口。你可以使用`navigator.storage` (en-US)或`WorkerNavigator.storage` (en-US)对此接口进行引用。

方法
--

`StorageManager.estimate()` 安全上下文

返回一个`StorageEstimate`对象，此对象包含为你的域名预留的存储空间总大小和你已经使用的存储空间大小。

`StorageManager.persist()` 安全上下文

如果你的 user agent 能够将你域名下的数据持久保存，那么将返回一个状态为 resolve 的`Promise`

`StorageManager.persisted()` 安全上下文

如果你的站点已经被授予可使用数据本地存储的权限，则返回一个状态为 resolve 的`Promise`

规范
--

| Specification |
| --- |
| Storage Standard # storagemanager |

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

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


FileSystemFileEntry - Web API 接口参考

FileSystemFileEntry
===================

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

文件系统 API 的 **`FileSystemFileEntry`** 接口表示文件系统中的文件。它提供了属性，描述文件的属性，以及 `file()` (en-US) 方法，它创建了可以用于读取文件的 `File` 对象。

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

属性
--

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

方法
--

`file()` (en-US)

创建新的 `File` 对象，它可以用于读取文件。

### 废弃的方法

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

创建新的 `FileWriter` 对象，它允许写入由文件系统条目表示的对象。

基本概念
----

为了向文件写入内容，通过调用 `createWriter()` (en-US) 创建 `FileWriter` 对象。为了读取文件，通过调用 `file()` (en-US)，获取表示其内容的 `File` 对象。

### 示例

下面的代码创建了一个空文件，叫做 `log.txt`（如果不存在的话），并使用文本 "Meow" 来填充。在成功的回调中，设置了事件处理器，来处理 `error` `error` 和 `writeend` 事件。通过创建 blob，向其追加文本，以及将 blob 传递给 `FileWriter.write()`，文本数据写入了文件。

```js
function onInitFs(fs) {
  fs.root.getFile(
    "log.txt",
    { create: true },
    function (fileEntry) {
      // Create a FileWriter object for our FileSystemFileEntry (log.txt).
      fileEntry.createWriter(function (fileWriter) {
        fileWriter.onwriteend = function (e) {
          console.log("Write completed.");
        };

        fileWriter.onerror = function (e) {
          console.log("Write failed: " + e.toString());
        };

        // Create a new Blob and write it to log.txt.
        var bb = new BlobBuilder();
        bb.append("Meow");

        fileWriter.write(bb.getBlob("text/plain"));
      }, errorHandler);
    },
    errorHandler,
  );
}

window.requestFileSystem(window.TEMPORARY, 1024 \* 1024, onInitFs, errorHandler);
```

规范
--

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

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

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

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

参见
--

* 文件和驱动器条目 API
* 文件系统 API 简介


FormData - Web API 接口参考

FormData
========

**`FormData`** 接口提供了一种表示表单数据的键值对 `key/value` 的构造方式，并且可以轻松的将数据通过`XMLHttpRequest.send()` 方法发送出去，本接口和此方法都相当简单直接。如果送出时的编码类型被设为 `"multipart/form-data"`，它会使用和表单一样的格式。

如果你想构建一个简单的`GET`请求，并且通过`<form>`的形式带有查询参数，可以将它直接传递给`URLSearchParams`。

实现了 `FormData` 接口的对象可以直接在`for...of`结构中使用，而不需要调用`entries()` : `for (var p of myFormData)` 的作用和 `for (var p of myFormData.entries())` 是相同的。

**备注：** 此特性可用于 Web Workers。

构造函数
----

`FormData()`

创建一个新的 `FormData` 对象。

方法
--

`FormData.append()`

向 `FormData` 中添加新的属性值，`FormData` 对应的属性值存在也不会覆盖原值，而是新增一个值，如果属性不存在则新增一项属性值。

`FormData.delete()`

从 FormData 对象里面删除一个键值对。

`FormData.entries()`

返回一个包含所有键值对的`iterator`对象。

`FormData.get()`

`返回在 FormData` 对象中与给定键关联的第一个值。

`FormData.getAll()`

返回一个包含 `FormData` 对象中与给定键关联的所有值的数组。

`FormData.has()`

`返回一个布尔值表明 FormData` 对象是否包含某些键。

`FormData.keys()`

返回一个包含所有键的`iterator`对象。

`FormData.set()`

给 `FormData` 设置属性值，如果`FormData` 对应的属性值存在则覆盖原值，否则新增一项属性值。

`FormData.values()`

返回一个包含所有值的`iterator`对象。

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # interface-formdata |

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

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

参见
--

* `XMLHTTPRequest`
* 使用 XMLHttpRequest
* 使用 FormData 对象
* `<form>`


Web Locks API - Web API 接口参考

Web Locks API
=============

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

**Web Locks API** 允许在一个标签页或 worker 中运行的脚本异步获取锁，在执行工作时保持锁，最后释放锁。持有锁时，在同一源中执行的其他脚本都无法获取相同的锁，这允许在多个标签页或 worker 中运行的 Web 应用程序协调工作和资源的使用。

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

概念和用法
-----

锁是一个抽象概念，代表一些潜在的共享资源，由 Web 应用程序选择的名称进行标识。例如，如果在多个标签页中运行的 Web 应用程序想要确保只有一个标签页在网络和索引数据库之间同步数据，则每个标签页都可以尝试获取“my\_net\_db\_sync”锁，但只有一个标签页会成功（领导者选举模式。）

API 用法如下：

1. 请求锁。
2. 在异步任务中持有锁的同时完成工作。
3. 任务完成后锁自动释放。

```js
navigator.locks.request("my\_resource", async (lock) => {
  // 锁已被获取。
  await do\_something();
  await do\_something\_else();
  // 现在锁将被释放。
});
```

当持有锁时，来自此执行上下文或其他标签页以及 Worker 进程的相同锁的请求将排队。仅当锁被释放时，第一个排队的请求才会被授予锁。

API 提供了可根据需要使用的可选功能，包括：

* 从异步任务返回值
* 共享锁和独占锁模式
* 条件获取
* 诊断以查询源中锁的状态
* 防止死锁的应急通道

锁的范围仅限于同一个源内；一个标签页从 `https://example.com` 获取的锁对另一个标签页从 `https://example.org:8080` 获取的锁没有影响，因为它们是不同的源。

主要入口点是请求锁的 `navigator.locks.request()` 方法。它需要一个锁的名称、一组可选选项和一个回调方法。授予锁时将调用回调方法。当回调方法返回时，锁会自动释放，因此通常回调是一个*异步函数*，这会导致只有当异步函数完全完成时才会释放锁。

`request()` 方法本身返回一个 Promise，一旦锁被释放，该 Promise 就会兑现；在 `async` 函数中，脚本可以使用 `await` 关键字等待调用以使异步代码线性调用。例如：

```js
await do\_something\_without\_lock();

// 请求锁。
await navigator.locks.request("my\_resource", async (lock) => {
  // 锁已被获取。
  await do\_something\_with\_lock();
  await do\_something\_else\_with\_lock();
  // 现在锁将被释放。
});
// 锁已被释放。

await do\_something\_else\_without\_lock();
```

### 选项

请求锁时可以传递一些选项：

* `mode`：默认模式为“独占”（`"exclusive"`），但可以指定为“共享”（`"shared"`）模式。锁只能有一个“独占”持有者，但可以同时授予多个“共享”请求。这可用于实现读者——写者模式。
* `ifAvailable`：如果指定，如果不等待就无法立即授予锁定，则锁定请求将失败。使用 `null` 调用回调方法。
* `steal`：如果指定，则将释放任何持有的同名锁，并且请求将被授予，抢占任何排队的请求。
* `signal`：可以传入一个 `AbortSignal`，允许中止锁定请求。这可用于实现请求超时。
### 监控

脚本可以使用 `navigator.locks.query()` 方法来内省源锁管理器的状态。这在调试时非常有用，例如，确定无法获取锁的原因。结果是一个锁管理器状态的快照，它标识了拍摄快照时持有的锁和请求中的锁以及有关每个锁的一些附加数据（例如模式）。

### 进阶用法

对于更复杂的情况，例如在任意时间内保持锁，回调可以返回一个脚本显式解决的 Promise：

```js
// 捕获 Promise 控制函数：
let resolve, reject;
const p = new Promise((res, rej) => {
  resolve = res;
  reject = rej;
});

// 请求锁：
navigator.locks.request(
  "my\_resource",
  // 锁已被获取。
  (lock) => p, // 现在锁将被保持直到调用 resolve() 方法或 reject() 方法为止。
);
```

### 死锁

当进程的每个部分都在等待无法满足的请求而无法再取得进展时，就会发生死锁。此 API 可能会在复杂的用例中发生这种情况，例如，如果无序请求多个锁。如果标签页 1 持有锁 A 并且标签页 2 持有锁 B，接着标签页 1 也尝试获取锁 B，而标签页 2 也尝试获取锁 A，则两个请求都不会被授予锁。Web 应用程序可以通过多种策略来避免这种情况，例如确保锁定请求不嵌套、始终有序或设定超时。请注意，此类死锁仅影响锁本身和依赖于它们的代码；浏览器、其他标签页和页面中的其他脚本不受影响。

接口
--

`Lock`

提供先前请求的锁的名称和模式，该锁会被传入 `LockManager.request()` 的回调方法接收。

`LockManager`

提供请求新的 `Lock` 对象和查询现有 `Lock` 对象的方法。要获取 `LockManager` 的实例，请访问 `navigator.locks`。

### 其他接口的扩展

`Navigator.locks` 只读

返回一个 `LockManager` 对象，该对象提供请求新的 `Lock` 对象和查询现有 `Lock` 对象的方法。

`WorkerNavigator.locks` 只读

返回一个 `LockManager` 对象，该对象提供请求新的 `Lock` 对象和查询现有 `Lock` 对象的方法。

规范
--

| Specification |
| --- |
| Web Locks API  |

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

### api.LockManager

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

### api.Lock

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


HTML 拖放 API - Web API 接口参考

HTML 拖放 API
===========

**HTML 拖放**（Drag and Drop）接口使应用程序能够在浏览器中使用拖放功能。例如，用户可使用鼠标选择可拖拽（*draggable*）元素，将元素拖拽到可放置（*droppable*）元素，并释放鼠标按钮以放置这些元素。拖拽操作期间，会有一个可拖拽元素的半透明快照跟随着鼠标指针。

对于网站、扩展以及 XUL 应用程序，你可以自定义什么元素是可拖拽的、可拖拽元素产生的反馈类型，以及可放置的元素。

此文档为 HTML 拖放的概述，包含了相关接口的说明、在应用程序中加入拖放支持的基本步骤，以及相关接口的使用简介。

拖拽事件
----

HTML 的 drag & drop 使用了 `DOM event model` 以及从 `mouse events` 继承而来的 *`drag events`*。一个典型的拖拽操作是这样的：用户选中一个\*可拖拽的（draggable）*元素，并将其拖拽（鼠标不放开）到一个*可放置的（droppable）\*元素，然后释放鼠标。

在操作期间，会触发一些事件类型，有一些事件类型可能会被多次触发（比如`drag` 和 `dragover` 事件类型）。

所有的 拖拽事件类型 有一个对应的 拖拽全局属性。每个拖拽事件类型和拖拽全局属性都有对应的描述文档。下面的表格提供了一个简短的事件类型描述，以及一个相关文档的链接。

| 事件 | On 型事件处理程序 | 触发时刻 |
| --- | --- | --- |
| `drag` | `ondrag` | 当拖拽元素或选中的文本时触发。 |
| `dragend` | `ondragend` (en-US) | 当拖拽操作结束时触发 (比如松开鼠标按键或敲“Esc”键). (见结束拖拽 (en-US)) |
| `dragenter` | `ondragenter` (en-US) | 当拖拽元素或选中的文本到一个可释放目标时触发（见 指定释放目标 (en-US)）。 |
| `dragleave` | `ondragleave` | 当拖拽元素或选中的文本离开一个可释放目标时触发。 |
| `dragover` | `ondragover` (en-US) | 当元素或选中的文本被拖到一个可释放目标上时触发（每 100 毫秒触发一次）。 |
| `dragstart` | `ondragstart` (en-US) | 当用户开始拖拽一个元素或选中的文本时触发（见开始拖拽操作 (en-US)）。 |
| `drop` | `ondrop` | 当元素或选中的文本在可释放目标上被释放时触发（见执行释放 (en-US)）。 |

\*\*注意：\*\*当从操作系统向浏览器中拖拽文件时，不会触发 `dragstart` 和`dragend` 事件。

接口
--

HTML 的拖拽接口有 `DragEvent`, `DataTransfer`, `DataTransferItem` 和`DataTransferItemList`。

`DragEvent` 接口有一个构造函数和一个 `dataTransfer` 属性，dataTransfer 属性是一个 `DataTransfer` 对象。

`DataTransfer` 对象包含了拖拽事件的状态，例如拖拽事件的类型（如拷贝 `copy` 或者移动 `move`），拖拽的数据（一个或者多个项）和每个拖拽项的类型（MIME 类型）。 `DataTransfer` 对象也有向拖拽数据中添加或删除项目的方法。

给应用程序添加 HTML 拖放功能，`DragEvent` 和 `DataTransfer` 接口应该是唯二需要的接口（Firefox 给 `DataTransfer` 添加了一些 Gecko 专有的扩展功能，但这些扩展只在 Firefox 上可用）。

每个 `DataTransfer` 都包含一个 `items` 属性，这个属性是 `DataTransferItem` 对象的 `list`。一个 `DataTransferItem` 代表一个拖拽项目，每个项目都有一个 `kind` 属性（`string` 或 `file`）和一个表示数据项目 MIME 类型的 `type` 属性。`DataTransferItem` 对象也有获取拖拽项目数据的方法。

`DataTransferItemList` 对象是 `DataTransferItem` 对象的列表。这个列表对象包含以下方法：向列表中添加拖拽项，从列表中移除拖拽项和清空列表中所有的拖拽项。

`DataTransfer` 和 `DataTransferItem` 接口的一个主要的不同是前者使用同步的 `getData()` 方法去得到拖拽项的数据，而后者使用异步的 `getAsString()` 方法得到拖拽项的数据。

注意：`DragEvent` 和 `DataTransfer` 接口是所有桌面浏览器都支持的。但是， `DataTransferItem` 和`DataTransferItemList` 接口并不被所有浏览器支持。请移步 互操作性 了解更多关于拖拽行为的信息。

### Gecko 专用接口

Mozilla 和 Firefox 支持一些不在标准拖放模型中的特性。请查看 `DataTransfer` 参考页以获取所有 Gecko 专有属性 和 Gecko 专有方法。

基础
--

这一部分总结了给应用程序加入拖放功能的基本步骤。

### 确定什么是可拖拽的

让一个元素被拖拽需要添加 `draggable` 属性，再加上全局事件处理函数`ondragstart` (en-US)，如下面的示例代码所示：

```html
<script>
 function dragstart\_handler(ev) {
 // Add the target element's id to the data transfer object
 ev.dataTransfer.setData("text/plain", ev.target.id);
 }

 window.addEventListener("DOMContentLoaded", () => {
 // Get the element by id
 const element = document.getElementById("p1");
 // Add the ondragstart event listener
 element.addEventListener("dragstart", dragstart\_handler);
 });
</script>

<p id="p1" draggable="true">This element is draggable.</p>
```

查看更多 draggable 属性 和 拖拽操作指南 (en-US)。

### 定义拖拽数据

应用程序可以在拖拽操作中包含任意数量的数据项。每个数据项都是一个 `string` 类型，典型的 MIME 类型，如：`text/html`。

每个 `drag event` 都有一个`dataTransfer` 属性，其中保存着事件的数据。这个属性（`DataTransfer` 对象）也有管理拖拽数据的方法。`setData()` 方法为拖拽数据添加一个项，如下面的示例代码所示：

```js
function dragstart\_handler(ev) {
  // 添加拖拽数据
  ev.dataTransfer.setData("text/plain", ev.target.innerText);
  ev.dataTransfer.setData("text/html", ev.target.outerHTML);
  ev.dataTransfer.setData(
    "text/uri-list",
    ev.target.ownerDocument.location.href,
  );
}
```

查看 推荐拖拽类型 (en-US) 了解可拖拽的常见数据类型（如文本、HTML、链接和文件），移步 拖拽数据 (en-US) 获取更多有关拖拽数据的信息。

### 定义拖拽图像

拖拽过程中，浏览器会在鼠标旁显示一张默认图片。当然，应用程序也可以通过 `setDragImage()` 方法自定义一张图片，如下面的例子所示。

```js
function dragstart\_handler(ev) {
  // Create an image and then use it for the drag image.
  // NOTE: change "example.gif" to a real image URL or the image
  // will not be created and the default drag image will be used.
  var img = new Image();
  img.src = "example.gif";
  ev.dataTransfer.setDragImage(img, 10, 10);
}
```

欲了解更多关于拖拽图像的信息，见 设置拖拽图像 (en-US)。

### 定义拖拽效果

`dropEffect` 属性用来控制拖放操作中用户给予的反馈。它会影响到拖拽过程中浏览器显示的鼠标样式。比如，当用户悬停在目标元素上的时候，浏览器鼠标也许要反映拖放操作的类型。

有 3 个效果可以定义：

1. **`copy`** 表明被拖拽的数据将从它原本的位置拷贝到目标的位置。
2. **`move`** 表明被拖拽的数据将被移动。
3. **`link`** 表明在拖拽源位置和目标位置之间将会创建一些关系表格或是连接。

在拖拽过程中，拖拽效果也许会被修改以用于表明在具体位置上具体效果是否被允许，如果允许，在该位置则被允许放置。

以下例子表明如何使用该属性。

```js
function dragstart\_handler(ev) {
  ev.dataTransfer.dropEffect = "copy";
}
```

查看 拖拽效果 (en-US) 更多细节。

### 定义一个放置区

当拖拽一个项目到 HTML 元素中时，浏览器默认不会有任何响应。想要让一个元素变成可释放区域，该元素必须设置 `ondragover` (en-US) 和 `ondrop` 事件处理程序属性，下面的例子通过简单的事件处理展示了如何使用这些属性：

```html
<script>
 function dragover\_handler(ev) {
 ev.preventDefault();
 ev.dataTransfer.dropEffect = "move";
 }
 function drop\_handler(ev) {
 ev.preventDefault();
 // Get the id of the target and add the moved element to the target's DOM
 var data = ev.dataTransfer.getData("text/plain");
 ev.target.appendChild(document.getElementById(data));
 }
</script>

<p
 id="target"
 ondrop="drop\_handler(event)"
 ondragover="dragover\_handler(event)">
  Drop Zone
</p>
```

注意每个处理程序调用 `preventDefault()` 来阻止对这个事件的其他处理过程（如触点事件或指针事件）。

欲了解更多信息，参见 指定释放目标 (en-US)。

### 处理放置效果

`drop` 事件的处理程序是以程序指定的方法处理拖拽数据。一般，程序调用 `getData()` 方法取出拖拽项目并按一定方式处理。程序意义根据 `dropEffect` 的值与/或可变更关键字的状态而不同

下面的例子展示了一个处理程序，从拖拽数据中获取事件源元素的 `id` 然后根据 `id` 移动源元素到目标元素：

```html
<script>
 function dragstart\_handler(ev) {
 // Add the target element's id to the data transfer object
 ev.dataTransfer.setData("application/my-app", ev.target.id);
 ev.dataTransfer.dropEffect = "move";
 }
 function dragover\_handler(ev) {
 ev.preventDefault();
 ev.dataTransfer.dropEffect = "move";
 }
 function drop\_handler(ev) {
 ev.preventDefault();
 // Get the id of the target and add the moved element to the target's DOM
 var data = ev.dataTransfer.getData("application/my-app");
 ev.target.appendChild(document.getElementById(data));
 }
</script>

<p id="p1" draggable="true" ondragstart="dragstart\_handler(event)">
  This element is draggable.
</p>
<div
 id="target"
 ondrop="drop\_handler(event)"
 ondragover="dragover\_handler(event)">
  Drop Zone
</div>
```

更多信息请参见 执行释放 (en-US)。

### 拖拽结束

拖拽操作结束时，在源元素（开始拖拽时的目标元素）上触发 `dragend` 事件。不管拖拽是完成还是被取消这个事件都会被触发。`dragend` 事件处理程序可以检查`dropEffect` 属性的值来确认拖拽成功与否。

更多关于处理拖拽结束的信息请参见 结束拖拽 (en-US)。

互操作性
----

在 数据交换对象接口的浏览器兼容性表 中可以看到拖放在桌面浏览器中相对支持得比较完整（除了 `DataTransferItem` 和 `DataTransferItemList` 接口支持得较少）。这个数据也显示出拖放操作在移动浏览器中支持得非常弱。

示例和演示
-----

* 使用 `DataTransfer` 接口拷贝和移动元素
* 使用 `DataTransferListItem` 接口拷贝和移动元素
* 拖放文件；仅 Firefox 支持：http://jsfiddle.net/9C2EF/
* 拖放文件；所有浏览器支持：https://jsbin.com/hiqasek/
* 使用了拖放 API 的停车小页面：https://park.glitch.me/ （在 这里 编辑）
规范
--

| Specification |
| --- |
| HTML Standard  |

参见
--

* 拖拽操作
* 推荐拖拽元素类型
* HTML5 Living Standard：HTML5 拖放操作
* 来自 CanIUse 的拖放兼容数据


CSSRule - Web API 接口参考

CSSRule
=======

**`CSSRule`** 接口表示一条 CSS 规则。有几种不同的规则类型，在下面的类型常量部分中有悉数列出。

`CSSRule` 接口指定了所有类型的规则的公共属性，而特定类型的规则的专有属性则在这些规则各自类型的、更专用的接口中被指定。

可以通过 `CSSStyleSheet` 的 `cssRules` 列表了解更多关于 `CSSRule` 的介绍。

所有 CSSRule 实例共有的属性
------------------

`CSSRule.cssText`

返回规则的文本表示。例如 `"h1,h2 { font-size: 16pt }"`

`CSSRule.parentRule` (en-US) 只读

返回包含规则，否则返回 `null`。例如：如果此规则是 `@media` 块中的样式规则，则其父规则将是该 `CSSMediaRule`。

`CSSRule.parentStyleSheet` 只读

返回包含此规则的样式表的 `CSSStyleSheet` 对象。

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

规则类型，表示 CSS 规则类型 类型常量 中的一种类型。

常量
--

### 类型常量

`CSSRule` 接口通过一系列整型常量来约束 `CSSRule` 的 `type` (en-US) 取值范围，同时这些常量也对应规则的具体实现接口。这些常量和接口的对应关系如下：

* `CSSStyleRule`
* `CSSImportRule` (en-US)
* `CSSMediaRule`
* `CSSFontFaceRule` (en-US)
* `CSSPageRule`
* `CSSNamespaceRule` (en-US)
* `CSSKeyframesRule` (en-US)
* `CSSKeyframeRule` (en-US)
* `CSSCounterStyleRule` (en-US)
* `CSSDocumentRule`
* `CSSSupportsRule`
* `CSSFontFeatureValuesRule` (en-US)
* `CSSViewportRule`

An up-to-date informal list of constants can be found on the CSSWG Wiki.

语法
--

使用 WebIDL 语法格式进行描述。
```

interface CSSRule {
    const unsigned short STYLE_RULE = 1;
    const unsigned short CHARSET_RULE = 2;
    const unsigned short IMPORT_RULE = 3;
    const unsigned short MEDIA_RULE = 4;
    const unsigned short FONT_FACE_RULE = 5;
    const unsigned short PAGE_RULE = 6;
    const unsigned short KEYFRAMES_RULE = 7;
    const unsigned short KEYFRAME_RULE = 8;
    const unsigned short NAMESPACE_RULE = 10;
    const unsigned short COUNTER_STYLE_RULE = 11;
    const unsigned short SUPPORTS_RULE = 12;
    const unsigned short DOCUMENT_RULE = 13;
    const unsigned short FONT_FEATURE_VALUES_RULE = 14;
    const unsigned short VIEWPORT_RULE = 15;
    const unsigned short REGION_STYLE_RULE = 16;
    readonly attribute unsigned short type;
    attribute DOMString cssText;
    readonly attribute CSSRule? parentRule;
    readonly attribute CSSStyleSheet? parentStyleSheet;
};
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # the-cssrule-interface |

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

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

参见
--

* Using dynamic styling information (en-US)


PageTransitionEvent - Web API 接口参考

PageTransitionEvent
===================

Page transition events fire when a webpage is being loaded or unloaded.

当网页在加载完成或卸载后会触发页面传输事件（Page transition events）。

DOM Information
---------------

### Inheritance Hierarchy

EventPageTransitionEvent

Example
-------

### HTML

```html
<!doctype html>
<html>
  <body onpageshow="myFunction(event)"></body>
</html>
```

### JavaScript

```js
function myFunction(event) {
  if (event.persisted) {
    alert("The page was cached by the browser");
  } else {
    alert("The page was NOT cached by the browser");
  }
}
```

Members
-------

The **PageTransitionEvent** object has these types of members:

* Properties
### Properties

The **PageTransitionEvent** object has these properties.

| Property | Access type | Description |
| --- | --- | --- |
| **persisted** | 只读 | 标记页面是否从缓存（Backforward Cache）中加载 |


RTCPeerConnection - Web API 接口参考

RTCPeerConnection
=================

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

**`RTCPeerConnection`** 接口代表一个由本地计算机到远端的 WebRTC 连接。该接口提供了创建，保持，监控，关闭连接的方法的实现。

**备注：** `RTCPeerConnection` 和`RTCSessionDescription` 是很多浏览器中使用的名称。强烈建议使用补充库，例如强大并且被广泛支持的Adapter.js，以确保你网站或 Web 应用程序的兼容性。值得注意的是Adapter.js不仅仅提供这些，它还做了一些其他补充以增强 WebRTC 在浏览器中的兼容性。参考：
```

var PeerConnection = window.RTCPeerConnection || window.mozRTCPeerConnection || window.webkitRTCPeerConnection;
var SessionDescription = window.RTCSessionDescription || window.mozRTCSessionDescription || window.webkitRTCSessionDescription;
var GET_USER_MEDIA = navigator.getUserMedia ? "getUserMedia" :
                     navigator.mozGetUserMedia ? "mozGetUserMedia" :
                     navigator.webkitGetUserMedia ? "webkitGetUserMedia" : "getUserMedia";
var v = document.createElement("video");
var SRC_OBJECT = 'srcObject' in v ? "srcObject" :
                 'mozSrcObject' in v ? "mozSrcObject" :
                 'webkitSrcObject' in v ? "webkitSrcObject" : "srcObject";
```

由于 RTCPeerConnection 实现了 `EventTarget` 接口，故其可以接收处理事件。

### 构造函数

`RTCPeerConnection.RTCPeerConnection()`

构造函数;创建一个新的 RTCPeerConnection 对象。

### 属性

*该接口的属性继承了其父接口，`EventTarget`.*

`RTCPeerConnection.canTrickleIceCandidates` 只读

`如果远端支持 UDP 打洞或支持通过中继服务器连接，则该属性值为 true。否则，为 false。该属性的值依赖于远端设置且仅在本地的` `RTCPeerConnection.setRemoteDescription()`方法被调用时有效，如果该方法没被调用，则其值为 null.

`RTCPeerConnection.connectionState` 只读

只读 connectionState 属性通过返回由枚举 RTCPeerConnectionState 指定的字符串值之一来指示对等连接的当前状态。

`RTCPeerConnection.currentLocalDescription` 只读

只读属性 RTCPeerConnection.currentLocalDescription 返回一个描述连接本地端的 RTCSessionDescription 对象，因为自上次 RTCPeerConnection 完成协商并连接到远程对等体之后，它最近成功协商。还包括可能已经由 ICE 代理生成的任何 ICE 候选者的列表，因为首先被描述的描述所表示的要约或答案。

`RTCPeerConnection.currentRemoteDescription` (en-US) 只读

只读属性 RTCPeerConnection.currentRemoteDescription 返回一个 RTCSessionDescription 对象，描述连接的远程端，因为最近一次 RTCPeerConnection 完成协商并连接到远程对等体后最近成功协商。还包括可能已经由 ICE 代理生成的任何 ICE 候选者的列表，因为首先被描述的描述所表示的要约或答案。

`RTCPeerConnection.defaultIceServers` 只读

只读属性 RTCPeerConnection.defaultIceServers 根据 RTCIceServer 字典返回一个对象数组，该字典指示如果在 RTCConfiguration 中没有提供给 RTCPeerConnection 的默认情况下，浏览器将使用 ICE 服务器。然而，浏览器根本不需要提供任何默认的 ICE 服务器。

`RTCPeerConnection.iceConnectionState` 只读

只读属性 RTCPeerConnection.iceConnectionState 返回与 RTCPeerConnection 关联的 ICE 代理的状态类型为 RTCIceConnectionState 的枚举。

`RTCPeerConnection.iceGatheringState` 只读

只读属性，返回一个 RTCIceGatheringState 类型的结构体，它描述了连接的 ICE 收集状态

`RTCPeerConnection.idpLoginUrl` 只读

blah

`RTCPeerConnection.localDescription` (en-US) 只读

只读属性，返回一个 `RTCSessionDescription` ，它描述了这条连接的本地端的会话控制（用户会话所需的属性以及配置信息）。如果本地的会话控制还没有被设置，它的值就会是 null。

`RTCPeerConnection.peerIdentity` 只读

只读属性，返回一个 `RTCIdentityAssertion`，它由一组信息构成，包括一个域名（idp）以及一个名称（name），它们代表了这条连接的远端机器的身份识别信息。如果远端机器还没有被设置以及校验，这个属性会返回一个 `null` 值。一旦被设置，它不能被一般方法改变。

`RTCPeerConnection.pendingLocalDescription` (en-US) 只读

blah

`RTCPeerConnection.pendingRemoteDescription` (en-US) 只读

blah

`RTCPeerConnection.remoteDescription` 只读

blah

`RTCPeerConnection.sctp` (en-US) 只读

blah

`RTCPeerConnection.signalingState` (en-US) 只读

返回一个 RTC 通信状态的结构体，这个结构体描述了本地连接的通信状态。这个 状态描述了一个定义连接配置的 SDP offer。它包含了下列信息，与`MediaStream` 类型本地相关的对象的描述，媒体流编码方式或 RTP 和 RTCP 协议的选项，以及被 ICE 服务器收集到的 candidates(连接候选者)。当 `RTCPeerConnection.signalingState` (en-US) 的值改变时，对象上的 `signalingstatechange` (en-US) 事件会被触发。

### 基本用法

一个基本的 RTCPeerConnection 使用需要协调本地机器以及远端机器的连接，它可以通过在两台机器间生成 Session Description 的数据交换协议来实现。呼叫方发送一个 offer(请求)，被呼叫方发出一个 answer（应答）来回答请求。双方 - 呼叫方以及被呼叫方，最开始的时候都要建立他们各自的 RTCPeerConnection 对象。
```

var pc = new RTCPeerConnection();
pc.onaddstream = function(obj) {
  var vid = document.createElement("video");
  document.appendChild(vid);
  vid.srcObject = obj.stream;
}

// Helper functions
function endCall() {
  var videos = document.getElementsByTagName("video");
  for (var i = 0; i < videos.length; i++) {
    videos[i].pause();
  }

  pc.close();
}

function error(err) { endCall(); }
```

呼叫初始化

如果你是呼叫方，你需要初始化一个连接
```

// Get a list of friends from a server
// User selects a friend to start a peer connection with
navigator.getUserMedia({video: true}, function(stream) {
  pc.onaddstream({stream: stream});
  // Adding a local stream won't trigger the onaddstream callback
  pc.addStream(stream);

  pc.createOffer(function(offer) {
    pc.setLocalDescription(new RTCSessionDescription(offer), function() {
      // send the offer to a server to be forwarded to the friend you're calling.
    }, error);
  }, error);
})
```

呼叫回答

在另一端，你的朋友会从服务器收到 offer 信息。
```

var offer = getOfferFromFriend();
navigator.getUserMedia({video: true}, function(stream) {
  pc.onaddstream({stream: stream});
  pc.addStream(stream);

  pc.setRemoteDescription(new RTCSessionDescription(offer), function() {
    pc.createAnswer(function(answer) {
      pc.setLocalDescription(new RTCSessionDescription(answer), function() {
        // send the answer to a server to be forwarded back to the caller (you)
      }, error);
    }, error);
  }, error);
})
```

处理应答

同时在呼叫发起方，你会收到这个应答（前面被呼叫方发出的 answer），你需要将它设置为你的远端连接。
```

// pc was set up earlier when we made the original offer
var offer = getResponseFromFriend();
pc.setRemoteDescription(new RTCSessionDescription(offer), function() { }, error);
```

属性
--

*这个接口从它的父元素中继承属性，`EventTarget`.*

`RTCPeerConnection.iceConnectionState` 只读

返回一个 RTCIceConnectionState 类型的结构体，这个结构体描述了连接的 ICE 连接状态。当这个状态的值改变时，这个对象会触发一个 `iceconnectionstatechange` (en-US) 事件。状态可能存在的值如下：

* "new": ICE 服务器正在收集地址或正在等待远端的 candidates(这两种情况可能同时存在)。
* `"checking"`: ICE 服务器找到了远端的 candidates（连接候选者）,这些 candidates 至少有一个，同时 ICE 服务器在检测这些 candidates，尽管它可能还没有找到连接。此刻，ICE 服务器可能仍在收集 candidates（连接候选者）。
* `"connected"`: ICE 服务器已经找到了一条可用的适合所有组件的连接，但它仍然在测试更多的远端 candidate 以提供更好的连接。同时，ICE 服务器可能仍在收集 candidates。
* `"completed"`: ICE 服务器已经找到了一条可用的连接，并不再测试远端 candidates。
* `"failed"`: ICE 服务器已经检测了所有的远端 candidates，但并没有找到可用的。对一些组件适用的连接可能已经被找到。
* `"disconnected"`: 至少一个组件的活跃度检查失败了，这可能是由糟糕的网络环境造成的一个短期状态，它可以被它自身所修复。
* `"closed"`: ICE 服务器已经关闭，并不再响应请求。

`RTCPeerConnection.iceGatheringState` 只读

返回一个 iceGatheringState 类型的结构体，它描述了这条连接的 ICE 收集状态。该状态可能取以下的值：

* `"new"`: 对象刚刚被创建，还没有网络化。
* `"gathering"`: ICE 引擎正在为连接收集 candidates(连接候选者)。
* `"complete"`: 引擎已经完成了 candidates 收集。但像添加一个新的接口或者一个新的 turn 服务器这些事件会导致状态回到"gathering"。

`RTCPeerConnection.localDescription` (en-US) 只读

返回一个 `RTCSessionDescription` ，它描述了这条连接的本地端的会话控制（用户会话所需的属性以及配置信息）。如果本地的会话控制还没有被设置，它的值就会是 null。

`RTCPeerConnection.peerIdentity` 只读

返回一个`RTCIdentityAssertion，它由一组信息构成，包括一个域名（idp）以及一个名称（name），它们代表了这条连接的远端机器的身份识别信息。如果远端机器还没有被设置以及校验，这个属性会返回一个 null 值。一旦被设置，它不能被一般方法改变`。

`RTCPeerConnection.remoteDescription` 只读

返回一个 `RTCSessionDescription` 它描述了这条连接的远端机器的会话控制，如果远端机器还未被设置，它的值会是 null。

`RTCPeerConnection.signalingState` (en-US) 只读

返回一个 RTC 通信状态的结构体，这个结构体描述了本地连接的通信状态。这个 状态描述了一个定义连接配置的 SDP offer。它包含了下列信息，与`MediaStream` 类型本地相关的对象的描述，媒体流编码方式或 RTP 和 RTCP 协议的选项，以及被 ICE 服务器收集到的 candidates(连接候选者)。当`RTCPeerConnection.signalingState` (en-US)的值改变时，对象上的 `signalingstatechange` (en-US) 事件会被触发。它可能取下列的值：

* `"stable"`: 没有 SDP offer/answer 正在被交换，连接仍然处于初始化状态。
* `"have-local-offer"`: 这条连接的本地端机器已经本地应用了一个 SDP offer。
* `"have-remote-offer"`: 这条连接的远端机器已经本地应用了一个 SDP offer。
* `"have-local-pranswer"`: 一个来自远端的 SDP offer 已经被应用，同时一个 SDP pranswer 在本地被应用。
* `"have-remote-pranswer"`：一个本地的 SDP offer 被应用，同时一个 SDP pranswer 在远端被应用。
* `"closed"`: 连接被关闭。

### 事件处理器

`RTCPeerConnection.onaddstream`

是收到 `addstream` 事件时调用的事件处理器。Such an event is 当`MediaStream` 被远端机器添加到这条连接时，该事件会被触发。当调用`RTCPeerConnection.setRemoteDescription()`方法时，这个事件就会被立即触发，它不会等待 SDP 协商的结果。

`RTCPeerConnection.ondatachannel`

是收到 `datachannel` 事件时调用的事件处理器。当一个 `RTCDataChannel` 被添加到连接时，这个事件被触发。

`RTCPeerConnection.onicecandidate`

是收到 `icecandidate` 事件时调用的事件处理器.。当一个 `RTCICECandidate` (en-US) 对象被添加时，这个事件被触发。

`RTCPeerConnection.oniceconnectionstatechange` (en-US)

是收到 `iceconnectionstatechange` 事件时调用的事件处理器。当`iceConnectionState` 改变时，这个事件被触发。

`RTCPeerConnection.onidentityresult`

是收到 `identityresult` 事件时调用的事件处理器。当通过`getIdentityAssertion()` (en-US)生成身份断言，或在生成一个 answer 或一个 offer 的过程中，这个事件被触发。

`RTCPeerConnection.onidpassertionerror`

是收到 `idpassertionerror` 事件时调用的事件处理器。当生成一个身份断言时，如果关联的身份提供者（idP）遇到一个错误，这个事件就会被触发。

`RTCPeerConnection.onidpvalidationerror`

是收到 `idpvalidationerror` 事件时调用的事件处理器。当检查 一个身份断言时，如果关联的身份提供者（idP）遇到一个错误，这个事件就会被触发。

`RTCPeerConnection.onnegotiationneeded` (en-US)

是收到 `negotiationneeded` 事件时调用的事件处理器，浏览器发送该事件以告知在将来某一时刻需要协商。

`RTCPeerConnection.onpeeridentity`

是收到 `peeridentity` 事件时调用的事件处理器，当一条连接的 peer identify 被设置以及校验后，该事件被触发

`RTCPeerConnection.onremovestream` (en-US)

是收到 `removestream` 事件时调用的事件处理器，当一条`MediaStream` 从连接上移除时，该事件被触发。

`RTCPeerConnection.onsignalingstatechange` (en-US)

是收到 `signalingstatechange` 事件时调用的事件处理器，当`signalingState` (en-US)的值发生改变时，该事件被触发。

构造函数
----

`RTCPeerConnection()`

RTCPeerConnection 的初始化函数，通过 new RTCPeerConnection() 初始化一个 RTCPeerConnection 实例。

实例方法
----

`RTCPeerConnection.createOffer()`

生成一个 offer，它是一个带有特定的配置信息寻找远端匹配机器（peer）的请求。这个方法的前两个参数分别是方法调用成功以及失败的回调函数，可选的第三个参数是用户对视频流以及音频流的定制选项（一个对象）。

`RTCPeerConnection.createAnswer()` (en-US)

在协调一条连接中的两端 offer/answers 时，根据从远端发来的 offer 生成一个 answer。这个方法的前两个参数分别是方法调用成功以及失败时的回调函数，可选的第三个参数是生成的 answer 的可供选项。

`RTCPeerConnection.setLocalDescription()` (en-US)

改变与连接相关的本地描述。这个描述定义了连接的属性，例如：连接的编码方式。连接会受到它的改变的影响，而且连接必须能同时支持新的以及旧的描述。这个方法可以接收三个参数，一个`RTCSessionDescription` 对象包含设置信息，还有两个回调函数，它们分别是方法调用成功以及失败的回调函数。

`RTCPeerConnection.setRemoteDescription()`

改变与连接相关的远端描述。这个描述定义了连接的属性，例如：连接的编码方式。连接会受到它的改变的影响，而且连接必须能同时支持新的以及旧的描述。这个方法可以接收三个参数，一个`RTCSessionDescription` 对象包含设置信息，还有两个回调函数，它们分别是方法调用成功以及失败的回调函数。

`RTCPeerConnection.updateIce()`

更新 ICE 服务器时调用的方法。

`RTCPeerConnection.addIceCandidate()`

添加 iceCandidate 时调用的方法。

`RTCPeerConnection.getConfiguration()` (en-US)

获取配置信息时调用的方法。

`RTCPeerConnection.getLocalStreams()` (en-US)

返回连接的本地媒体流数组。这个数组可能是空数组。

`RTCPeerConnection.getRemoteStreams()` (en-US)

返回连接的远端媒体流数组。这个数组可能是空数组。

`RTCPeerConnection.getStreamById()` (en-US)

返回连接中与所给 id 匹配的媒体流 `MediaStream`，如果没有匹配项，返回 null。

`RTCPeerConnection.addStream()` (en-US)

添加一个媒体流 `MediaStream`作为本地音频或视频源。如果本地端与远端协调已经发生了，那么需要一个新的媒体流，这样远端才可以使用它。

`RTCPeerConnection.removeStream()`

将一个作为本地音频或视频源的媒体流 `MediaStream`移除。如果本地端与远端协调已经发生了，那么需要一个新的媒体流，这样远端才可以停止使用它。

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

关闭一个 RTCPeerConnection 实例所调用的方法。

`RTCPeerConnection.createDataChannel()`

在一条连接上建立一个新的`RTCDataChannel`（用于数据发送）。这个方法把一个数据对象作为参数，数据对象中包含必要的配置信息。

`RTCPeerConnection.createDTMFSender()`

创建一个新的与特殊的`MediaStreamTrack`相关的`RTCDTMFSender` (en-US)，可以在连接上发送DTMF (en-US)手机信号。

`RTCPeerConnection.getStats()` (en-US)

生成一个新的`RTCStatsReport`，它包含连接相关的统计信息。

`RTCPeerConnection.setIdentityProvider()` (en-US)

根据所给的三个参数设置身份提供者（IdP)，这三个参数是它的名称，通信所使用的协议（可选），以及一个可选的用户名。只有当一个断言被需要时，这个 IdP 才会被使用。

`RTCPeerConnection.getIdentityAssertion()` (en-US)

初始化身份断言的收集，只有当`signalingState` (en-US)的值不为"closed"时，它才有效。它自动完成，在需求发生前调用它是最好的选择。

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # interface-definition |

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

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

参见
--

* https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
* WebRTC 入门
* TutorRoom：Node.js HTML 视频捕获、点对点视频和文件共享应用程序（GitHub 上的源码）