Sensor APIs - Web API 接口参考

Sensor APIs
===========

传感器 API（Sensor APIs）是一组统一设计的接口，它们在 web 平台中为各类传感器提供了一致的访问方式。

传感器 API 的概念和使用
--------------

尽管通用传感器 API 规范（Generic Sensor API specification）定义了一个 `Sensor` (en-US) 接口，但作为 web 开发者不应该直接使用它。你应该使用它的某个子类来获得指定的传感器数据。例如，`accelerometer` (en-US)接口返回设备当前沿所有三个轴的加速度。

传感器接口不一定与物理上的传感器一一对应。例如，`Gyroscope` (en-US) 接口确实与一个单独的物理器件接口对应，但`AbsoluteOrientationSensor` (en-US)接口提供的信息则是来自两个或更多传感器器件的数据通过算法得到的。这两类传感器分别被称为*低级的*（*low-level*）和*高级的*（*high-level*）。后者也被称为融合传感器（fusion sensor），或者虚拟（virtual）传感器，或称合成（synthetic）传感器。

### 功能检测

传感器接口仅仅是底层器件传感器的代理。因此，相比其他 API，传感器功能检测更为复杂。传感器 API 的存在并不能告诉你 API 是否与一个真实的硬件传感器相连，即使相连它是否在工作，甚至用户是否已经授权访问它。要一致地提供所有这些信息是要消耗性能和电池电量的。

因此，传感器 API 的功能检测必须包含 API 本身的检测以及防御性编程策略（见下）（defensive programming strategies）。

下面的例子展示了检测传感器 API 的三种方法。此外你还可以把对象实例化部分放在一个`try...catch` 块中。注意通过你并不能通过`Navigator` 接口来实现传感器检测。

```js
if (typeof Gyroscope === "function") {
  // run in circles...
}

if ("ProximitySensor" in window) {
  // watch out!
}

if (window.AmbientLightSensor) {
  // go dark...
}
```

### 许可和功能策略

只有用户对针对某种类型的传感器授权之后，才能对该类传感器进行读取。用`Permissions` API 来进行这种授权。下面的小例子展示了在试图使用传感器之前首先请求授权。

```js
navigator.permissions.query({ name: 'accelerometer' })
.then(result => {
  if (result.state === 'denied') {
    console.log('Permission to use accelerometer sensor is denied.');
    return;
  }
  // Use the sensor.
}
```

另外一种方式是利用错误并侦听`SecurityError`事件。

```js
const sensor = new AbsoluteOrientationSensor();
sensor.start();
sensor.onerror = (event) => {
  if (event.error.name === "SecurityError")
    console.log("No permissions to use AbsoluteOrientationSensor.");
};
```

下表描述了每种传感器类型，使用它们在 Permissions API、`<iframe>` 元素中`allow` 属性，以及`Permissions-Policy`语句中被引用时使用的名字。

| Sensor | Permission/Feature Policy Name |
| --- | --- |
| `AbsoluteOrientationSensor` | `'accelerometer'`, `'gyroscope'`, and `'magnetometer'` |
| `Accelerometer` | `'accelerometer'` |
| `AmbientLightSensor` | `'ambient-light-sensor'` |
| `Gyroscope` | `'gyroscope'` |
| `LinearAccelerationSensor` | `'accelerometer'` |
| `Magnetometer` | `'magnetometer'` |
| `RelativeOrientationSensor` | `'accelerometer'`, and `'gyroscope'` |

### 读数

传感器读数通过`Sensor.onreading` (en-US)回调函数获得，该回调函数被所有传感器类型继承。读取频率可通过在传感器的构造函数中带相应的选项来指定。此选项是一个数值，它指定每秒读取的次数。可使用整数或小数，后者用于频率低于每秒一次的情况。实际的读取频率依赖于器件的硬件实现因而可能小于所请求的频率。

下面以`Magnetometer` (en-US)为例展示使用方法。

```js
let magSensor = new Magnetometer({ frequency: 60 });

magSensor.addEventListener("reading", (e) => {
  console.log("Magnetic field along the X-axis " + magSensor.x);
  console.log("Magnetic field along the Y-axis " + magSensor.y);
  console.log("Magnetic field along the Z-axis " + magSensor.z);
});
magSensor.addEventListener("error", (event) => {
  console.log(event.error.name, event.error.message);
});
magSensor.start();
```

### 防御性编程

防御性编程（defensive programming）要遵循下面三个原则：

* 实例化一个传感器对象时要检查抛出的错误。
* 使用中要侦听抛出的错误。
* 正确处理错误以提升用户体验而非相反

下面的示例代码说明以上原则。`try...catch`代码块捕捉在实例化传感器时抛出的错误。它实现了一个`Sensor.onerror` (en-US)处理函数以捕捉使用中抛出的错误。它只在以下情况下提示用户：需要请求权限 (en-US)时，以及所请求的传感器类型在设备上不支持时。

**备注：** 如果一个权限策略（permission policy）阻止了对某功能的使用，这是因为你的代码与你的服务器上设置的策略不一致。这种情况是不应该显示给用户看的。具体实现请参见 `Permissions-Policy`。

```js
let accelerometer = null;
try {
  accelerometer = new Accelerometer({ referenceFrame: "device" });
  accelerometer.addEventListener("error", (event) => {
    // Handle runtime errors.
    if (event.error.name === "NotAllowedError") {
      // Branch to code for requesting permission.
    } else if (event.error.name === "NotReadableError") {
      console.log("Cannot connect to the sensor.");
    }
  });
  accelerometer.addEventListener("reading", () => reloadOnShake(accelerometer));
  accelerometer.start();
} catch (error) {
  // Handle construction errors.
  if (error.name === "SecurityError") {
    // See the note above about feature policy.
    console.log("Sensor construction was blocked by a feature policy.");
  } else if (error.name === "ReferenceError") {
    console.log("Sensor is not supported by the User Agent.");
  } else {
    throw error;
  }
}
```

接口
--

`AbsoluteOrientationSensor` (en-US)

描述相对于地球参考坐标系的设备物理方向。

`Accelerometer` (en-US)

提供沿三个轴的加速度。

`AmbientLightSensor`

返回当前光照强度或环境光照度。

`Gyroscope` (en-US)

提供三个轴向的角速度。

`LinearAccelerationSensor` (en-US)

提供去除重力贡献部分之后的沿三个轴的加速度。

`Magnetometer` (en-US)

提供由设备主磁传感器检测到的磁场信息。

`OrientationSensor` (en-US)

`AbsoluteOrientationSensor` (en-US)的基类。本接口不能直接使用。它提供其继承类可访问的属性和方法。

`RelativeOrientationSensor` (en-US)

描述设备与地球参考坐标系无关的物理方向。

`Sensor` (en-US)

所有其他传感器接口的基类。本接口不能直接使用。它提供其继承类可访问的属性、事件处理函数及方法。

`SensorErrorEvent` (en-US)

提供由`Sensor` (en-US)或其相关的接口抛出的错误的信息。

规范
--

| Specification |
| --- |
| Generic Sensor API # the-sensor-interface |

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

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


IDBDatabase - Web API 接口参考

IDBDatabase
===========

IndexedDB 中的 **`IDBDatabase`** 接口提供一个到 数据库的连接; 你可以使用 `IDBDatabase` 对象在数据库中打开一个transaction , 然后进行操作或者删除数据库中的对象。这是唯一一个能够访问和管理数据库版本的接口。

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

**备注：** 在 IndexedDB 中所做的所有事情总是发生在事务 (en-US)的上下文中，表示与数据库中的数据的交互。IndexedDB 中的所有对象——包括对象存储、索引和游标——都与特定事务绑定。因此，在事务之外你不能执行命令、访问数据或打开任何东西。

**备注：** 请注意，从 Firefox 40 开始，IndexedDB 事务具有宽松的持久性保证以提高性能（请参阅bug 1112702）以前在`readwrite`事务中`IDBTransaction.oncomplete` (en-US)被触发只有当所有数据都保证已刷新到磁盘时。在 Firefox 40+ 中，`complete`事件在操作系统被告知写入数据之后被触发，但可能在该数据实际上被刷新到磁盘之前。该`complete`因此，事件可以比以前更快地传递，但是，如果操作系统崩溃或者在将数据刷新到磁盘之前系统电源丢失，则整个事务将丢失的可能性很小。由于这种灾难性事件很少见，大多数消费者不应该进一步关注自己。如果由于某种原因必须确保持久性（例如，你要存储以后无法重新计算的关键数据），则可以`complete`通过使用实验（非标准）`readwriteflush`模式创建事务来强制事务在传递事件之前刷新到磁盘（请参阅`IDBDatabase.transaction` (en-US)）。

方法
--

继承自：EventTarget

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

在一个单独的线程中关闭数据库连接并立即返回。

`IDBDatabase.createObjectStore()`

创建并返回一个新的 object store 或者 index。

`IDBDatabase.deleteObjectStore()`

根据给定的名字，删除在当前连接的数据库中的 object store 和 相关的索引。

`IDBDatabase.transaction()` (en-US)

立即返回一个包含`IDBTransaction.objectStore` (en-US) 方法的 transaction 对象。你可以用这个对象来操作 object store。这个操作是在一个单独的线程中执行的。

属性
--

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

`DOMString`类型，当前连接数据库名。

`IDBDatabase.version` (en-US) 只读

64-bit (en-US) 整型数，当前连接数据库的版本。当数据第一次被创建时，这个属性是一个空的字符串。

`IDBDatabase.objectStoreNames` (en-US) 只读

`DOMStringList`类型，当前连接连接数据库中所有的 object store 名字列表。

### Event handlers

`IDBDatabase.onabort` (en-US)

在中断数据库访问时触发。

`IDBDatabase.onerror` (en-US)

当访问数据库失败时触发。

`IDBDatabase.onversionchange`

当数据库结构发生更改时触发

(`IDBOpenDBRequest.onupgradeneeded` (en-US)事件或在其他地方请求 `IDBFactory.deleteDatabase` (en-US) 时（最可能在同一台计算机上的另一个窗口/选项卡中）这与版本更改事务（请参阅参考资料`IDBVersionChangeEvent` (en-US)) 不同，但它是相关的。

示例
--

在下面的代码中，异步打开了一个数据库连接 (`IDBFactory`), 并处理成功或者异常事件，如果触发了 upgrade 事件就需要创建一个新的 object store (`IDBdatabase`)。如果想看完整的例子，可以使用 To-do Notifications 应用 (view example live.)

```js
// 我们先打开一个数据库
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

// 当数据库打开出错/成功时，以下两个事件处理程序将分别对 IDBDatabase 对象进行下一步操作
DBOpenRequest.onerror = function (event) {
  note.innerHTML += "<li>Error loading database.</li>";
};

DBOpenRequest.onsuccess = function (event) {
  note.innerHTML += "<li>Database initialised.</li>";

  // 将打开数据库的结果存储在 db 变量中，该变量将在后面的代码中被频繁使用
  db = DBOpenRequest.result;

  // 运行 displayData() 方法，用 IDB 中已经存在的所有待办事项列表数据填充到任务列表中
  displayData();
};

// 当试图打开一个尚未被创建的数据库，或者试图连接一个数据库还没被创立的版本时，onupgradeneeded 事件会被触发

DBOpenRequest.onupgradeneeded = function (event) {
  var db = event.target.result;

  db.onerror = function (event) {
    note.innerHTML += "<li>Error loading database.</li>";
  };

  // 使用 IDBDatabase.createObjectStore 方法，可创建一个对象存储区

  var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" });

  // 定义 objectStore 将包含哪些数据项

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });

  objectStore.createIndex("notified", "notified", { unique: false });

  note.innerHTML += "<li>Object store created.</li>";
};
```

下一行打开数据库上的事务，然后打开一个对象存储，然后我们可以在其中操作数据。

```js
var objectStore = db.transaction("toDoList").objectStore("toDoList");
```

规范
--

| Specification |
| --- |
| Indexed Database API 3.0 # database-interface |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (view example live.)


XMLDocument - Web API 接口参考

XMLDocument
===========

The **XMLDocument** interface represents an XML document. It inherits from the generic `Document` and does not add any specific methods or properties to it: nevertheless, several algorithms behave differently with the two types of documents.

EventTarget

Node

Document

XMLDocument属性
--

*Also inherits properties from: `Document`.*

方法
--

*Also inherits methods from: `Document`.*

规范
--

| Specification |
| --- |
| DOM Standard # xmldocument |

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

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

参见
--

* DOM 接口索引


Barcode Detection API - Web API 接口参考

Barcode Detection API
=====================

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

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

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

Barcode Detection API 可用于检测图像中的条形码和二维码。

概念和用法
-----

Web 应用程序中对条形码识别的支持通过支持的各种条形码格式解锁了各种用例。二维码可用于在线支付、网络导航或建立社交媒体连接，Aztec 码可用于扫描登机牌，购物应用程序可使用 EAN 或 UPC 条形码来比较实物商品的价格。

检测是通过 `detect()` 方法实现的，该方法接受一个图像对象；它可以是以下对象之一：`HTMLImageElement`、`SVGImageElement` (en-US)、`HTMLVideoElement`、`HTMLCanvasElement`、`ImageBitmap`、`OffscreenCanvas`、`VideoFrame` (en-US)、`Blob` 或 `ImageData`。可以将可选参数传递给 `BarcodeDetector` 构造函数，以提供有关要检测的条形码格式的提示。

### 支持的条形码格式

Barcode Detection API 支持以下条形码格式：

| 格式 | 描述 | 图像 |
| --- | --- | --- |
| aztec | 一种遵循 iso24778 的方形二维矩阵，中心有方形牛眼图案，类似于阿兹特克金字塔。不需要周围的空白区域。 | 一个 aztec 条形码的示例图像。一个里面有较小的黑色和白色正方形的正方形 |
| code\_128 | 一种线性（一维）、双向可解码、可自检的条形码，遵循 iso15417 标准，能够对 ASCII 的所有 128 个字符进行编码（因此而得名）。 | 一个 code-128 条形码的图像。一个垂直黑白线的水平布局图案 |
| code\_39 | 一种遵循 iso16388 的线性（一维）可自检的条形码。它是一种离散且可变长度的条形码类型。 | 一个 code-39 条形码的图像。一个垂直黑白线的水平布局图案 |
| code\_93 | 一种 BC5 之后的可变长度的线性连续符号系统。它提供比 Code 128 和视觉上相似的 Code 39 更大的信息密度。Code 93 主要由加拿大邮政用来对补充的投递信息进行编码。 | 一个 code 93 条形码的图像。一个垂直黑白线的水平布局图案 |
| codabar | 一种表示字符 0-9、A-D 和符号 - . $ / + 的线性条形码。 | 一个 codabar 格式条形码的图像。一个黑白垂直线的水平布局团 |
| data\_matrix | 一种与方向无关的二维码，由按照 ISO16022 标准排列成正方形或矩形图案的黑白模块组成。 | 一个数据矩阵条形码的示例。一个由较小的黑色和白色方块填充的正方形 |
| ean\_13 | 一种基于 UPC-A 标准并在 iso15420 中定义的线性条形码。 | 一个 EAN-13 格式条形码的图像。一个白色和黑色线条的水平布局的图案 |
| ean\_8 | 一种在 ISO15420 中定义并源自 EAN-13 的线性条形码。 | 一个 EAN-8 格式条形码的图像。一个垂直黑白线的水平布局的图案 |
| itf | 一种连续、自检、双向可解码的条形码。它始终编码 14 位数字。 | 一个 ITF 条形码的图像。一个白色和黑色线条的水平布局图案 |
| pdf417 | 一种具有多行和多列的连续二维条形码符号格式。它可双向解码并且使用 iso15438 标准。 | 一个 pdf417 条形码格式的示例。一个由较小的黑白正方形组成的矩形 |
| qr\_code | 一种采用 iso18004 标准的二维条形码。编码的信息可以是文本、URL 或其他数据。 | 一个二维码的示例。一个由较小的黑色和白色正方形组成的正方形 |
| upc\_a | 最常见的线性条形码类型之一，广泛应用于美国的零售业。在 iso15420 中定义，它通过条带和空格来表示数字，每个数字都与 2 个条块和 2 个空格的独特模式相关联，两者的宽度都是可变的。UPC-A 可以编码唯一分配给每个项目的 12 位数字，从技术上讲，它是 EAN-13 的子集（UPC-A 代码在 EAN-13 中表示，第一个字符设置为 0）。 | 一个 upc-a 条形码的图像。一个由黑白垂直线组成且下方有数字的矩形 |
| upc\_e | 一种 iso15420 中定义的 UPC-A 的变体，压缩掉不必要的零以获得更紧凑的条形码。 | 一个 upc-e 条形码的图像。一个由黑白垂直线组成的矩形 |
| unknown | 平台使用此值来表示它不知道或未指定目前正在检测或支持的条形码格式。 |  |

你可以通过 `getSupportedFormats()` 方法检查用户代理支持的格式。

接口
--

`BarcodeDetector`
实验性

Barcode Detection API 的 `BarcodeDetector` 接口允许检测图像中的条形码和二维码。

示例
--

### 创建检测器

此示例测试浏览器兼容性并使用指定的支持格式创建新的条形码检测器对象。

```js
// 检查兼容性
if (!("BarcodeDetector" in globalThis)) {
  console.log("此浏览器不支持条形码检测器。");
} else {
  console.log("条形码检测器是支持的！");

  // 创建新检测器
  const barcodeDetector = new BarcodeDetector({
    formats: ["code\_39", "codabar", "ean\_13"],
  });
}
```

### 获取支持的格式

以下示例调用 `getSupportedFormats()` 方法并将结果记录到控制台。

```js
// 检查支持的类型
BarcodeDetector.getSupportedFormats().then((supportedFormats) => {
  supportedFormats.forEach((format) => console.log(format));
});
```

### 检测条形码

此示例使用 `detect()` 方法来检测给定图像中的条形码。识别结果被迭代并且条形码数据被记录到控制台。

```js
barcodeDetector
  .detect(imageEl)
  .then((barcodes) => {
    barcodes.forEach((barcode) => console.log(barcode.rawValue));
  })
  .catch((err) => {
    console.log(err);
  });
```

规范
--

| Specification |
| --- |
| Accelerated Shape Detection in Images # barcode-detection-api |

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

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

参见
--

* barcodefaq.com：包含有关不同条形码和不同类型示例的信息的网站。
* Shape Detection API：一张图片胜过一千个单词、人脸和条形码


OfflineAudioContext - Web API 接口参考

OfflineAudioContext
===================

`OfflineAudioContext` 接口是一个 `AudioContext` 的接口，代表由多个 `AudioNode` 连接在一起构成的音频处理图。与 `AudioContext` 标准相反的是， `OfflineAudioContext` 不在硬件设备渲染音频；相反，它尽可能快地生成音频，输出一个 `AudioBuffer` 作为结果。

构造函数
----

`OfflineAudioContext.OfflineAudioContext()`

创建一个新的 `OfflineAudioContext` 实例。

属性
--

*从父级 `AudioContext` 获取属性。*

`OfflineAudioContext.length` 只读

代表采样帧缓冲区大小的整数。

### 事件处理程序

`OfflineAudioContext.oncomplete` (en-US)

当进程完成时，基于事件版本的`OfflineAudioContext.startRendering()` (en-US) 被使用之后，事件处理器将会被调用，`complete` 事件类型为 `OfflineAudioCompletionEvent` (en-US)）被触发。

方法
--

*从父级 `AudioContext` 和 `EventTarget` 获取方法的实现。*

`OfflineAudioContext.resume()` (en-US)

恢复一个被暂停的音频的时间进程。

`OfflineAudioContext.suspend()`

在指定的时间安排音频暂停时间进程，并且通过 Promise 返回。

`OfflineAudioContext.startRendering()` (en-US)

开始渲染音频，考虑当前连接和当前计划的修改。这个页面涵盖基于事件的和基于 Promise 的版本。

示例
--

这个简单的例子中，我们声明了 `AudioContext` 和 `OfflineAudioContext` 对象。我们使用 `AudioContext` 去加载一个 XHR（`AudioContext.decodeAudioData`）获取的音轨，然后使用 `OfflineAudioContext` 去渲染音频并得到一个 into an `AudioBufferSourceNode`，并播放这个音轨。在离线音频处理图建立后，你需要去使用 `OfflineAudioContext.startRendering` (en-US) 来渲染它成为 `AudioBuffer`。

当 `startRendering()` 的 `Promise` 解决后，渲染也完成了，在 `Promise` 内可以获得输出的 `AudioBuffer`。

在此刻，我们创建了一个另外的音频上下文，在它里面创建了一个 `AudioBufferSourceNode`，并且设置它的 buffer 为之前生成的 Promise 中的 `AudioBuffer。这样它就可以作为简单标准音频图来播放了`。

**备注：** 为了获取可以运行的例子，请看我们在 Github 的仓库 offline-audio-context-promise （也可以看到 源代码。）

```js
// 定义一个在线或者离线的音频上下文

var audioCtx = new AudioContext();
var offlineCtx = new OfflineAudioContext(2, 44100 \* 40, 44100);

source = offlineCtx.createBufferSource();

// 使用 XHR 去加载一个音轨，
// 使用 decodeAudioData 去解码，
// 使用 OfflineAudioContext 去渲染它

function getData() {
  request = new XMLHttpRequest();

  request.open("GET", "viper.ogg", true);

  request.responseType = "arraybuffer";

  request.onload = function () {
    var audioData = request.response;

    audioCtx.decodeAudioData(audioData, function (buffer) {
      myBuffer = buffer;
      source.buffer = myBuffer;
      source.connect(offlineCtx.destination);
      source.start();
      //source.loop = true;
      offlineCtx
        .startRendering()
        .then(function (renderedBuffer) {
          console.log("渲染完全成功");
          var audioCtx = new (window.AudioContext ||
            window.webkitAudioContext)();
          var song = audioCtx.createBufferSource();
          song.buffer = renderedBuffer;

          song.connect(audioCtx.destination);

          play.onclick = function () {
            song.start();
          };
        })
        .catch(function (err) {
          console.log("渲染失败：" + err);
          // 注意：当 OfflineAudioContext 上 startRendering 被立刻调用，Promise 应该被 reject
        });
    });
  };

  request.send();
}

// 运行 getData 去开始这个进程

getData();
```

规范
--

| Specification |
| --- |
| Web Audio API # OfflineAudioContext |

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

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

参见
--

* Web Audio API 的运用


Screen - Web API 接口参考

Screen
======

`Screen` 接口表示一个屏幕窗口，往往指的是当前正在被渲染的 window 对象，可以使用 `window.screen` 获取它。

请注意：由浏览器决定提供屏幕对象，此对象一般通过当前浏览器窗口活动状态动态检测来得到。

属性
--

`Screen.availTop`

Specifies the y-coordinate of the first pixel that is not allocated to permanent or semipermanent user interface features.

`Screen.availLeft`

返回屏幕左边边界的第一个像素点

`Screen.availHeight`

Specifies the height of the screen, in pixels, minus permanent or semipermanent user interface features displayed by the operating system, such as the Taskbar on Windows.

`Screen.availWidth`

返回窗口中水平方向可用空间的像素值。

`Screen.colorDepth`

返回屏幕的色彩深度。

`Screen.height`

以像素为单位返回屏幕的高度。

`Screen.left` (en-US)

返回从最左边界到当前屏幕的像素值。

`Screen.orientation`

返回当前屏幕的转向。

`Screen.pixelDepth`

获取屏幕的像素点

`Screen.top` (en-US)

返回最上边界到当前屏幕的像素值。

`Screen.width`

返回屏幕的宽度。

`Screen.mozEnabled` (en-US)

布尔值。如果设置为 false 将关闭设备的屏幕。

`Screen.mozBrightness` (en-US)

控制设备屏幕的亮度。期望参数是 0-1.0 之间的浮点数。

### Events handler

`Screen.onorientationchange` (en-US)

对`orientationchange` 事件的时间处理器。

方法
--

*方法继承自其父接口 `EventTarget`。*

`Screen.lockOrientation`
已弃用

锁定屏幕转向（仅在全屏或者已安装的 APP 中生效）

`Screen.unlockOrientation` (en-US)
已弃用

解锁屏幕转向（仅在全屏或者已安装的 APP 中生效）

示例
--

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

规范
--

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

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

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


SubtleCrypto - Web API 接口参考

SubtleCrypto
============

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

Web Crypto API 的 **`SubtleCrypto`** 接口提供了许多底层加密函数。你可以通过 `crypto` 属性提供的 `Crypto` 对象中的 `subtle` 属性来访问 `SubtleCrypto` 的相关特性。

**警告：** 此 API 提供了许多底层密码学原语。滥用它们很容易陷入微妙的陷阱中。

即使你正确地运用了基础加密方法，也很难设计一套正确的安全密钥管理及整体安全设计方案，这些往往是安全专家所做的事情。

错误的安全系统设计和实现会使系统的安全性完全失效。

你可以学习并进行实验，但我们并不能保证这些内容的安全性，最好有熟悉该领域的人对你的相关工作进行彻底的审查以保证其安全性。如果你要学习安全系统的设计和部署，可以学习 Crypto 101 课程。

实例属性
----

*此接口没有任何父接口，因此没有继承任何属性。*

实例方法
----

*此接口没有任何父接口，因此没有继承任何方法。*

`SubtleCrypto.encrypt()`

返回一个 `Promise`，会兑现与参数中给定的明文、算法和密钥对应的密文。

`SubtleCrypto.decrypt()`

返回一个 `Promise`，会兑现与参数中给定的密文、算法和密钥对应的明文。

`SubtleCrypto.sign()`

返回一个 `Promise`，会兑现与参数中给定的文本、算法和密钥对应的签名。

`SubtleCrypto.verify()`

返回一个 `Promise`，会兑现一个布尔值，表示参数中给定的签名是否与文本、密钥和算法对应的签名相匹配。

`SubtleCrypto.digest()`

返回一个 `Promise`，会兑现通过参数中给定的算法和文本生成的摘要。

`SubtleCrypto.generateKey()`

返回一个 `Promise`，会兑现一个新生成的密钥（用于对称加密算法）或密钥对 (en-US)（用于非对称加密算法）。它们与通过参数给定的算法、用法和可导出性相对应。

`SubtleCrypto.deriveKey()`

返回一个 `Promise`，会兑现一个新生成的、从主密钥（以过参数给定的算法）派生出来的密钥。

`SubtleCrypto.deriveBits()`

返回一个 `Promise`，会兑现一个新生成的、从主密钥（以通过参数给定的算法）派生出来的伪随机比特序列。

`SubtleCrypto.importKey()`

返回一个 `Promise`，会兑现一个新生成的密钥，该密钥与通过参数给定的密钥格式、算法、原始密钥数据、用法和可导出性相对应。

`SubtleCrypto.exportKey()`

返回一个 `Promise`，会兑现一个包含所请求格式的密钥的原始密钥数据。

`SubtleCrypto.wrapKey()`

返回一个 `Promise`，会兑现一个包装的对称密钥，该密钥可在不安全的环境中使用（传输、存储）。该密钥与通过参数给定的格式相匹配，并使用制定的算法来包装给定的密钥。

`SubtleCrypto.unwrapKey()`

返回一个 `Promise`，会兑现一个与通过参数给定的包装密钥（wrapped key）对应的密钥。

使用 SubtleCrypto
---------------

我们可以将此 API 的实现函数分为两类：加密函数和密钥管理函数。

### 加密函数

这些函数你可以用来实现系统中的隐私和身份验证等安全特性。`SubtleCrypto` API 提供了如下加密函数：

* `sign()` 和 `verify()`：创建和验证数字签名。
* `encrypt()` 和 `decrypt()`：加密和解密数据。
* `digest()`：生成某些数据的定长、防碰撞的消息摘要。
### 密钥管理函数

除了 `digest()`，`SubtleCrypto` API 中所有加密函数都会使用密钥，并使用 `CryptoKey` 对象表示加密密钥。要执行签名和加密操作，请将 `CryptoKey` 对象传参给 `sign()` 或 `encrypt()` 函数。

#### 生成和派生密钥

`generateKey()` 和 `deriveKey()` 函数都可以创建一个新的 `CryptoKey` 对象。

不同之处在于 `generateKey()` 每次都会生成一个新的键值对，而 `deriveKey()` 通过基础密钥资源派生一个新的密钥。如果为两个独立的 `deriveKey()` 函数调用提供相同的基础密钥资源，那么你会获得两个具有相同基础值的 `CryptoKey` 对象。如果你想通过密码派生加密密钥，然后从相同的密码派生相同的密钥以解密数据，那么这将会非常有用。

#### 导入和导出密钥

要在应用程序外部使密钥可用，你需要导出密钥，`exportKey()` 可以为你提供该功能。你可以选择多种导出格式。

`importKey()` 与 `exportKey()` 刚好相反。你可以从其他系统导入密钥，并且支持像 PKCS #8 和 JSON Web Key 这样可以帮助你执行此操作的标准格式。`exportKey()` 函数以非加密格式导出密钥。

如果密钥是敏感的，你应该使用 `wrapKey()`，该函数导出密钥并且使用另外一个密钥加密它。此类 API 调用被称为“密钥包装密钥”（key-wrapping key）。

`unwrapKey()` 与 `wrapKey()` 相反，该函数解密密钥后导入解密的密钥。

#### 存储密钥

`CryptoKey` 对象可以通过结构化克隆算法来存储，这意味着你可以通过 web storage API 来存储和获取它们。更为规范的方式是通过使用 IndexedDB API 来存储 `CryptoKey` 对象。

### 支持的算法

Web Crypto API 提供的加密函数可以由一个或多个不同的*加密算法*执行：函数可以通过 `algorithm` 参数来指定使用的算法。一些算法需要额外的参数，在这些情况下可以将 `algorithm` 参数作为对象字典传入额外的参数。

下表总结了哪些算法适用于哪些加密操作：

|  | sign()verify() | encrypt()decrypt() | digest() | deriveBits()deriveKey() | wrapKey()unwrapKey() |
| --- | --- | --- | --- | --- | --- |
| RSASSA-PKCS1-v1\_5 | ✓ |  |  |  |  |
| RSA-PSS | ✓ |  |  |  |  |
| ECDSA | ✓ |  |  |  |  |
| HMAC | ✓ |  |  |  |  |
| RSA-OAEP |  | ✓ |  |  | ✓ |
| AES-CTR |  | ✓ |  |  | ✓ |
| AES-CBC |  | ✓ |  |  | ✓ |
| AES-GCM |  | ✓ |  |  | ✓ |
| SHA-1 |  |  | ✓ |  |  |
| SHA-256 |  |  | ✓ |  |  |
| SHA-384 |  |  | ✓ |  |  |
| SHA-512 |  |  | ✓ |  |  |
| ECDH |  |  |  | ✓ |  |
| HKDF |  |  |  | ✓ |  |
| PBKDF2 |  |  |  | ✓ |  |
| AES-KW |  |  |  |  | ✓ |

规范
--

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

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

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

参见
--

* Web Crypto API
* SubtleCrypto 的非加密用途 (en-US)
* Web 安全
* 隐私、权限和信息安全 (en-US)
* `Crypto` 和 `Crypto.subtle`。
* Crypto 101：密码学入门课程。


Console API - Web API 接口参考

Console API
===========

Console API 提供了允许开发人员执行调试任务的功能，例如在代码中的某个位置记录消息或变量值，或者计算任务完成所需的时间。

概念和用法
-----

Console API 最初是一个专有的 API，不同的浏览器以自己的实现方式来实现它。Console API 规范统一了这个 API 的行为，并且所有现代浏览器最终都决定实现这种行为 — 尽管一些实现仍然有自己的附加专有功能。了解这些请查看：

* Google Chrome DevTools implementation
* Safari DevTools implementation

用法非常简单 — `console` 对象 — 可以通过`window.console`获取到，在 workers 里面使用`WorkerGlobalScope.console` (en-US)获取，`console` — 包含许多方法，你可以调用它们来执行基本的调试任务，通常专注于将各种值记录到浏览器中 WEB 控制台.

到目前为止，最常用的方法是 console.log，它用于记录特定变量中包含的当前值。

接口
--

`console`

提供基本的调试功能，包括日志记录，堆栈跟踪，计时器和计数器。

示例
--

```js
let myString = "Hello world";

// Output "Hello world" to the console
console.log(myString);
```

到Console reference page查看更多示例

规范
--

| Specification |
| --- |
| Console Standard # console-namespace |

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

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

参见
--

* Tools
* Web Console — how the Web Console in Firefox handles console API calls
* Remote debugging — how to see console output when the debugging target is a mobile device


MessageEvent - Web API 接口参考

MessageEvent
============

**`MessageEvent`** 是接口代表一段被目标对象接收的消息。

用来代表下列情况的消息

* Server-sent events (参见`EventSource.onmessage` (en-US)).
* Web sockets (参见 WebSocket 接口的 `onmessage` 属性).
* Cross-document messaging (参见 `Window.postMessage()` 和 `Window.onmessage`).
* Channel messaging (参见 `MessagePort.postMessage()` (en-US) 和`MessagePort.onmessage`).
* Cross-worker/document messaging (参见上面两个入口，还有 `Worker.postMessage()`, `Worker.onmessage`, `ServiceWorkerGlobalScope.onmessage` (en-US), 等等.)
* Broadcast channels (参见 `Broadcastchannel.postMessage()`) 和 `BroadcastChannel.onmessage`).
* WebRTC data channels (参见 `RTCDataChannel.onmessage` (en-US)).

通过这个事件触发的动作被定义为一个函数，该函数作为相关`message`事件 (例如使用前文所列的`onmessage` 处理器) 的事件处理器。

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

构造函数
----

`MessageEvent()`

创建一个新的 **消息事件** 。

属性
--

*继承其父类 `Event` 的属性。*

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

返回 `DOMString`, `Blob` 或者 `ArrayBuffer`，包含来自发送者的数据。

`MessageEvent.origin` (en-US)

返回一个表示消息发送者来源的`USVString`

`MessageEvent.lastEventId` (en-US) 只读

`DOMString` representing a unique ID for the event.

`MessageEvent.source` (en-US)

`MessageEventSource` (可以是 `WindowProxy`, `MessagePort`, 或 `ServiceWorker` 对象) 代表消息发送者。

`MessageEvent.ports` (en-US)

`MessagePort`对象数组，表示消息正通过特定通道（数据通道）发送的相关端口（适用于通道消息传输或者向一个共享线程（shared work）发送消息时）。

方法
--

*继承父类 `Event` 的方法。*

`MessageEvent.initMessageEvent()`
已弃用

**不要再使用**: 使用 `MessageEvent()`。

示例
--

在我们的基础共享线程示例 Basic shared worker example (run shared worker) 中，我们有两个 HTML 页，每一页都用简单的 js 代码去执行简单的计算。不同的脚本使用同一个 worker 文件去执行计算 — 它们都可以访问那个 worker 文件，即使它们（scripts）运行在不同的窗口。

下面的代码片段展示了使用`SharedWorker()`构造器创建一个 `SharedWorker`对象。

```js
var myWorker = new SharedWorker("worker.js");
```

接下来两份脚本通过一个`SharedWorker.port` (en-US)方法创建的`MessagePort`对象访问 worker。如果 onmessage 事件通过 addEventListener 被绑定，端口可以用`start()`方法手动开启：

```js
myWorker.port.start();
```

当端口被打开，两份脚本各自都可用 `port.postMessage()` 向 worker 传消息并用 `port.onmessage`处理它（worker）传来的消息：

```js
first.onchange = function () {
  myWorker.port.postMessage([first.value, second.value]);
  console.log("Message posted to worker");
};

second.onchange = function () {
  myWorker.port.postMessage([first.value, second.value]);
  console.log("Message posted to worker");
};

myWorker.port.onmessage = function (e) {
  result1.textContent = e.data;
  console.log("Message received from worker");
};
```

在 worker 内部我们使用 `SharedWorkerGlobalScope.onconnect` (en-US) 处理器来连接前文说到相同端口。与 worker 相关联的端口可以在 `connect` (en-US) 事件的 `ports` 属性中访问到——接着我们使用 `MessagePort` `start()` 方法打开端口，`onmessage` 处理器来处理主线程传来的消息。

```js
onconnect = function (e) {
  var port = e.ports[0];

  port.addEventListener("message", function (e) {
    var workerResult = "Result: " + e.data[0] \* e.data[1];
    port.postMessage(workerResult);
  });

  port.start(); // Required when using addEventListener. Otherwise called implicitly by onmessage setter.
};
```

规范
--

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

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

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


HTML DOM API - Web API 接口参考

HTML DOM API
============

**HTML DOM API** 由一系列接口组成，它们定义了 HTML 中每个元素的功能，以及它们所依赖的任何支持类型和接口。

HTML DOM API 的功能包括：

* 通过 DOM 访问和控制 HTML 元素。
* 访问和操作表单数据。
* 与 2D 图像的内容，以及 HTML `<canvas>` 元素的上下文进行交互，例如在其上绘制。
* 管理连接到 HTML 媒体元素的媒体（`<audio>` 和 `<video>`）。
* 在网页上拖放内容。
* 访问浏览器导航历史记录。
* 支持和关联其他 API 的接口，例如 Web 组件、Web Storage、Web Worker、WebSocket 和 Server-sent 事件。
HTML DOM 概念和用法
--------------

在本文中，我们将重点关注与 HTML 元素交互的 HTML DOM 部分。其他领域的讨论，例如拖放、WebSocket、Web Storage 等，可以在这些 API 的文档中找到。

### HTML 文档的结构

文档对象模型（DOM）是一种描述文档结构的架构；每个文档都由 `Document` 接口的实例表示。而一个文档则由**节点**层次树组成，其中每个节点，都代表文档中单个对象（如元素或文本节点）的基本记录。

节点可以组织文档结构，提供将其他节点分组，以及构建层级结构的点的方法。其他节点可能代表文档的可见组件。每个节点都基于 `Node` 接口，该接口提供了获取有关节点信息，以及创建、删除和组织 DOM 中节点的方法。

节点本身不包含实际显示在文档中的内容，它们是空容器。节点呈现视觉内容的能力，是由 `Element` 接口引入的。一个 `Element` 对象实例，代表着使用 HTML 或 SVG 等 XML 词汇创建的文档中的单个元素。

例如，考虑一个包含两个元素的文档，其中一个元素内嵌了另外两个元素：

![窗口中，内部包含元素的文档结构](/zh-CN/docs/Web/API/HTML_DOM_API/dom-structure.svg)

虽然 `Document` 接口是作为 DOM 规范的一部分定义的，但 HTML 规范显著增强了它，添加了特定于 Web 浏览器上下文中，使用 DOM 以及表示 HTML 文档的信息。

HTML 标准添加到 `Document` 中的内容包括：

* 在加载页面时，支持访问 HTTP 标头提供的各种信息，例如文档加载的位置、cookie、修改日期、引用站点等。
* 可以访问文档 `<head>` 块和 body 中元素的列表，以及包含在文档中的图像、链接、脚本等列表。
* 支持通过检查焦点和对可编辑内容执行命令来与用户交互。
* HTML 标准定义的文档事件处理器，允许访问鼠标和键盘事件、拖放、媒体控制等。
* 可以传递到元素和文档的事件处理器；目前仅包括复制、剪切和粘贴操作。
### HTML 元素接口

通过引入 `HTMLElement` 接口，`Element` 接口被进一步调整为专门表示 HTML 元素，所有更具体的 HTML 元素类都继承自它。这扩展了 `Element` 类，以向元素节点添加了特定于 HTML 的通用特性。`HTMLElement` 添加的属性包括 `hidden` 和 `innerText` 等。

HTML 文档是 DOM 树，其中每个节点都是一个由 `HTMLElement` 接口表示的 HTML 元素。`HTMLElement` 类实现了 `Node`，因此每个元素也是一个节点（但反过来不成立）。这样，由 `Node` 接口实现的结构特性也可用于 HTML 元素中，允许它们相互嵌套、创建和删除、移动等。

`HTMLElement` 接口是通用的，但是它仅提供所有 HTML 元素共有的功能，例如元素的 ID、坐标、构成元素的 HTML 代码、滚动位置等信息。

为了扩展核心 `HTMLElement` 接口的功能，以提供特定元素所需的特性，`HTMLElement` 类被子类化以添加所需的属性和方法。例如，`<canvas>` 元素由类型为 `HTMLCanvasElement` 的对象表示。`HTMLElement` 通过添加诸如 `height` 等属性和 `getContext()` 等方法来增强 `HTMLElement` 类型，从而提供特定于 canvas 的特性。

HTML 元素类的总体继承关系如下：

![HTML 元素的接口层次结构](/zh-CN/docs/Web/API/HTML_DOM_API/html-dom-hierarchy.svg)

因此，元素继承其所有祖先的属性和方法。例如，考虑 `<a>` 元素，在 DOM 中由类型为 `HTMLAnchorElement` (en-US) 的对象表示。元素包括了该类文档中，`Anchor` 特定的属性和方法。但也包括 `HTMLElement`、`Element` 以及 `Node` 定义的内容，最后是 `EventTarget` 定义的内容。

每一层级都定义了元素实用性的一个关键方面。从 `Node` 开始，该元素继承了有关该元素能否被另一个元素包含，以及自身包含其他元素的概念。特别重要的是从 `EventTarget` 继承的：接收和处理事件（如鼠标点击、播放和暂停事件等）的能力。

有一些元素具有共性，因此还有一个额外的中介类型。例如，`<audio>` 和 `<video>` 元素都呈现音视频媒体。相应的 `HTMLAudioElement` 和 `HTMLVideoElement` 类型都基于通用类型 `HTMLMediaElement`，后者又基于 `HTMLElement` 等等。`HTMLMediaElement` 定义了音频和视频元素之间共同拥有的方法和属性。

这些特定于元素的接口构成了大部分 HTML DOM API，并且是本文的重点。要了解 DOM 的实际结构，请参阅 DOM 概述。

HTML DOM 的目标受众
--------------

HTML DOM 所暴露的特性是 web 开发人员工具箱中最常用的 API 之一。除了最简单的 web 应用程序外，几乎所有 web 应用程序都会使用 HTML DOM 的某些特性。

HTML DOM API 接口
---------------

HTML DOM API 中的大多数接口，几乎一对一地映射到单个 HTML 元素，或是类似功能的少量元素组。此外，HTML DOM API 还包括一些接口和类型，以支持 HTML 元素接口。

### HTML 元素接口

这些接口代表特定的 HTML 元素（或者属性、方法与它们相关、相同的元素）。

* `HTMLAnchorElement` (en-US)
* `HTMLAreaElement`
* `HTMLAudioElement`
* `HTMLBaseElement`
* `HTMLBodyElement`
* `HTMLBRElement`
* `HTMLButtonElement`
* `HTMLCanvasElement`
* `HTMLDataElement` (en-US)
* `HTMLDataListElement` (en-US)
* `HTMLDetailsElement`
* `HTMLDialogElement`
* `HTMLDirectoryElement`
* `HTMLDivElement`
* `HTMLDListElement` (en-US)
* `HTMLElement`
* `HTMLEmbedElement` (en-US)
* `HTMLFieldSetElement`
* `HTMLFormElement`
* `HTMLHRElement` (en-US)
* `HTMLHeadElement`
* `HTMLHeadingElement` (en-US)
* `HTMLHtmlElement`
* `HTMLIFrameElement`
* `HTMLImageElement`
* `HTMLInputElement`
* `HTMLLabelElement` (en-US)
* `HTMLLegendElement` (en-US)
* `HTMLLIElement`
* `HTMLLinkElement` (en-US)
* `HTMLMapElement` (en-US)
* `HTMLMediaElement`
* `HTMLMenuElement` (en-US)
* `HTMLMetaElement` (en-US)
* `HTMLMeterElement` (en-US)
* `HTMLModElement` (en-US)
* `HTMLObjectElement` (en-US)
* `HTMLOListElement` (en-US)
* `HTMLOptGroupElement`
* `HTMLOptionElement`
* `HTMLOutputElement` (en-US)
* `HTMLParagraphElement`
* `HTMLPictureElement` (en-US)
* `HTMLPreElement` (en-US)
* `HTMLProgressElement` (en-US)
* `HTMLQuoteElement` (en-US)
* `HTMLScriptElement`
* `HTMLSelectElement` (en-US)
* `HTMLSlotElement`
* `HTMLSourceElement` (en-US)
* `HTMLSpanElement`
* `HTMLStyleElement`
* `HTMLTableCaptionElement` (en-US)
* `HTMLTableCellElement` (en-US)
* `HTMLTableColElement` (en-US)
* `HTMLTableElement`
* `HTMLTableRowElement` (en-US)
* `HTMLTableSectionElement` (en-US)
* `HTMLTemplateElement`
* `HTMLTextAreaElement`
* `HTMLTimeElement` (en-US)
* `HTMLTitleElement` (en-US)
* `HTMLTrackElement` (en-US)
* `HTMLUListElement` (en-US)
* `HTMLUnknownElement`
* `HTMLVideoElement`

#### 废弃的 HTML 元素接口

* `HTMLMarqueeElement` (en-US)
已弃用

#### 过时的 HTML 元素接口

* `HTMLFontElement` (en-US)
已弃用
* `HTMLFrameElement`
已弃用
* `HTMLFrameSetElement` (en-US)
已弃用
* `HTMLIsIndexElement`
已弃用
* `HTMLMenuItemElement` (en-US)
已弃用
### Web 应用程序和浏览器集成接口

这些接口提供了访问包含 HTML 的浏览器窗口和文档的方式，以及访问浏览器状态、可用插件（如果有）和各种配置选项的方式。

* `BarProp` (en-US)
* `Navigator`
* `Window`

#### 废弃的 Web 应用程序和浏览器集成接口

* `External`
已弃用

#### 过时的 Web 应用程序和浏览器集成接口

* `ApplicationCache`
已弃用
* `Plugin`
已弃用
* `PluginArray` (en-US)
已弃用
### 表单支持接口

这些接口提供了创建和管理表单所需的结构和功能，包括 `<form>` 和 `<input>` 元素。

* `FormDataEvent` (en-US)
* `HTMLFormControlsCollection` (en-US)
* `HTMLOptionsCollection` (en-US)
* `RadioNodeList` (en-US)
* `ValidityState`
### Canvas 和图像接口

这些接口代表了 Canvas API 以及 `<img>` 元素和 `<picture>` 元素使用的对象。

* `CanvasGradient`
* `CanvasPattern`
* `CanvasRenderingContext2D`
* `ImageBitmap`
* `ImageBitmapRenderingContext`
* `ImageData`
* `OffscreenCanvas`
* `OffscreenCanvasRenderingContext2D` (en-US)
* `Path2D`
* `TextMetrics`
### 媒体接口

媒体接口提供对媒体元素（`<audio>` 和 `<video>`）内容的 HTML 访问。

* `AudioTrack`
* `AudioTrackList` (en-US)
* `MediaError` (en-US)
* `TextTrack` (en-US)
* `TextTrackCue` (en-US)
* `TextTrackCueList` (en-US)
* `TextTrackList` (en-US)
* `TimeRanges`
* `TrackEvent` (en-US)
* `VideoTrack` (en-US)
* `VideoTrackList` (en-US)
### 拖放接口

这些接口被 HTML 拖放 API 用于表示单个或一组可拖动（或已拖动）元素，并处理拖放过程。

* `DataTransfer`
* `DataTransferItem`
* `DataTransferItemList`
* `DragEvent`
### 页面历史接口

History API 接口允许你访问有关浏览器历史记录的信息，并通过历史记录将浏览器的当前标签页向前或向后跳转。

* `BeforeUnloadEvent`
* `HashChangeEvent`
* `History`
* `Location`
* `PageTransitionEvent`
* `PopStateEvent` (en-US)
### Web 组件接口

这些接口被 Web 组件 API 用于创建和管理可用的自定义元素。

* `CustomElementRegistry`
### 杂项和支持接口

这些支持对象类型在 HTML DOM API 中以各种方式被使用。此外，`PromiseRejectionEvent` 表示当 JavaScript `Promise` 被拒绝时传递的事件。

* `DOMStringList`
* `DOMStringMap`
* `ErrorEvent`
* `HTMLAllCollection` (en-US)
* `MimeType`
* `MimeTypeArray` (en-US)
* `PromiseRejectionEvent`
### 属于其他 API 的接口

有几个接口在 HTML 规范中在技术上被定义，但实际上是其他 API 的一部分。

#### Web Storage 接口

Web Storage API 提供了网站在用户设备上临时或永久存储数据以便后续复用的能力。

* `Storage`
* `StorageEvent`

#### Web Worker 接口

这些接口被 Web Worker API 用于建立 Worker 与应用及其内容交互的能力，同时也支持窗口或应用之间的消息传递。

* `BroadcastChannel`
* `DedicatedWorkerGlobalScope`
* `MessageChannel`
* `MessageEvent`
* `MessagePort`
* `SharedWorker`
* `SharedWorkerGlobalScope` (en-US)
* `Worker`
* `WorkerGlobalScope` (en-US)
* `WorkerLocation` (en-US)
* `WorkerNavigator` (en-US)

#### WebSocket 接口

这些接口由 HTML 规范定义，被 WebSocket API 使用。

* `CloseEvent`
* `WebSocket`

#### Server-sent 事件接口

`EventSource` 接口表示发送或正在发送 server-sent 事件的源。

* `EventSource`
示例
--

在这个示例中，`<input>` 元素的 `input` 事件被监听，以便根据给定字段当前是否有值，来更新表单“提交”按钮的状态。

### JavaScript

```js
const nameField = document.getElementById("userName");
const sendButton = document.getElementById("sendButton");

sendButton.disabled = true;
// [提示：这是被禁用的，因为它会导致文章始终加载此示例，并将其聚焦和滚动到视图中]
//nameField.focus();

nameField.addEventListener("input", (event) => {
  const elem = event.target;
  const valid = elem.value.length != 0;

  if (valid && sendButton.disabled) {
    sendButton.disabled = false;
  } else if (!valid && !sendButton.disabled) {
    sendButton.disabled = true;
  }
});
```

这段代码使用 `Document` 接口的 `getElementById()` 方法，获取 ID 为 `userName` 和 `sendButton` 的 `<input>` 元素的 DOM 对象。通过这些对象，我们可以访问提供信息的属性和方法，并获得对这些元素的控制权。

“发送”按钮的 `HTMLInputElement` 对象的 `disabled` (en-US) 属性被设置为 `true`，这将禁用“发送”按钮，使其无法点击。此外，通过调用继承自 `HTMLElement` 的 `focus()` (en-US) 方法，用户名输入字段成为活动焦点。

然后调用 `addEventListener()` 来为用户名输入添加一个 `input` 事件的处理器。这段代码检测当前输入值的长度；如果它是零，则禁用“发送”按钮（如果尚未禁用）。否则，该代码确保按钮已启用。

有了这个设置，只要用户名输入框中有值，“发送”按钮就会一直处于启用状态，当为空时则禁用。

### HTML

表单的 HTML 如下：

```html
<p>请提供以下信息。标有“*”的项目为必填项。</p>
<form action="" method="get">
  <p>
    <label for="userName" required>用户名：</label>
    <input type="text" id="userName" /> (*)
  </p>
  <p>
    <label for="email">邮箱：</label>
    <input type="email" id="userEmail" />
  </p>
  <input type="submit" value="发送" id="sendButton" />
</form>
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # htmlelement |

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

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

参见
--

### 参考

* HTML 元素参考
* HTML 属性参考
* 文档对象模型（DOM）参考
### 指南

* 操作文档：操作 DOM 的入门指南。


DocumentFragment - Web API 接口参考

DocumentFragment
================

**`DocumentFragment`**，文档片段接口，表示一个没有父对象的最小文档对象。

它被作为一个轻量版的 `Document` 使用，就像标准的 document 一样，存储由节点（nodes）组成的文档结构。与 document 相比，最大的区别是它不是真实 DOM 树的一部分，它的变化不会触发 DOM 树的重新渲染，且不会对性能产生影响。

EventTarget

Node

DocumentFragment构造函数
----

`DocumentFragment()`

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

属性
--

*该接口没有特殊的属性，其属性都继承自 `Node`。*

`DocumentFragment.childElementCount` (en-US) 只读

返回所有属于 `DocumentFragment` 的 `Element` 类型的子对象。

`DocumentFragment.children` (en-US) 只读

返回一个实时的 `HTMLCollection`，其中包含了所有属于 `DocumentFragment` 的 `Element` 类型的子对象。

`ParentNode.firstElementChild` (en-US) 只读

返回 `DocumentFragment` 的第一个 `Element` 类型的子对象，如果没有则返回 `null`。

`ParentNode.lastElementChild` (en-US) 只读

返回 `DocumentFragment` 的最后一个 `Element` 类型的子对象，如果没有则返回 `null`。

方法
--

*该接口继承 `Node` 的全部方法。*

`DocumentFragment.append()` (en-US)

在文档片段的最后一个子对象后插入一组 `Node` 或字符串对象。

`DocumentFragment.prepend()` (en-US)

在文档片段的第一个元素前插入一组 `Node` 或字符串对象。

`DocumentFragment.querySelector()`

返回在 `DocumentFragment` 中以文档顺序排列的第一个符合指定选择器的 `Element` 节点。

`DocumentFragment.querySelectorAll()`

返回在 `DocumentFragment` 中所有的符合指定选择器的 `Element` 节点组成的 `NodeList` 数组。

`DocumentFragment.getElementById()` (en-US)

返回在 `DocumentFragment` 中以文档顺序排列的第一个符合指定 ID 选择器的 `Element` 节点。与 `Document.getElementById()` 作用相同。

使用说明
----

最常用的方法是使用 `DocumentFragment` 创建并组成一个 DOM 子树，然后使用 `Node` 接口方法（如：`appendChild()` 或 `insertBefore()`）将其插入到 DOM 中。这种情况下会插入片段的所有子节点，并留下一个空的 `DocumentFragment`。因为所有的节点会被一次插入到文档中，所以仅会发生一个重渲染的操作，而不是每个节点分别被插入到文档中从而发生多次重渲染的操作。

该接口在 Web 组件（Web components）中也非常有用：`<template>` 元素在其 `HTMLTemplateElement.content` 属性中包含了一个 `DocumentFragment`。

可以使用 `document.createDocumentFragment` 方法或者构造函数来创建一个空的 `DocumentFragment`。

示例
--

### HTML

```html
<ul id="list"></ul>
```

### JavaScript

```js
const list = document.querySelector("#list");
const fruits = ["Apple", "Orange", "Banana", "Melon"];

const fragment = new DocumentFragment();

fruits.forEach((fruit) => {
  const li = document.createElement("li");
  li.textContent = fruit;
  fragment.appendChild(li);
});

list.appendChild(fragment);
```

### 结果

规范
--

| Specification |
| --- |
| DOM Standard # interface-documentfragment |

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

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


WEBGL_lose_context - Web API 接口参考

WEBGL\_lose\_context
====================

**WEBGL\_lose\_context** 是属于 WebGL API 的一个扩展 API，它提供一组方法用来模拟一个 `WebGLRenderingContext` 上下文的丢失和恢复。

WebGL 扩展可以通过 `WebGLRenderingContext.getExtension()` 方法来使用。更多信息可参阅 WebGL 教程 中的 使用 WebGL 扩展 。

**备注：** 该扩展在 WebGL1 和 WebGL2 上下文中都是可用的。

方法
--

`WEBGL_lose_context.loseContext()`

模拟上下文丢失。

`WEBGL_lose_context.restoreContext()`

模拟上下文恢复。

示例
--

使用这个扩展，你可以模拟 `webglcontextlost` 和 `webglcontextrestored` (en-US) 事件：

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

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

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

// 打印了 "webglcontextlost" 类型的 WebGLContextEvent 事件。
```

规范
--

| Specification |
| --- |
| WebGL WEBGL\_lose\_context Khronos Ratified Extension Specification  |

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

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

参见
--

* `WebGLRenderingContext.isContextLost()`
* 事件：`webglcontextlost`、`webglcontextrestored` (en-US)、`webglcontextcreationerror` (en-US)


CSSStyleDeclaration - Web API 接口参考

CSSStyleDeclaration
===================

**`CSSStyleDeclaration`** 接口表示一个对象，它是一个 CSS 声明块，CSS 属性键值对的集合。它暴露了样式信息和各种与样式相关的方法和属性。

`CSSStyleDeclaration` 对象可被暴露于三种不同的 API 下：

* `HTMLElement.style`，用于操作单个元素的样式（`<elem style="...">`）。
* `CSSStyleSheet` API，举个例子，`document.styleSheets[0].cssRules[0].style` 会返回文档中第一个样式表中的第一条 CSS 规则。
* `Window.getComputedStyle()`，将 `CSSStyleDeclaration` 对象作为一个**只读**的接口。
属性
--

`CSSStyleDeclaration.cssText` (en-US)

当前声明块的文本内容。设置此属性会改变样式。

`CSSStyleDeclaration.length`

属性的数量。参照下面的 `item()` 方法。

`CSSStyleDeclaration.parentRule` (en-US)

包含当前声明块的 `CssRule`。

方法
--

`CSSStyleDeclaration.getPropertyPriority()`

返回可选的优先级，"important"。

`CSSStyleDeclaration.getPropertyValue()`

返回给定属性的值。

`CSSStyleDeclaration.item()`

 返回用 index 标记的属性名，当 index 越界时返回空字符串。
 另一个可选方案：使用 nodeList[*i*]（在 i 越界时返回 undefined）获取。通常在非 JavaScript Dom 实现方案是很有用。

`CSSStyleDeclaration.removeProperty()`

从 CSS 声明块中删除属性。

`CSSStyleDeclaration.setProperty()`

在 CSS 声明块中修改现有属性或设置新属性。

`CSSStyleDeclaration.getPropertyCSSValue()`
已弃用

**仅在火狐浏览器中支持 getComputedStyle.** 返回 `CSSPrimitiveValue` (en-US) or `null` for shorthand properties.

范例
--

```js
var styleObj = document.styleSheets[0].cssRules[0].style;
console.log(styleObj.cssText);

for (var i = styleObj.length; i--; ) {
  var nameString = styleObj[i];
  styleObj.removeProperty(nameString);
}

console.log(styleObj.cssText);
```

规范
--

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

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

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

参见
--

* DOM CSS Properties


SVGEvent - Web API 接口参考

SVGEvent
========

`SVGEvent` 是一种与 SVG 相关事件所对应的事件对象接口。

Properties
----------

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | 事件目标（DOM 树的最顶端） |
| `type` 只读  | `DOMString` | 事件类型 |
| `bubbles` 只读  | `Boolean` | 事件是否冒泡 |
| `cancelable` 只读  | `Boolean` | 事件是否可取消 |


TransformStream - Web API 接口参考

TransformStream
===============

Stream API 的 **`TransformStream`** 接口表示链式管道传输（pipe chain）*转换流*（transform stream）概念的具体实现。

它可以传递给 `ReadableStream.pipeThrough()` 方法，以便将流数据从一种格式转换成另一种。例如，它可以用于解码（或者编码）视频帧，解压缩数据或者将流从 XML 转换到 JSON。

转换算法可以作为构造函数对象的可选参数提供。如果没有提供，数据在通过管道传输流时，不会被修改。

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

构造函数
----

`TransformStream()`

从给定的处理程序中创建并且返回一个转换流对象。

实例属性
----

`TransformStream.readable` 只读

转换流的 `readable` 端。

`TransformStream.writable` 只读

转换流的 `writable` 端。

实例方法
----

无

示例
--

### 将任意对象转换为 uint8 数组

在下面的示例中，一个转换流将其接收的所有分块转换为 `Uint8Array`。

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

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

### TextEncoderStream 和 TextDecoderStream 的 polyfill

注意，通过原生构造函数已弃用它。它旨在为不受支持的平台提供一个 polyfill。

```js
const tes = {
  start() {
    this.encoder = new TextEncoder();
  },
  transform(chunk, controller) {
    controller.enqueue(this.encoder.encode(chunk));
  },
};

let _jstes_wm = new WeakMap(); /\* info holder \*/
class JSTextEncoderStream extends TransformStream {
  constructor() {
    let t = { ...tes };

    super(t);
    _jstes_wm.set(this, t);
  }
  get encoding() {
    return _jstes_wm.get(this).encoder.encoding;
  }
}
```

类似地，`TextDecoderStream` 可以这样写：

```js
const tds = {
  start() {
    this.decoder = new TextDecoder(this.encoding, this.options);
  },
  transform(chunk, controller) {
    controller.enqueue(this.decoder.decode(chunk, { stream: true }));
  },
};

let _jstds_wm = new WeakMap(); /\* info holder \*/
class JSTextDecoderStream extends TransformStream {
  constructor(encoding = "utf-8", { ...options } = {}) {
    let t = { ...tds, encoding, options };

    super(t);
    _jstds_wm.set(this, t);
  }
  get encoding() {
    return _jstds_wm.get(this).decoder.encoding;
  }
  get fatal() {
    return _jstds_wm.get(this).decoder.fatal;
  }
  get ignoreBOM() {
    return _jstds_wm.get(this).decoder.ignoreBOM;
  }
}
```

### 连接多个 ReadableStream 链

这是一个连接多个流很有用的方法。示例包括构建一个渐进式加载和渐进式流的 PWA。

```js
let responses = [
  /\* conjoined response tree \*/
];
let { readable, writable } = new TransformStream();

responses.reduce(
  (a, res, i, arr) =>
    a.then(() => res.pipeTo(writable, { preventClose: i + 1 !== arr.length })),
  Promise.resolve(),
);
```

注意，这种影响是不可恢复的。

规范
--

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

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

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

参见
--

* WHATWG Stream Visualizer，用于可读、可写和转换流的基本可视化。
* 数据流——权威指南


Event - Web API 接口参考

Event
=====

**`Event`** 接口表示在 DOM 中出现的事件。

一些事件是由用户触发的，例如鼠标或键盘事件；或者由 API 生成以表示异步任务的进度。事件也可以通过编程方式触发，例如对元素调用 `HTMLElement.click()` 方法，或者定义一些自定义事件，再使用 `EventTarget.dispatchEvent()` 方法将自定义事件派发往指定的目标（target）。

有许多不同类型的事件，其中一些使用基于 `Event` 主接口的其他接口。`Event` 本身包含适用于所有事件的属性和方法。

很多 DOM 元素可以被设计接收 (或者监听) 这些事件，并且执行代码去响应（或者处理）它们。通过 `EventTarget.addEventListener()` 方法可以将事件处理器绑定到不同的 HTML 元素上（比如 `<button>`、`<div>`、`<span>` 等等）。这种方式基本替换了老版本中使用 HTML 事件处理器属性的方式。此外，在正确添加后，还可以使用 `removeEventListener()` 方法移除这些事件处理器。

**备注：** 一个元素可以绑定多个事件处理器，甚至是对于完全相同的事件。尤其是相互独立的代码模块出于不同的目的附加事件处理器。（比如，一个网页同时有着广告模块和统计模块同时监听视频播放。）

当有很多嵌套的元素，每个元素都有着自己的事件处理器，事件处理过程会变得非常复杂。尤其当一个父元素和子元素绑定完全相同的事件时，因为结构上的重叠，事件在技术层面发生在两个元素中，触发的顺序取决于每个处理器的事件冒泡和事件捕获的设置。

基于 Event 的接口
------------

下面是基于 `Event` 主接口的接口列表，每一个接口都设置了指向各自的 MDN API 参考中相应文档的链接。

需要注意的是，所有的事件接口名称都是以“Event”结尾的。

* `AnimationEvent` (en-US)
* `AudioProcessingEvent` (en-US)
已弃用
* `BeforeUnloadEvent`
* `BlobEvent` (en-US)
* `ClipboardEvent`
* `CloseEvent`
* `CompositionEvent`
* `CustomEvent`
* `DeviceMotionEvent`
* `DeviceOrientationEvent`
* `DragEvent`
* `ErrorEvent`
* `FetchEvent`
* `FocusEvent`
* `FontFaceSetLoadEvent` (en-US)
* `FormDataEvent` (en-US)
* `GamepadEvent`
* `HashChangeEvent`
* `HIDInputReportEvent` (en-US)
* `IDBVersionChangeEvent` (en-US)
* `InputEvent`
* `KeyboardEvent`
* `MediaStreamEvent`
已弃用
* `MessageEvent`
* `MouseEvent`
* `MutationEvent` (en-US)
已弃用
* `OfflineAudioCompletionEvent` (en-US)
* `PageTransitionEvent`
* `PaymentRequestUpdateEvent` (en-US)
* `PointerEvent`
* `PopStateEvent` (en-US)
* `ProgressEvent`
* `RTCDataChannelEvent` (en-US)
* `RTCPeerConnectionIceEvent` (en-US)
* `StorageEvent`
* `SubmitEvent` (en-US)
* `SVGEvent`
已弃用
* `TimeEvent` (en-US)
* `TouchEvent`
* `TrackEvent` (en-US)
* `TransitionEvent`
* `UIEvent`
* `WebGLContextEvent`
* `WheelEvent`
构造函数
----

`Event()`

创建并返回一个 `Event` 对象。

实例属性
----

`Event.bubbles` 只读

一个布尔值，用来表示该事件是否会在 DOM 中冒泡。

`Event.cancelable` 只读

一个布尔值，表示事件是否可以取消。

`Event.composed` 只读

一个布尔值，表示事件是否可以穿过 Shadow DOM 和常规 DOM 之间的边界进行冒泡。

`Event.currentTarget` 只读

对事件当前注册的目标的引用。这是一个当前计划将事件发送到的对象。它是有可能在*重定向*（retarget）的过程中被改变的。

`Event.defaultPrevented` 只读

一个布尔值，表示 `event.preventDefault()` 方法是否取消了事件的默认行为。

`Event.eventPhase` 只读

指示正在处理的事件流阶段。它是以下数字之一：`NONE`、`CAPTURING_PHASE`、`AT_TARGET`、`BUBBLING_PHASE`。

`Event.isTrusted` 只读

表示事件是由浏览器（例如用户点击）发起的，还是由脚本发起的（例如使用事件创建方法）。

`Event.target` 只读

对最初分发事件的对象的引用。

`Event.timeStamp` 只读

事件创建时的时间戳（精度为毫秒）。按照规范，这个时间戳是 Unix 纪元起经过的毫秒数，但实际上，在不同的浏览器中，对此时间戳的定义也有所不同。另外，规范正在将其修改为 `DOMHighResTimeStamp`。

`Event.type` 只读

事件的类型，不区分大小写。

### 遗留属性和非标准属性

`Event.cancelBubble`
已弃用

`Event.stopPropagation()` 的历史别名，应该改用。在事件处理程序返回之前将其值设置为 `true` 可以阻止事件传播。

`Event.explicitOriginalTarget` (en-US)
非标准
 只读

事件的明确原始目标。

`Event.originalTarget`
非标准
 只读

重定向目标前的事件原始目标。

`Event.returnValue`
已弃用

为了确保现有网站继续工作，而仍然支持的历史属性。请改用 `Event.preventDefault()` 和 `Event.defaultPrevented`。

`Event.scoped` 只读
已弃用

一个布尔值，指示给定事件是否会穿过影子根节点冒泡到标准 DOM。请改用 `composed`。

实例方法
----

`Event.composedPath()`

返回事件的路径（将在该对象上调用监听器）。如果阴影根（shadow root）节点创建时 `ShadowRoot.mode` 值为 closed，那么路径不会包括该根节点下影子树（shadow tree）的节点。

`event.preventDefault`

取消事件（如果该事件可取消）。

`event.stopImmediatePropagation`

对这个特定的事件而言，没有其他监听器被调用。这个事件既不会添加到相同的元素上，也不会添加到以后将要遍历的元素上（例如在捕获阶段）。

`event.stopPropagation`

停止冒泡，阻止事件在 DOM 中继续冒泡。

### 弃用方法

`Event.initEvent()`
已弃用

初始化创建的事件的值。如果事件已经被分派，则此方法不执行任何操作。请改用构造函数（`Event()`）。

规范
--

| Specification |
| --- |
| DOM Standard # interface-event |

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

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

参考
--

* 可用的事件类型：Event 参考
* Event 目标的比较（目标 `target` vs 当前目标 `currentTarget` vs 相关目标 `relatedTarget` vs 初始目标 `originalTarget`）
* 创建和触发自定义事件


Web 视频文本轨格式（WebVTT） - Web API 接口参考

Web 视频文本轨格式（WebVTT）
===================

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
**Web 视频文本轨格式**（**WebVTT**）是一种使用 `<track>` 元素显示定时文本轨道（例如字幕或者标题）的格式。WebVTT 文件的主要用途是将文本叠加到 `<video>` 中。WebVTT 是一种基于文本的格式，必须使用 UTF-8 进行编码。在可以使用空格的地方，也可以使用制表符。这里也有一个小的 API 可用于表示和管理这些轨道以及在正确时间执行文本回放所需的数据。

WebVTT 文件
---------

WebVTT 的 MIME 格式是 `text/vtt`。

一个 WebVTT 文件（`.vtt`）包含一行或者多行的时间提示性内容（cue），如下所示：
```

WEBVTT

00:01.000 --> 00:04.000
- Never drink liquid nitrogen.

00:05.000 --> 00:09.000
- It will perforate your stomach.
- You could die.
```

WebVTT 主体内容
-----------

WebVTT 的结构由以下部分组成，其中一些是可选的，如下所示：

* 一个可选的字节顺序标记（BOM）。
* 字符串“`WEBVTT`”。
* `WEBVTT` 右侧的可选文本标题。
    + `WEBVTT` 之后必须有一个空格。
    + 你可以通过此方式向文本添加描述。
    + 你可以在文本标题中使用除换行符和“`-->`”字符外的任何内容。
* 空白行，相当于两个连续的换行符。
* 任意数量的 cue 或注释。
* 任意数量的空行。
### 示例

* 最简形式的 WebVTT 文件
```

WEBVTT
```

* 仅有一个文本标题的 WebVTT
```

WEBVTT - This file has no cues.
```

* 有着文本标题和 cue 的通用 WebVTT 文件
```

WEBVTT - This file has cues.

14
00:01:14.815 --> 00:01:18.114
- What?
- Where are we now?

15
00:01:18.171 --> 00:01:20.991
- This is big bat country.

16
00:01:21.058 --> 00:01:23.868
- [ Bats Screeching ]
- They won't get in your hair. They're after the bugs.
```

### 一个 WebVTT 文件内部结构

让我们重新检查我们之前的一个示例，并且更仔细的查看 cue 的内部结构。
```

WEBVTT

00:01.000 --> 00:04.000
- Never drink liquid nitrogen.

00:05.000 --> 00:09.000
- It will perforate your stomach.
- You could die.
```

每个 cue 的作用如下：

* 第一行是以时间开始，其是显示了字幕出现在下面的开始时间。
* 在同一行，我们有一个字符串“`-->`”。
* 我们使用第二个时间结束第一行，其是显示关联文本结束的时间。
* 然后，我们可以有一个或者多个连字符开头的行（-），每个行都是要显示的字幕轨的一部分。

我们页可以在我们的 `.vtt` 文件放置注释，以帮助我们记住关于文件各部分的重要信息。这些应该在单独的行上，以 `NOTE` 字符串开头。你将在下一部分找到更多关于这些的信息。

重要的是不要在 cue 中使用“额外的”空白行，例如时间行和 cue 其余的行之间。WebVTT 是基于行的；一个空白行将关闭 cue。

WebVTT 注释
---------

注释是一个可选的部分，其可以用于给 WebVTT 文件增加信息。注释是为那些阅读文件的人准备的，并且用户不能看到。注释可以包含换行符，但是不能包含空白行，这相当于两个连续的换行符。一个空白行标志该注释的结尾。

注释不能包含 `-->` 字符串、和号字符（`&`）或者小于号（`<`）。如果你希望使用这些字符，你需要使用例如 `&` 和 `<`，避免使用和号和小于号字符。这里建议你使用大于转义序列（`>`），而不是大于字符（`>`）去避免与标签混淆。

注释由这三部分组成：

* `NOTE` 字符串。
* 空格或者换行符。
* 除上述字符外任意多的字符。
### 示例

* 通用 WebVTT 示例
```

NOTE This is a comment
```

* 多行注释
```

NOTE
One comment that is spanning
more than one line.

NOTE You can also make a comment
across more than one line this way.
```

* 通用注释用法
```

WEBVTT - Translation of that film I like

NOTE
This translation was done by Kyle so that
some friends can watch it with their parents.

1
00:02:15.000 --> 00:02:20.000
- Ta en kopp varmt te.
- Det är inte varmt.

2
00:02:20.000 --> 00:02:25.000
- Har en kopp te.
- Det smakar som te.

NOTE This last line may not translate well.

3
00:02:25.000 --> 00:02:30.000
- Ta en kopp
```

为 WebVTT cue 添加样式
-----------------

你可以通过查找与 `::cue` 伪元素匹配的元素来为 WebVTT 添加样式。

### 在网页中使用 CSS 定义样式

```css
video::cue {
  background-image: linear-gradient(to bottom, dimgray, lightgray);
  color: papayawhip;
}

video::cue(b) {
  color: peachpuff;
}
```

在这里，视频元素中的所有字幕风格都使用一个灰色的线性渐变作为它们的背景，并且拥有 `"papayawhip"` 的前景颜色。此外，使用 `<b>` 元素加粗的字幕是 `"peachpuff"` 颜色的。

以下的 HTML 片段实际上处理媒体自身的显示。

```html
<video controls autoplay src="video.webm">
  <track default src="track.vtt" />
</video>
```

### 在 WebVTT 文件自身中定义样式

你也可以在 WebVTT 文件中直接定义样式。在这种情况下，你可以插入 CSS 规则到文件中，且每个规则之前，在一行单独的文本上都有 `"STYLE"` 字符串，如下所示：
```

WEBVTT

STYLE
::cue {
  background-image: linear-gradient(to bottom, dimgray, lightgray);
  color: papayawhip;
}
/* Style blocks cannot use blank lines nor "dash dash greater than" */

NOTE comment blocks can be used between style blocks.

STYLE
::cue(b) {
  color: peachpuff;
}

00:00:00.000 --> 00:00:10.000
- Hello <b>world</b>.

NOTE style blocks cannot appear after the first cue.
```

我们也可以在 WebVTT 文件中使用标识符，其可以为文件的某些特殊的 cue 定义新样式。例如，我们希望转录文本以红色高亮显示，且另一部分保持正常，我们可以使用 CSS 定义它，如下所示。需要注意的是，CSS 在 HTML 页面使用时，要使用转义序列的方式：
```

WEBVTT

1
00:00.000 --> 00:02.000
That's an, an, that's an L!

crédit de transcription
00:04.000 --> 00:05.000
Transcrit par Célestes™
```

```css
::cue(#\31) {
  color: lime;
}
::cue(#crédit\ de\ transcription) {
  color: red;
}
```

字幕轨的位置也是受支持的，通过在 cue 的时间线后添加位置信息，如下所示（参见 Cue 设置获取更多信息）：
```

WEBVTT

00:00:00.000 --> 00:00:04.000 position:10%,line-left align:left size:35%
Where did he go?

00:00:03.000 --> 00:00:06.500 position:90% align:right size:35%
I think he went down this lane.

00:00:04.000 --> 00:00:06.500 position:45%,line-right align:center size:35%
What are you waiting for?
```

WebVTT cue
----------

一个 cue 就是一个单独的字幕块，它有一个单独的开始、结束和要显示文本。一个 cue 由五部分组成：

* 可选的 cue 标识符，后跟换行符。
* cue 时间线。
* 可选的 cue 设置，在第一个设置之前和每个设置之间至少有一个空格。
* 单独的换行。
* cue 中要显示文本。

这里有一个 cue 的示例：
```

1 - Title Crawl
00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start
Some time ago in a place rather distant....
```

### cue 标识符

标识符是标识 cue 的名称。它可以从一个脚本中引用 cue。其不得包含换行以及不能包含“`-->`”字符串。它必须以一个新行结束。它们不必是唯一的，尽管对它们进行编号很常见（例如，1、2、3）。

这里有一些示例：

* 一个基本的 cue 标识符
```

1 - Title Crawl
```

* 标识符通常的用法
```

WEBVTT

1
00:00:22.230 --> 00:00:24.606
This is the first subtitle.

2
00:00:30.739 --> 00:00:34.074
This is the second.

3
00:00:34.159 --> 00:00:35.743
Third
```

### cue 时间线

cue 时间线指示 cue 何时显示。它用时间戳表示开始和结束的时间。结束的时间一定大于开始的时间，并且开始时间必须大于或者等于所有之前开始的时间。cue 可能具有重叠的时间。

如果 webVTT 文件用于 chapters（`<track>` 的 `kind` 是 `chapters`），那么文件中不能有重叠的时间。

每个 cue 的时间线都包含五个部分：

* 开始的时间戳。
* 至少一个空格
* “`-->`”字符串。
* 至少一个空格。
* 结束的时间戳，必须大于开始的时间。

时间戳必须是以下两种格式之一：

* `mm:ss.ttt`
* `hh:mm:ss.ttt`

其中各部分定义如下：

`hh`

表示小时并且必须至少有两个数字。他可以超过两个数字（例如 `9999:00:00.000`）。

`mm`

表示分钟并且必须在 00 和 59 之间（包括 00 和 59）。

`ss`

表示秒并且必须在 00 和 59 之间（包括 00 和 59）。

`ttt`

表示分钟并且必须在 000 和 999 之间（包括 000 和 999）。

这里有一些时间线的示例：

* 基本的 cue 时间线示例
```

00:00:22.230 --> 00:00:24.606
00:00:30.739 --> 00:00:34.074
00:00:34.159 --> 00:00:35.743
00:00:35.827 --> 00:00:40.122
```

* 重叠的 cue 时间线示例
```

00:00:00.000 --> 00:00:10.000
00:00:05.000 --> 00:01:00.000
00:00:30.000 --> 00:00:50.000
```

* 未重叠的 cue 时间线示例
```

00:00:00.000 --> 00:00:10.000
00:00:10.000 --> 00:01:00.581
00:01:00.581 --> 00:02:00.100
00:02:01.000 --> 00:02:01.000
```

### Cue 设置

cue 设置是可选的，其用于设置有效字幕将显示在视频中的具体位置。这包括文本是水平显示还是垂直显示。它们可以是任意的个数，只要每个设置使用不超过一次，它们就可以以任何顺序使用。

cue 设置被增加在 cue 时间线的右侧。在 cue 时间线和第一个设置之间以及每个设置之间必须有一个或者更多的空格。设置的名称和值由冒号分隔。设置区分大小写，因此如下所示，其都是使用小写的。这里有五个 cue 设置：

`vertical`

表示文本将垂直的显示而不是水平的显示，例如在一些亚洲语言中。这里有两个可能的值：

`rl`

书写方向从右向左。

`lr`

书写方向从左向右。

`line`

如果没有设置垂直方向，那么指定文本垂直方向显示的位置。如果设置了垂直，line 指定文本出现的水平位置。它的值可能是：

数字

数字表示视频中显示的 cue 第一行的高度。正数表示自上而下，负数表示自下而上。

百分比

它必须是一个 0 和 100 之间的整数，包括 0 和 100（即不是小数），并且其后必须跟随一个百分比符号（%）。

| Line | `vertical` omitted | `vertical:rl` | `vertical:lr` |
| --- | --- | --- | --- |
| `line:0` | top | right | left |
| `line:-1` | bottom | left | right |
| `line:0%` | top | right | left |
| `line:100%` | bottom | left | right |

`position`

指定字幕水平出现的位置。如果设置了垂直方向，position 指定文本垂直方向出现的位置。当值是一个百分比，其必须是一个 0 到 100 之间的整数，包括 0 和 100（不是小数），并且其后必须跟随一个百分比符号（%）。

| Position | `vertical` omitted | `vertical:rl` | `vertical:lr` |
| --- | --- | --- | --- |
| `position:0%` | left | top | top |
| `position:100%` | right | bottom | bottom |

`size`

指定字幕区域到宽度。如果设置了垂直方向，size 指定了文本区域到高度。当值是一个百分比，其必须是一个 0 到 100 之间的整数，包括 0 和 100（不是小数），并且其后必须跟随一个百分比符号（%）。

| Size | `vertical` omitted | `vertical:rl` | `vertical:lr` |
| --- | --- | --- | --- |
| `size:100%` | full width | full height | full height |
| `size:50%` | half width | half height | half height |

`align`

指定文本的对齐方式。如果设置了字幕，则在 cue 设置的 size 给出的空间中对齐。

| Align | `vertical` omitted | `vertical:rl` | `vertical:lr` |
| --- | --- | --- | --- |
| `align:start` | left | top | top |
| `align:center` | centered horizontally | centered vertically | centered vertically |
| `align:end` | right | bottom | bottom |

让我们学习 cue 设置的示例。

第一行没有显示任何设置。第二行用于在标记或者标签上叠加文本。第三行可用于标题，最后一行可能是一个亚洲语言。
```

00:00:05.000 --> 00:00:10.000
00:00:05.000 --> 00:00:10.000 line:63% position:72% align:start
00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start
00:00:05.000 --> 00:00:10.000 vertical:rt line:-1 align:end
```

### cue 有效内容

有效内容是主要信息或者内容所处的位置。在正常使用中，有效内容包含将被展示的字幕。有效内容中的文本可包含换行符，但是它不能包含一个空行，这等同于两个连续的换行符。一个空白行表示 cue 的结尾。

cue 文本的有效内容不能包含 `-->` 字符串、和号字符（`&`）或者小于号（`<`）。然而，你需要使用例如 `&` 和 `<`，避免使用和号和小于号字符。这里也建议你使用大于转义序列（`>`），而不是大于字符（`>`）去避免与标签混淆。如果你将 WebVTT 文件用于元数据，这些限制不会适用。

除了上面提到的三个转义序列外，这里还有四个。它们在以下列表。

| 名称 | 字符 | 转义序列 |
| --- | --- | --- |
| 和号 | `&` | `&` |
| 小于号 | `<` | `<` |
| 大于号 | `>` | `>` |
| 从左向右的标志 | *none* | `` |
| 从右向左的标志 | *none* | `` |
| 不换行的空格 |  | ` ` |

### cue 有效内容的文本标签

这里有一些标签，例如 `<b>`。然而，如果 WebVTT 文件在 `kind` 属性是 `chapters` 的 `<track>` 元素中使用，那么你无法使用这些标签。

时间戳标签

时间戳必须大于 cue 开始的时间戳，大于在 cue 有效内容中任意之前的时间戳，并且小于 cue 结束的时间戳。*活动的文本*（active text）是指当前时间戳和下一个时间戳之间的文本或者如果有效内容中没有其他时间戳，则一直到有效内容末尾的文本。有效内容中*活动的文本*之前的任何文本都是*之前已出现的文本*（previous text）。*活动的文本*之后的文本都是*未来即将出现的文本*（future text）。这启用了 karaoke 风格的字幕。
```

1
00:16.500 --> 00:18.500
When the moon <00:17.500>hits your eye

1
00:00:18.500 --> 00:00:20.500
Like a <00:19.000>big-a <00:19.500>pizza <00:20.000>pie

1
00:00:20.500 --> 00:00:21.500
That's <00:00:21.000>amore
```

以下标签是 cue 中允许的 HTML 标签，并且需要闭合（例如 `<b>text</b>`）。

类标签（`<c></c>`）

使用 CSS 类对包含的文本进行样式设置。

```xml
<c.classname>text</c>
```

斜体标签（`<i></i>`）

将包含的文本斜体化。

```xml
<i>text</i>
```

粗体标签（`<b></b>`）

将包含的文本粗体化。

```xml
<b>text</b>
```

下划线标签（`<u></u>`）

给包含的文本加下划线

```xml
<u>text</u>
```

Ruby 标签（`<ruby></ruby>`）

使用 ruby 文本标签展示 ruby 字符（即其他字符上的小的注解字符）。

```xml
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
```

Ruby 文本标签（`<rt></rt>`）

使用 ruby 文本标签展示 ruby 字符（即其他字符上的小的注解字符）。

```xml
<ruby>WWW<rt>World Wide Web</rt>oui<rt>yes</rt></ruby>
```

声音标签（`<v></v>`）

与类标签类似，也用于使用 CSS 设置包含文本的样式。

```xml
<v Bob>text</v>
```

方法和属性
-----

WebVTT 使用的方法是那些用于更改 cue 或者 region 的方法，因为两个接口的属性都不同，我们可以对它们进行分类，以更好地理解关于 WebVTT 中的每个接口：

### VTTCue

`VTTCue` (en-US) 接口可用的方法：

* `getCueAsHTML()` (en-US) 获取该 cue 的 HTML。
* 一个构造函数，`VTTCue()` (en-US) 用于创建此接口的新实例。

允许不同的属性去读和设置 cue 的特征，像它的位置、对齐方式或者大小都是可更改的。检查 `VTTCue` (en-US) 获取完整性列表。

### VTTRegion

`VTTRegion` (en-US) 提供用于以下区域的方法，以及对其功能的描述，特别是它允许去调整整个给定区域中所有节点的滚动设置。

如何编写 WebVTT 文件的指导
-----------------

编写一个简单的 WebVTT 文件可以遵循以下步骤。开始之前，必须注意你可以使用记事本且保存文件作为“.vtt”的格式。步骤如下所示：

* 打开一个记事本。
* WebVTT 的第一行是标准化的，类似于其他一些语言，你需要去文件头部标识文件的类型。在第一行，你得这样写：
```

WEBVTT
```

* 第二行留空，在第三行指定第一个 cue 的时间。例如，第一个 cue 从第 1 秒开始且第 5 秒结束，他可以这样写：
```

00:01.000 --> 00:05.000
```

* 在下一行，以可以为这个 cue 写上字幕，它们将在第 1 秒和第 5 秒期间（包括第 1 秒和第 5 秒）显示。
* 按照类似的步骤，可以为指定的视频或音频文件制作完整的 WebVTT 文件。
CSS 伪类
------

CSS 伪类允许我们去归类我们想与其他对象类型区别的对象类型。它在 WebVTT 文件的工作方式与在 HTML 文件的工作方式类似。

WebVTT 支持的良好的特征之一是本地化和类元素的使用，它们可以以相同的方式在 HTML 和 CSS 中为特定的对象类型用样式进行归类，但在这里，这些元素用于样式化以及分类 cue，如下所示：
```

WEBVTT

04:02.500 --> 04:05.000
J'ai commencé le basket à l'âge de 13, 14 ans

04:05.001 --> 04:07.800
Sur les <i.foreignphrase><lang en>playground</lang></i>, ici à Montpellier
```

在上面的示例中，可以看到我们可以使用标识符和伪类名称定义字幕的语言，其中 `<i>` 标签用于斜体。

伪类的类型由它正在使用的选择器决定，其工作性质与在 HTML 中的选择器类似。以下 CSS 伪类可以被使用：

* `lang`（Language）：例如 `p:lang(it)`。
* `link`：例如 `a:link`。
* `nth-last-child`：例如 `p:nth-last-child(2)`。
* `nth-child(n)`：例如 `p:nth-child(2)`。

其中 p 和 a 标签被用作 HTML 标签中的段落和链接，它们可以替换 WebVTT 文件中用于 cue 的标识符。

规范
--

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # the-vttcue-interface |
| HTML Standard # texttrack |
| WebVTT: The Web Video Text Tracks Format # the-vttregion-interface |

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

### api.VTTCue

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

### api.TextTrack

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

### api.VTTRegion

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

### 注意

在 Firefox 50 之前，`AlignSetting` 枚举（表示 `VTTCue.align` (en-US) 可能的值）错误地包含 `"middle"` 值而不是 `"center"` 值。但这已经得到了纠正。

WebVTT 在 Firefox 24 的首选项 `media.webvtt.enabled` 之后实现，默认是禁止的；你可以设置这个选项为 `true` 以启用它。WebVTT 在 Firefox 31 默认开启并可以通过设置这个选项为 `false` 以禁止它。

在 Firefox 58 之前，`REGION` 关键字由 `VTTRegion` (en-US) 对象创建，但是它们没有被使用。Firefox 58 现在完全支持 `VTTRegion` 以及它的使用；然而，这个功能在首选项 `media.webvtt.regions.enabled` 默认是禁用的；将其设置为 `true` 以在 Firefox 58 开启区域支持。在 Firefox 59 中默认是开启的（参见 bug Firefox bug 1338030 和 Firefox bug 1415805）。

参见
--

* CSS 伪类 `::cue` 和 `::cue()`


ScriptProcessorNode - Web API 接口参考

ScriptProcessorNode
===================

**备注：** 这个特性在 2014 年 8 月 29 日发布的 Web Audio API 规范中已经标记为不推荐，将很快会被Audio Workers代替。

`ScriptProcessorNode` 接口允许使用 JavaScript 生成、处理、分析音频。它是一个 `AudioNode`，连接着两个缓冲区音频处理模块，其中一个缓冲区包含输入音频数据，另外一个包含处理后的输出音频数据。实现了 `AudioProcessingEvent` (en-US) 接口的一个事件，每当输入缓冲区有新的数据时，事件将被发送到该对象，并且事件将在数据填充到输出缓冲区后结束。

![The ScriptProcessorNode stores the input in a buffer, send the audioprocess event. The EventHandler takes the input buffer and fill the output buffer which is sent to the output by the ScriptProcessorNode.](/zh-CN/docs/Web/API/ScriptProcessorNode/webaudioscriptprocessingnode.png)

输入和输出缓冲区大小在创建时定义，当 `AudioContext.createScriptProcessor()` 方法被调用时 (都是由 `AudioContext.createScriptProcessor()`的 `bufferSize` 参数定义). 缓冲区大小必须是在 `256` 到 `16384` 之间的 2 的次幂，为 `256`, `512`, `1024`, `2048`, `4096`, `8192` 或者 `16384`. Small numbers lower the *latency*, but large number may be necessary to avoid audio breakup and glitches.

If the buffer size is not defined, which is recommended, the browser will pick one that its heuristic deems appropriate.

|  |  |
| --- | --- |
| Number of inputs | `1` |
| Number of outputs | `1` |
| Channel count mode | `"max"` |
| Channel count | `2` (not used in the default count mode) |
| Channel interpretation | `"speakers"` |

属性
--

*从上一级继承属性，`AudioNode`。*

`ScriptProcessorNode.bufferSize` (en-US) 只读

返回一个表示输入和输出缓冲区大小的整数。它的值可以是在`256`–`16384` 之间的 2 的次幂。

### 事件句柄

`ScriptProcessorNode.onaudioprocess` (en-US)

Represents the event handler to be called.

方法
--

*No specific methods; inherits methods from its parent, `AudioNode`*.

示例
--

参见 `BaseAudioContext.createScriptProcessor()` 以获取示例代码。

规范
--

自 2014 年 8 月 29 日 Web Audio API 规范发布以来，此特性已被弃用。它不再有望成为标准。

它已被 AudioWorklet (en-US) 和 `AudioWorkletNode` 接口所取代。

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

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

参见
--

* 使用 Web Audio API


CSS 计数器样式 - Web API 接口参考

CSS 计数器样式
=========

CSS 计数器样式模块允许自定义计数器样式，可以用于 CSS 列表标记与生成内容计数器。

接口
--

`CSSCounterStyleRule` (en-US)

表示一个 `@counter-style` 规则。

规范
--

| Specification |
| --- |
| CSS Counter Styles Level 3 # the-csscounterstylerule-interface |

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

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

参见
--

* 使用 CSS 计数器


CryptoKey - Web API 接口参考

CryptoKey
=========

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

Web Crypto API 的 **`CryptoKey`** 接口表示从特定 `SubtleCrypto` 方法（`generateKey()`、`deriveKey()`、`importKey()` 或 `unwrapKey()`）导出的密钥。

出于安全考虑，`CryptoKey` 接口仅在安全上下文中可用。

实例属性
----

`CryptoKey.type`

返回一个表示密钥类型的字符串，可使用以下值：

* `"secret"`：为密钥（secret key），用于对称加密算法 (en-US)。
* `"private"`：为非对称加密算法 (en-US)的 `CryptoKeyPair` (en-US) 的密钥（private key）部分。
* `"public"`：为非对称加密算法 (en-US)的 `CryptoKeyPair` (en-US) 的公钥（public key）部分。

`CryptoKey.extractable`

一个布尔值，表示原始信息是否能使用 `SubtleCrypto.exportKey()` 或 `SubtleCrypto.wrapKey()` 导出。

* `true`：密钥可以导出。
* `false`：密钥不能导出。使用 `exportKey()` 或 `wrapKey()` 方法来导出此密钥将会抛出异常。

`CryptoKey.algorithm`

一个描述可使用此密钥的算法及任何关联的额外参数的对象。

* `AesKeyGenParams` (en-US) 如果算法是任意高级加密标准（AES）的变体。
* `RsaHashedKeyGenParams` (en-US) 如果算法是任意 RSA 的变体。
* `EcKeyGenParams` (en-US) 如果算法是任意椭圆曲线加密算法（EC）的变体。
* `HmacKeyGenParams` (en-US) 如果算法是任意密钥散列消息认证码（HMAC）的变体。

`CryptoKey.usages`

一个字符串的数组，指明密钥的用途。数组元素可能的值有：

* `"encrypt"`：密钥可用于加密消息。
* `"decrypt"`：密钥可用于解密消息。
* `"sign"`：密钥可用于对消息进行签名。
* `"verify"`：密钥可用于验证签名。
* `"deriveKey"`：密钥可用于派生新的密钥。
* `"deriveBits"`：密钥可用于派生比特序列。
* `"wrapKey"`：密钥可被包装。
* `"unwrapKey"`：密钥可被解包装。

示例
--

`SubtleCrypto` 方法的示例大多使用了 `CryptoKey` 对象。例如：

* `SubtleCrypto.generateKey()`
* `SubtleCrypto.deriveKey()`
* `SubtleCrypto.importKey()`
* `SubtleCrypto.exportKey()`
* `SubtleCrypto.wrapKey()`
* `SubtleCrypto.unwrapKey()`
* `SubtleCrypto.encrypt()`
* `SubtleCrypto.decrypt()`
* `SubtleCrypto.sign()`
* `SubtleCrypto.verify()`
规范
--

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

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

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

参见
--

* Web Crypto API
* Web 安全
* 隐私、权限和信息安全 (en-US)
* `Crypto` 和 `Crypto.subtle`。


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

isSecureContext 全局属性
====================

全局只读属性 **`isSecureContext`** 返回一个布尔值，指示当前上下文是安全的（`true`）还是不安全的（`false`）。

值
-

一个布尔值，`true` 或 `false`。

规范
--

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

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

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

参见
--

* 安全上下文


MathMLElement - Web API 接口参考

MathMLElement
=============

**`MathMLElement`** 接口表示任意 MathML 元素。

属性
--

*This interface has no properties, but inherits properties from: `DocumentAndElementEventHandlers`, `Element`, `ElementCSSInlineStyle` (en-US), `GlobalEventHandlers`, `HTMLOrForeignElement`.*

方法
--

*This interface has no methods, but inherits methods from: `DocumentAndElementEventHandlers`, `Element`, `ElementCSSInlineStyle` (en-US), `GlobalEventHandlers`, `HTMLOrForeignElement`.*

示例
--

### MathML

```html
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <msqrt>
    <mi>x</mi>
  </msqrt>
</math>
```

### JavaScript

```js
document.querySelector("msqrt").constructor.name; // MathMLElement
```

规范
--

| Specification |
| --- |
| MathML Core # dom-mathmlelement |

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

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

参见
--

* `Element`
* `HTMLElement`
* `SVGElement`


MediaQueryList - Web API 接口参考

MediaQueryList
==============

一个 `MediaQueryList` 对象在一个 `document` 上维持着一系列的媒体查询 (en-US)，并负责处理当媒体查询在其 document 上发生变化时向监听器进行通知的发送。

如果你需要以编程方式来检测一个 document 上的媒体查询的值的变化，这个 `MediaQueryList` 对象使得通过观察其 document 而检测它的媒体查询的值的变化成为可能，而不是周期性地对这些媒体查询的值进行检查。

方法概述
----
```

void addListener(MediaQueryListListener listener);
void removeListener(MediaQueryListListener listener);
```

实例属性
----

*`MediaQueryList` 接口从它的父接口 `EventTarget` 继承了属性。*

`matches` 只读

一个布尔值，如果当前 `document` 与媒体查询列表相匹配，则返回 `true`，否则返回 `false`。

`media` (en-US) 只读

代表序列化的媒体查询的字符串。

方法
--

### addListener()

在媒体查询列表上增加一个新的监听器，如果列表中已经存在了这个指定的监听器，这个方法将失去作用。
```

void addListener(
  MediaQueryListListener listener
);
```

#### 参数 ( 针对 addListener 方法)

`listener`

当其媒体查询的求值结果发生变化时，该 `MediaQueryListListener` (en-US) 对象将会被调用。

### removeListener()

从媒体查询列表中移除一个监听器，如果列表中不存在这个指定的监听器，则这个方法将失去作用。
```

void removeListener(
  MediaQueryListListener listener
);
```

#### 参数 (针对 removeListener 方法)

`listener`

该 `MediaQueryListListener` (en-US)对象将停止访问媒体查询的求值结果发生的变化。

规范
--

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

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

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

参见
--

* CSS 媒体查询 (en-US)
* 通过代码使用媒体查询 (en-US)
* `window.matchMedia()`
* `MediaQueryListListener` (en-US)


IntersectionObserverEntry - Web API 接口参考

IntersectionObserverEntry
=========================

**`IntersectionObserverEntry 接口`** (从属于 Intersection Observer API ) 描述了目标元素与其根元素容器在某一特定过渡时刻的交叉状态。`IntersectionObserverEntry` 的实例作为 `entries` 参数被传递到一个 `IntersectionObserver` 的回调函数中; 此外，这些对象只能通过调用`IntersectionObserver.takeRecords()` 来获取。

属性
--

`IntersectionObserverEntry.boundingClientRect` (en-US) 只读

返回包含目标元素的边界信息的`DOMRectReadOnly`. 边界的计算方式与 `Element.getBoundingClientRect()` 相同。

`IntersectionObserverEntry.intersectionRatio` (en-US) 只读

返回`intersectionRect` 与 `boundingClientRect` 的比例值。

`IntersectionObserverEntry.intersectionRect` (en-US) 只读

返回一个 `DOMRectReadOnly` 用来描述根和目标元素的相交区域。

`IntersectionObserverEntry.isIntersecting` (en-US) 只读

返回一个布尔值，如果目标元素与交叉区域观察者对象 (intersection observer) 的根相交，则返回 `true` .如果返回 `true`, 则 `IntersectionObserverEntry` 描述了变换到交叉时的状态; 如果返回 `false`, 那么可以由此判断，变换是从交叉状态到非交叉状态。

`IntersectionObserverEntry.rootBounds` (en-US) 只读

返回一个 `DOMRectReadOnly` 用来描述交叉区域观察者 (intersection observer) 中的根。

`IntersectionObserverEntry.target` (en-US) 只读

与根出现相交区域改变的元素 (`Element`).

`IntersectionObserverEntry.time` (en-US) 只读

返回一个记录从 `IntersectionObserver` 的时间原点 (time origin) 到交叉被触发的时间的时间戳 (`DOMHighResTimeStamp`).

方法
--

*此接口没有方法。*

规范
--

| Specification |
| --- |
| Intersection Observer # intersection-observer-entry |

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

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


AudioDestinationNode - Web API 接口参考

AudioDestinationNode
====================

`AudioDestinationNode`接口表示音频图形在特定情况下的最终输出地址 - 通常为扬声器。当使用`OfflineAudioContext`时为音频记录节点。

AudioDestinationNode 没有输出（因为它就是输出，它存在于视频图标中后 AudioNode 不能被链接），有一个输入。输入信道的数量必须是 0 至 maxChannelCount 之间的值或是一个异常。

`AudioDestinationNode` 可以通过 `AudioContext.destination` 属性来查看。

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

属性
--

*从`AudioNode`继承的属性*.

`AudioDestinationNode.maxChannelCount`

以无符长整型返回物理设备可以处理的最大通道数量。

方法
--

*继承 `AudioNode` 的方法。*

例子
--

`AudioDestinationNode 不需要使用复杂的设置` — 在默认情况下只是简单的代表使用者系统的输出 (例如他们的扬声器)，这样你就可以使用几行代码来与内置音频图标挂钩：

```js
var audioCtx = new AudioContext();
var source = audioCtx.createMediaElementSource(myMediaElement);
source.connect(gainNode);
gainNode.connect(audioCtx.destination);
```

更多的例子，请查看 MDN Web Audio 示例，例如Voice-change-o-matic 或者 Violent Theremin.

标准
--

| Specification |
| --- |
| Web Audio API # AudioDestinationNode |

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

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

参见
--

* Using the Web Audio API


ReadableStream - Web API 接口参考

ReadableStream
==============

Stream API 中的 `ReadableStream` 接口表示可读的字节数据流。Fetch API 通过 `Response` 的属性 `body` (en-US) 提供了一个具体的 `ReadableStream` 对象。

构造函数
----

`ReadableStream()`

创建并从给定的处理程序返回一个可读流对象。

实例属性
----

`ReadableStream.locked` 只读

`locked` 返回该可读流是否被锁定到一个 reader。

实例方法
----

`ReadableStream.cancel()`

取消读取流，读取方发出一个信号，表示对这束流失去兴趣。可以传入 reason 参数表示取消原因，这个原因将传回给调用方。

`ReadableStream.getReader()`

创建一个读取器并将流锁定于其上。一旦流被锁定，其他读取器将不能读取它，直到它被释放。

`ReadableStream.pipeThrough()`

提供将当前流管道输出到一个转换（transform）流或可写/可读流对的链式方法。

`ReadableStream.pipeTo()`

将当前 ReadableStream 管道输出到给定的 `WritableStream`，并返回一个 promise，该 promise 在输出过程成功完成时兑现，在发生错误时拒绝。

`ReadableStream.tee()`

`tee` 方法拷贝了可读流，返回包含两个 `ReadableStream` 实例分支的数组，每个元素接收了相同的传输数据。

示例
--

### Fetch 流

下面的例子，创建了一个智能的 `Response` 将从另一个资源获取的 HTML 片段流式的传输到浏览器。

它演示了 `ReadableStream` 与 `Uint8Array` (en-US) 的协同用法。

```js
fetch("https://www.example.org")
  .then((response) => response.body)
  .then((rb) => {
    const reader = rb.getReader();
    return new ReadableStream({
      start(controller) {
        // The following function handles each data chunk
        function push() {
          // "done" is a Boolean and value a "Uint8Array"
          reader.read().then(({ done, value }) => {
            // If there is no more data to read
            if (done) {
              console.log("done", done);
              controller.close();
              return;
            }
            // Get the data and send it to the browser via the controller
            controller.enqueue(value);
            // Check chunks by logging to the console
            console.log(done, value);
            push();
          });
        }
        push();
      },
    });
  })
  .then((stream) =>
    // Respond with our stream
    new Response(stream, { headers: { "Content-Type": "text/html" } }).text(),
  )
  .then((result) => {
    // Do things with result
    console.log(result);
  });
```

### 转换异步迭代器到流

将（异步）迭代器转换为可读流：

```js
function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();
      if (done) {
        controller.close();
      } else {
        controller.enqueue(value);
      }
    },
  });
}
```

这适用于异步和非异步的迭代器。

### 使用 for await...of 对流进行异步迭代

此示例展示了如何使用 `for await...of` 循环来迭代到达的分块，以处理 `fetch()` 响应。

```js
const response = await fetch("https://www.example.org");
let total = 0;

// Iterate response.body (a ReadableStream) asynchronously
for await (const chunk of response.body) {
  // Do something with each chunk
  // Here we just accumulate the size of the response.
  total += chunk.length;
}

// Do something with the total
console.log(total);
```

规范
--

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

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

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

参见
--

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


AudioBufferSourceNode - Web API 接口参考

AudioBufferSourceNode
=====================

**`AudioBufferSourceNode`** 接口继承自 `AudioScheduledSourceNode`，表现为一个音频源，它包含了一些写在内存中的音频数据，通常储存在一个 ArrayBuffer 对象中。在处理有严格的时间精确度要求的回放的情形下它尤其有用。比如播放那些需要满足一个指定节奏的声音或者那些储存在内存而不是硬盘或者来自网络的声音。为了播放那些有时间精确度需求但来自网络的流文件或者来自硬盘，则使用 `AudioWorkletNode` 来实现回放。

EventTarget

AudioNode

AudioScheduledSourceNode

AudioBufferSourceNode
`AudioBufferSourceNode` 没有输入却有一个输出，其通道数与其 `buffer` 属性所指定的 `AudioBuffer` 相同。如果没有设置 buffer，也就是说 `buffer` 属性是 `null` 的话，输出将包含一个无声的单通道（每个采样点均为 0）。

一个 `AudioBufferSourceNode` 只能被播放一次，也就是说，每次调用 `start()` (en-US) 之后，如果还想再播放一遍同样的声音，那么就需要再创建一个 `AudioBufferSourceNode`。庆幸的是，创建该节点的代价并不大，并且想要多次播放声音的话，实际上 `AudioBuffer` 也可以被重用。事实上，你可以用一种“阅后即焚”的方式来使用这些节点：创建节点，调用 `start()` 开始播放声音，然后，你甚至不需要再保留这个节点的引用了。声音播放完成之后，垃圾收集器会找个恰当的时机回收资源。

`多次调用 AudioBufferSourceNode.stop()` 是允许的。如果这时候 `AudioBufferSourceNode` 还没有到达缓冲区末尾的话，最近一次的调用将替换上一次的调用。

![The AudioBufferSourceNode takes the content of an AudioBuffer and m](/zh-CN/docs/Web/API/AudioBufferSourceNode/webaudioaudiobuffersourcenode.png)

|  |  |
| --- | --- |
| 输入数量 | `0` |
| 输出数量 | `1` |
| 频道数量 | 由相关的 `AudioBuffer` 定义 |

属性
--

*从父级的* *`AudioNode` 继承属性*.

`AudioBufferSourceNode.buffer`

是一个 `AudioBuffer` 它定义了要播放的音频，当设置它的值为 0 时，它会定义一个静默的单通道。

`AudioBufferSourceNode.detune` (en-US)

Is a k-rate (en-US) `AudioParam` representing detuning of oscillation in cents. Its default value is `0`.

`AudioBufferSourceNode.loop` (en-US)

Is a Boolean attribute indicating if the audio asset must be replayed when the end of the `AudioBuffer` is reached. Its default value is `false`.

`AudioBufferSourceNode.loopStart` (en-US)

Is a double value indicating, in seconds, where in the `AudioBuffer` the restart of the play must happen. Its default value is `0`.

`AudioBufferSourceNode.loopEnd` (en-US)

Is a double value indicating, in seconds, where in the `AudioBuffer` the replay of the play must stop (and eventually loop again). Its default value is `0`.

`AudioBufferSourceNode.playbackRate` (en-US)

Is an a-rate `AudioParam` that defines the speed factor at which the audio asset will be played. Since no pitch correction is applied on the output, this can be used to change the pitch of the sample.

### 事件

`AudioBufferSourceNode.onended` (en-US)

是一个事件处理器类型，包含了与 `ended` 相关联的结束事件。

方法
--

*从父级的 `AudioNode` 继承方法。*

`AudioBufferSourceNode.start()`

Schedules the start of the playback of the audio asset.

`AudioBufferSourceNode.stop()` (en-US)

Schedules the end of the playback of an audio asset.

例子
--

在这个例子中，我们将会创建一个 2 秒的缓冲器，并用白噪音填充它，然后通过`AudioBufferSourceNode`来播放它。注释里说明了它的功能。

**备注：** 你可以 查看在线演示 或 查看源代码.

```js
var audioCtx = new (window.AudioContext || window.webkitAudioContext)();
var button = document.querySelector("button");
var pre = document.querySelector("pre");
var myScript = document.querySelector("script");

pre.innerHTML = myScript.innerHTML;

// Stereo
var channels = 2;
// Create an empty two-second stereo buffer at the
// sample rate of the AudioContext
var frameCount = audioCtx.sampleRate \* 2.0;

var myArrayBuffer = audioCtx.createBuffer(2, frameCount, audioCtx.sampleRate);

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

  // Get an AudioBufferSourceNode.
  // This is the AudioNode to use when we want to play an AudioBuffer
  var source = audioCtx.createBufferSource();
  // set the buffer in the AudioBufferSourceNode
  source.buffer = myArrayBuffer;
  // connect the AudioBufferSourceNode to the
  // destination so we can hear the sound
  source.connect(audioCtx.destination);
  // start the source playing
  source.start();
};
```

**备注：** 音频数据解码的例子请查看 `AudioContext.decodeAudioData` 页面。

规范
--

| Specification |
| --- |
| Web Audio API # AudioBufferSourceNode |

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

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

相关页面
----

* Using the Web Audio API


MediaSource - Web API 接口参考

MediaSource
===========

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

**`MediaSource`** 是 Media Source Extensions API 表示媒体资源 `HTMLMediaElement` 对象的接口。`MediaSource` 对象可以附着在 `HTMLMediaElement` 在客户端进行播放。

构造函数
----

`MediaSource()`

创建并且返回一个新的 `MediaSource` 的空对象（with no associated source buffers）。

属性
--

`MediaSource.sourceBuffers` 只读

返回一个 `SourceBufferList` 对象，包含了这个 `MediaSource` 的 `SourceBuffer` 的对象列表。

`MediaSource.activeSourceBuffers` 只读

 返回一个 `SourceBufferList` 对象，包含了这个 `MediaSource.sourceBuffers` 中的 `SourceBuffer`
 子集的对象—即提供当前被选中的视频轨（video track），启用的音频轨（audio tracks）以及显示/隐藏的字幕轨（text tracks）的对象列表。

`MediaSource.readyState` 只读

返回一个代表当前 `MediaSource` 状态的枚举值，即当前是否未连接到媒体元素（`closed`），是否已连接并准备好接收 `SourceBuffer` 对象（`open`），或者是否已连接但已通过 `MediaSource.endOfStream()` 结束媒体流（`ended`）。

`MediaSource.duration`

获取和设置当前正在推流媒体的持续时间。

方法
--

*从父接口`EventTarget`上继承而来。*

`MediaSource.addSourceBuffer()`

创建一个带有给定 MIME 类型的新的 `SourceBuffer` 并添加到 `MediaSource` 的 `SourceBuffers` 列表。

`MediaSource.removeSourceBuffer()`

删除指定的 `SourceBuffer` 从这个 `MediaSource` 对象中的 `SourceBuffers`列表。

`MediaSource.endOfStream()`

表示流的结束。

静态方法
----

`MediaSource.isTypeSupported()`

返回一个 `Boolean` (en-US) 值表明给定的 MIME 类型是否被当前的浏览器支持——这意味着是否可以成功的创建这个 MIME 类型的 `SourceBuffer` 对象。

示例
--

这个例子尽可能快地逐块加载视频，并在加载好后立刻播放。以下片段基于 Nick Desaulniers 编写的一个简单示例（查看完整的在线演示，或者下载源代码进行进一步研究）。

```js
const video = document.querySelector("video");

const assetURL = "frag\_bunny.mp4";
// Need to be specific for Blink regarding codecs
// ./mp4info frag\_bunny.mp4 | grep Codec
const mimeCodec = 'video/mp4; codecs="avc1.42E01E, mp4a.40.2"';

if ("MediaSource" in window && MediaSource.isTypeSupported(mimeCodec)) {
  const mediaSource = new MediaSource();
  //console.log(mediaSource.readyState); // closed
  video.src = URL.createObjectURL(mediaSource);
  mediaSource.addEventListener("sourceopen", sourceOpen);
} else {
  console.error("Unsupported MIME type or codec: ", mimeCodec);
}

function sourceOpen(\_) {
  //console.log(this.readyState); // open
  const mediaSource = this;
  const sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
  fetchAB(assetURL, function (buf) {
    sourceBuffer.addEventListener("updateend", function (\_) {
      mediaSource.endOfStream();
      video.play();
      //console.log(mediaSource.readyState); // ended
    });
    sourceBuffer.appendBuffer(buf);
  });
}

function fetchAB(url, cb) {
  console.log(url);
  const xhr = new XMLHttpRequest();
  xhr.open("get", url);
  xhr.responseType = "arraybuffer";
  xhr.onload = function () {
    cb(xhr.response);
  };
  xhr.send();
}
```

规范
--

| Specification |
| --- |
| Media Source Extensions™ # mediasource |

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

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

参见
--

* `SourceBuffer`
* `SourceBufferList`


HTMLFormElement - Web API 接口参考

HTMLFormElement
===============

HTMLFormElement 接口可以创建或者修改`<form>`对象;它继承了`HTMLElement`接口的方法和属性。

属性
--

*继承自父类的属性，`HTMLElement`.*

`HTMLFormElement.acceptCharset` (en-US)

Is a `DOMString` that reflects the `accept-charset` HTML attribute, containing a list of character encodings that the server accepts.

`HTMLFormElement.action`

Is a `DOMString` that reflects the `action` HTML attribute, containing the URI of a program that processes the information submitted by the form.

`HTMLFormElement.autocomplete`

Is a `DOMString` that reflects the `autocomplete` HTML attribute, containing a string that indicates whether the controls in this form can have their values automatically populated by the browser.

`HTMLFormElement.elements` 只读

Returns a live `HTMLFormControlsCollection` (en-US) containing all the form controls belonging to this form element.

`HTMLFormElement.encoding` (en-US)

Is a synonym for `enctype`.

`HTMLFormElement.enctype`

Is a `DOMString` reflects the `enctype` HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set.

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

Returns a `long` that represents the number of controls in the form.

`HTMLFormElement.method` (en-US)

Is a `DOMString` that reflects the `method` HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set.

`HTMLFormElement.name` (en-US)

Is a `DOMString` that reflects the `name` HTML attribute, containing the name of the form.

`HTMLFormElement.noValidate`

Is a `Boolean` that reflects the `novalidate` HTML attribute, indicating that the form should not be validated.

`HTMLFormElement.target` (en-US)

Is a `DOMString` that reflects the `target` HTML attribute, indicating where to display the results received from submitting the form.

方法
--

*这个元素继承了 `HTMLElement` 的属性。*

`HTMLFormElement.checkValidity()`

Returns a `Boolean` that is `true` if the element's child controls are subject to constraint validation and satify those contraints, or `false` if some controls do not satisfy their constraints. Fires an event named `invalid` at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond to `false`.

`HTMLFormElement.item()`

Gets the item in the `elements` collection at the specified index, or null if there is no item at that index. You can also specify the index in array-style brackets or parentheses after the form object name, without calling this method explicitly.

`HTMLFormElement.namedItem()`

从元素集合中获取 `name` 或者 `id` 与指定名称匹配的项，没有匹配项则返回 null。你也可以像调用数组那样用圆括号或方括号来指定名称，而不必显式地调用这个方法。

`HTMLFormElement.submit()`

Submits the form to the server.

`HTMLFormElement.reset()`

Resets the forms to its initial state.

`HTMLFormElement.reportValidity()`

Returns `true` if the element's child controls satisfy their validation constraints. When `false` is returned, cancelable `invalid` (en-US) events are fired for each invalid child and validation problems are reported to the user.

Examples
--------

The following example shows how to create a new form element, modify its attributes and submit it.

```js
// Create a form
var f = document.createElement("form");

// Add it to the document body
document.body.appendChild(f);

// Add action and method attributes
f.action = "/cgi-bin/some.cgi";
f.method = "POST";

// Call the form's submit method
f.submit();
```

In addition, the following complete HTML document shows how to extract information from a form element and to set some of its attributes.

```html
<title>Form example</title>
<script type="text/javascript">
 function getFormInfo() {
 var info;

 // Get a reference using the forms collection
 var f = document.forms["formA"];
 info =
 "f.elements: " +
 f.elements +
 "\n" +
 "f.length: " +
 f.length +
 "\n" +
 "f.name: " +
 f.name +
 "\n" +
 "f.acceptCharset: " +
 f.acceptCharset +
 "\n" +
 "f.action: " +
 f.action +
 "\n" +
 "f.enctype: " +
 f.enctype +
 "\n" +
 "f.encoding: " +
 f.encoding +
 "\n" +
 "f.method: " +
 f.method +
 "\n" +
 "f.target: " +
 f.target;
 document.forms["formA"].elements["tex"].value = info;
 }

 // A reference to the form is passed from the
 // button's onclick attribute using 'this.form'
 function setFormInfo(f) {
 f.method = "GET";
 f.action = "/cgi-bin/evil\_executable.cgi";
 f.name = "totally\_new";
 }
</script>

<h1>Form example</h1>

<form name="formA" id="formA" action="/cgi-bin/test" method="POST">
  <p>
    Click "Info" to see information about the form. Click set to change
    settings, then info again to see their effect
  </p>
  <p>
    <input type="button" value="info" onclick="getFormInfo();" />
    <input type="button" value="set" onclick="setFormInfo(this.form);" />
    <input type="reset" value="reset" />
    <br />
    <textarea id="tex" style="height:15em; width:20em"> </textarea>
  </p>
</form>
```

The following example shows how to submit a form in a popup window.

```html
<!doctype html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>MDN Example</title>
    <script type="text/javascript">
 function popupSend(oFormElement) {
 if (
 oFormElement.method &&
 oFormElement.method.toLowerCase() !== "get"
 ) {
 alert("This script supports the GET method only.");
 return;
 }
 var oField,
 sFieldType,
 nFile,
 sSearch = "";
 for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) {
 oField = oFormElement.elements[nItem];
 if (!oField.hasAttribute("name")) {
 continue;
 }
 sFieldType =
 oField.nodeName.toUpperCase() === "INPUT"
 ? oField.getAttribute("type").toUpperCase()
 : "TEXT";
 if (sFieldType === "FILE") {
 for (
 nFile = 0;
 nFile < oField.files.length;
 sSearch +=
 "&" +
 escape(oField.name) +
 "=" +
 escape(oField.files[nFile++].name)
 );
 } else if (
 (sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") ||
 oField.checked
 ) {
 sSearch += "&" + escape(oField.name) + "=" + escape(oField.value);
 }
 }
 open(
 oFormElement.action.replace(/(?:\?.\*)?$/, sSearch.replace(/^&/, "?")),
 "submit-" + (oFormElement.name || Math.floor(Math.random() \* 1e6)),
 "resizable=yes,scrollbars=yes,status=yes",
 );
 }
 </script>
  </head>

  <body>
    <form
 name="yourForm"
 action="test.php"
 method="get"
 onsubmit="popupSend(this); return false;">
      <p>
        First name: <input type="text" name="firstname" /><br />
        Last name: <input type="text" name="lastname" /><br />
        Password: <input type="password" name="pwd" /><br />
        <input type="radio" name="sex" value="male" /> Male
        <input type="radio" name="sex" value="female" /> Female
      </p>
      <p>
        <input type="checkbox" name="vehicle" value="Bike" />I have a bike<br />
        <input type="checkbox" name="vehicle" value="Car" />I have a car
      </p>
      <p><input type="submit" value="Submit" /></p>
    </form>
  </body>
</html>
```

### Submitting forms and uploading files using `XMLHttpRequest`

If you want to know how to serialize and submit a form using the `XMLHttpRequest` API, please read this paragraph.

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

| Specification |
| --- |
| HTML Standard # htmlformelement |

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

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

See also
--------

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


DeviceAcceleration - Web API 接口参考

DeviceAcceleration
==================

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

设备加速对象可以提供有关设备沿三个轴（x、y、z）的加速度的信息。

属性
--

`DeviceAcceleration.x` (en-US) 只读

沿 X 轴的加速度量（只读）

`DeviceAcceleration.y` (en-US) 只读

沿 Y 轴的加速度量（只读）

`DeviceAcceleration.z` (en-US) 只读

沿 Z 轴的加速度量（只读）

说明
--

| Specification |
| --- |
| DeviceOrientation Event Specification # devicemotioneventacceleration |


AudioListener - Web API 接口参考

AudioListener
=============

`AudioListener` 接口代表了人听音乐场景时声音的位置和方向，和用于音频空间化 (en-US)。所有`PannerNode` (en-US) 相对于 `AudioListener` 的空间化储存在`BaseAudioContext.listener` 属性里。

特别需要注意的是一个环境中只能有一个收听者而且这不是`AudioNode`.

![We see the position, up and front vectors of an AudioListener, with the up and front vectors at 90° from the other.](/zh-CN/docs/Web/API/AudioListener/webaudiolistenerreduced.png)

Properties
----------

**备注：** position,forward 和 up 值是以不同的语法设置和检索的。检索是通过访问来实现的，比如说 `AudioListener.positionX` ，设置相同属性时可以通过使用 `AudioListener.positionX.value` 来完成。这就是为什么他们不被标记为只读，这在规范的接口定义中就是这么说的。

`AudioListener.positionX` (en-US)

在笛卡尔右手坐标系中代表一个收听者的水平坐标。默认值是 0.

`AudioListener.positionY` (en-US)

Represents the vertical position of the listener in a right-hand cartesian coordinate sytem. The default is 0.

`AudioListener.positionZ` (en-US)

Represents the longitudinal (back and forth) position of the listener in a right-hand cartesian coordinate sytem. The default is 0.

`AudioListener.forwardX` (en-US)

在相同的笛卡尔坐标系中代表了收听者的面向的方向的水平坐标，就像 (`positionX`, `positionY`, 和 `positionZ`) 值一样。前方和上方值互相线性无关。默认值是 0.

`AudioListener.forwardY`

Represents the vertical position of the listener's forward direction in the same cartesian coordinate sytem as the position (`positionX`, `positionY`, and `positionZ`) values. The forward and up values are linearly independent of each other. The default is 0.

`AudioListener.forwardZ` (en-US)

Represents the longitudinal (back and forth) position of the listener's forward direction in the same cartesian coordinate sytem as the position (`positionX`, `positionY`, and `positionZ`) values. The forward and up values are linearly independent of each other. The default is -1.

`AudioListener.upX` (en-US)

代表了收听者头顶在笛卡尔坐标系的水平位置，就像 (`positionX`, `positionY`, 和`positionZ`) 值一样。前方和上方值线性无关。默认值是 0.

`AudioListener.upY` (en-US)

Represents the vertical position of the top of the listener's head in the same cartesian coordinate sytem as the position (`positionX`, `positionY`, and `positionZ`) values. The forward and up values are linearly independent of each other. The default is 1.

`AudioListener.upZ` (en-US)

Represents the longitudinal (back and forth) position of the top of the listener's head in the same cartesian coordinate sytem as the position (`positionX`, `positionY`, and `positionZ`) values. The forward and up values are linearly independent of each other. The default is 0.

Methods
-------

`AudioListener.setOrientation()` (en-US)
已弃用

设置收听者的方向。

`AudioListener.setPosition()` (en-US)
已弃用

设置收听者的位置。

**备注：** Although these methods are deprecated they are currently the only way to set the orientation and position in Firefox, Internet Explorer and Safari.

Deprecated features
-------------------

`AudioListener.dopplerFactor`
已弃用

一个 Double 值，表示在呈现 多普勒效应 时要使用的音高偏移量。

`AudioListener.speedOfSound`
已弃用

一个 Double 值代表了声音的速度，以米每秒的单位计算。

In a previous version of the specification, the `dopplerFactor` and `speedOfSound` properties and the `setPosition()` method could be used to control the doppler effect applied to `AudioBufferSourceNode`s connected downstream — these would be pitched up and down according to the relative speed of the `PannerNode` (en-US) and the `AudioListener`. These features had a number of problems:

* Only `AudioBufferSourceNode`s were pitched up or down, not other source nodes.
* The behavior to adopt when an `AudioBufferSourceNode` was connected to multiple `PannerNode` (en-US)s was unclear.
* Because the velocity of the panner and the listener were not `AudioParam`s, the pitch modification could not be smoothly applied, resulting in audio glitches.

Because of these issues, these properties and methods have been removed.

The `setOrientation()` and `setPosition()` methods have been replaced by setting their property value equivilents. For example `setPosition(x, y, z)` can be achieved by setting `positionX.value`, `positionY.value`, and `positionZ.value` respectively.

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

| Specification |
| --- |
| Web Audio API # AudioListener |

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

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

See also
--------

* Using the Web Audio API (en-US)


MIDIConnectionEvent - Web API 接口参考

MIDIConnectionEvent
===================

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

The **`MIDIConnectionEvent`** interface of the Web MIDI API (en-US) is the event passed to the `onstatechange` (en-US) event of the `MIDIAccess` interface and the `onstatechange` event of the `MIDIPorts` interface. This occurs any time a new port becomes available, or when a previously available port becomes unavailable. 例如，这个事件无论是在一个 MIDI 设备插入或拔出设备时都会触发。

构造函数
----

`MIDIConnectionEvent.MIDIConnectionEvent` (en-US)

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

属性
--

`MIDIConnectionEvent.port` (en-US)

返回一个 `MIDIPort` (en-US) 实例的引用，指明其端口是否已经连接。

举例
--

规范
--

| Specification |
| --- |
| Web MIDI API # midiconnectionevent-interface |

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

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


IntersectionObserver - Web API 接口参考

IntersectionObserver
====================

**`IntersectionObserver`** 接口（从属于 Intersection Observer API）提供了一种异步观察目标元素与其祖先元素或顶级文档视口（viewport）交叉状态的方法。其祖先元素或视口被称为根（root）。

当一个 `IntersectionObserver` 对象被创建时，其被配置为监听根中一段给定比例的可见区域。一旦 `IntersectionObserver` 被创建，则无法更改其配置，所以一个给定的观察者对象只能用来监听可见区域的特定变化值；然而，你可以在同一个观察者对象中配置监听多个目标元素。

构造函数
----

`IntersectionObserver()`

创建一个新的 `IntersectionObserver` 对象，当其监听到目标元素的可见部分（的比例）超过了一个或多个**阈值**（threshold）时，会执行指定的回调函数。

实例属性
----

`IntersectionObserver.root` 只读

测试交叉时，用作边界盒的元素或文档。如果构造函数未传入 `root` 或其值为`null`，则默认使用顶级文档的视口。

`IntersectionObserver.rootMargin` 只读

计算交叉时添加到根边界盒 (en-US)的矩形偏移量，可以有效的缩小或扩大根的判定范围从而满足计算需要。此属性返回的值可能与调用构造函数时指定的值不同，因此可能需要更改该值，以匹配内部要求。所有的偏移量均可用**像素**（`px`）或**百分比**（`%`）来表达，默认值为“0px 0px 0px 0px”。

`IntersectionObserver.thresholds` (en-US) 只读

一个包含阈值的列表，按升序排列，列表中的每个阈值都是监听对象的交叉区域与边界区域的比率。当监听对象的任何阈值被越过时，都会生成一个通知（Notification）。如果构造器未传入值，则默认值为 0。

实例方法
----

`IntersectionObserver.disconnect()`

使 `IntersectionObserver` 对象停止监听目标。

`IntersectionObserver.observe()`

使 `IntersectionObserver` 开始监听一个目标元素。

`IntersectionObserver.takeRecords()`

返回所有观察目标的 `IntersectionObserverEntry` 对象数组。

`IntersectionObserver.unobserve()`

使 `IntersectionObserver` 停止监听特定目标元素。

示例
--

```js
const intersectionObserver = new IntersectionObserver((entries) => {
  // 如果 intersectionRatio 为 0，则目标在视野外，
  // 我们不需要做任何事情。
  if (entries[0].intersectionRatio <= 0) return;

  loadItems(10);
  console.log("Loaded new items");
});
// 开始监听
intersectionObserver.observe(document.querySelector(".scrollerFooter"));
```

规范
--

| Specification |
| --- |
| Intersection Observer # intersection-observer-interface |

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

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

参见
--

* `MutationObserver`
* `PerformanceObserver`
* `ResizeObserver`