IDBObjectStore - Web API 接口参考

IDBObjectStore
==============

IndexedDB API 的 **`IDBObjectStore`** 接口表示数据库中的 一个 对象库 (object store) 。对象库中的记录根据其键值进行排序。这种排序可以实现快速插入，查找和有序检索。

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

注：为了方便理解，可以把“对象存储空间”想象成关系数据库的“表”结构，下文也会把对象存储空间称为表。

方法预览
----

| `IDBRequest add (in any value, in optional any key) raises (DOMException);` |
| --- |
| `IDBRequest clear() raises (DOMException);` |
| `IDBRequest count (in optional any key) raises (DOMException);` |
| `IDBIndex createIndex (in DOMString name, in DOMString keyPath, in optional boolean unique) raises (DOMException);` |
| `IDBRequest delete (in any key) raises (DOMException);` |
| `void deleteIndex (in any DOMString indexName) raises (DOMException); |
| `IDBRequest get (in any key) raises (DOMException);` |
| `IDBIndex index (in DOMString name) raises (DOMException);` |
| `IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises(DOMException);` |
| `IDBRequest put (in any value, in optional any key) raises (DOMException);` |

属性
--

| Attribute | Type | Description |
| --- | --- | --- |
| `indexNames` | `readonly DOMStringList` | 表中对象的索引名列表。 |
| `keyPath` | `readonly` `DOMString` | 表中的键路径，如果该属性为 null，每次操作表时必须提供一个键名。 |
| `name` | `readonly` `DOMString` | 表名 |
| `transaction` | `readonly IDBTransaction` | 事务的名称，该表属于此事务。 |
| `autoIncrement` | `readonly boolean` | 表中自增字段的值 |

方法
--

### add()

返回一个 IDBRequest 对象，并且在新线程中克隆一个值，该值存储在表中。

想知道是否成功添加数据，可以在事务的 complete 事件中进行监听，而不是 success，因为事务在 success 事件之后还有可能失败。

add 方法只能插入数据。如果以 key 参数作为某记录的关键字，并且该条记录已存在，则其所返回的请求对象会产生 ConstrainError 错误。
```

IDBRequest add (in any value, in optional any key) raises (DOMException);
```

#### 参数

value

被存储的值。

key

标识某条记录的键，如果不指定，它会被设为 null。

##### 返回

IDBRequest

一个请求对象，可以在其中绑定事件。

##### 异常

该方法会抛出 DOMError 类型的 DOMException 异常。

| Exception | Description |
| --- | --- |
| ReadOnlyError |
 The transaction associated with this operation is in read-only
 mode (en-US).
  |
| TransactionInactiveError | This IDBObjectStore's transaction is inactive. |
| DataError | Any of the following conditions apply:* The object store uses in-line keys or has a key generator, and a key
 parameter was provided.
* The object store uses out-of-line keys and has no key generator, and
 no key parameter was provided.
* The object store uses in-line keys but no key generator, and the
 object store's key path does not yield a valid key.
* The key parameter was provided but does not contain a valid key.
 |
| `InvalidStateError` | The IDBObjectStore has been deleted or removed. |
| `DataCloneError` |
 The data being stored could not be cloned by the internal structured
 cloning algorithm.
  |

### clear()

创建并立即返回一个 IDBRequest 对象，并且在一个单独的线程中清除这个对象存储。清除对象存储包括从对象存储中删除所有的记录，并删除对象存储引用的索引中的所有记录。
```

IDBRequest clear () raises (DOMException);
```

#### Returns

IDBRequest

返回一个 request 对象，在其上触发与操作相关的事件。

##### Exceptions

此方法可能会引发 domException，其中 domError 的类型如下：

| Exception | Description |
| --- | --- |
| ReadOnlyError | The transaction associated with this operation is in read-only mode (en-US). |
| TransactionInactiveError | This IDBObjectStore's transaction is inactive. |

### count()

立即返回一个 IDBRequest 对象，并在新线程中计算符合条件的对象的数量，该方法的参数可以是键，或键范围（key range）。在 IDBRequest 对象中，source 属性就是 IDBObjectStore 对象，result 属性持有计算后的数量值。如果参数非法将会抛出异常。
```

IDBRequest count (in optional any key) raises(DOMException);
```

#### 参数

key

计算被该键或键范围（key range）所标识的记录数。

##### Returns

IDBRequest

一个请求对象，可绑定事件。

##### 异常

该方法会引发如下异常：

| Exception | Description |
| --- | --- |
| TransactionInactiveError | 事务已闲置 |
| DataError | key 参数非法 |
| `InvalidStateError` | IDBObjectStore 对象已被删除 |

### createIndex()

创建并返回新的 IDBIndex 对象，该方法只能从 versionchange 事务模式的回调方法中被调用。
```

IDBIndex createIndex  (in DOMString name, in DOMString keyPath, in optional boolean unique) raises (DOMException);
```

#### Parameters

name

The name of the index to create.

keyPath

The key path for the index to use.

optionalParameters

The IDBIndexParameters object whose attributes are optional parameters to the method. It includes the following properties:

| Attribute | Description |
| --- | --- |
| `unique` | If true, the index will not allow duplicate values for a single key. |
| `multiEntry` | If true, the index will add an entry in the index for each array element when the *keypath* resolves to an Array. If false, it will add one single entry containing the Array. |

##### Returns

IDBIndex

The newly created index.

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| `InvalidStateError` | The IDBObjectStore has been deleted or removed or the method was not called from a `versionchange` (en-US) transaction mode callback. |
| `ConstraintError` | An index with the same name (case-sensitive) already exists in the database. |

### delete()

Immediately returns an `IDBRequest` object, and removes the records specified by the given key or key range from this object store, and any indexes that reference it, in a separate thread.
```

IDBRequest delete (in any key) raises (DOMException);
```

#### Parameters

key

The key or key range that identifies the records.

##### Returns

IDBRequest

A request object on which subsequent events related to this operation are fired. As per spec the result of the Object Store Deletion Operation algorithm is `undefined`, so it's not possible to know if some records were actually deleted by looking at the request result.

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| TransactionInactiveError | This IDBObjectStore's transaction is inactive. |
| ReadOnlyError | The transaction associated with this operation is in read-only mode (en-US). |
| `DataError` | The key or key range provided contains an invalid key. |

**备注：** If the key that identifies the record is a Number, the key passed to the delete method must be a Number too, and not a String. So for example you might need to do the following:

```js
var key_val = "42";
var key = Number(key_val);
objectstore.delete(key);
```

### deleteIndex()

Destroys the index with the specified name in the connected database. Note that this method must be called only from a `VersionChange` transaction mode callback. Note that this method synchronously modifies the indexNames property.
```

void deleteIndex (in any DOMString indexName) raises (DOMException);
```

#### Parameters

indexName

The name of the existing index to remove.

Returns

Void

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| `InvalidStateError` | The method was not called from a `versionchange` (en-US) transaction mode callback. |
| `NotFoundError` | There is no index with the given name (case-sensitive) in the database. |

### get()

Immediately returns an IDBRequest object, and retrieves the requested record from the object store in a separate thread. If the operation is successful, then a success event is fired on the returned object, with its `result` set to the retrieved value, and `transaction` set to the transaction in which this object store is opened.
```

IDBRequest get (in any key) raises (DOMException);
```

>
> \*\*备注：\*\*This function produces the same result if no record with the given key exists in the database as when a record exists, but with an `undefined` value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and no cursor if it does not.
>
>
>

#### Parameters

key

The key or key range identifying the record to retrieve. In the case of a key range, the record returned is the first record associated with the first key in the range.

##### Returns

`IDBRequest`

A request object on which subsequent events related to this operation are fired.

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| TransactionInactiveError | This IDBObjectStore's transaction is inactive. |
| DataError | The key or key range provided contains and invalid key. |
| `InvalidStateError` | The IDBObjectStore has been deleted or removed. |

### index()

Opens the named index in this object store.
```

IDBIndex index (in DOMString name) raises (DOMException);
```

#### Parameters

name

The name of the index to open.

##### Returns

`IDBIndex`

An object for accessing the index.

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| `InvalidStateError` | The source object store has been deleted, or the transaction for the object store has finished. |
| `NotFoundError` | There is no index with the given name (case-sensitive) in the database. |

### openCursor()

Immediately returns an IDBRequest object, and creates a cursor (en-US) over the records in this object store, in a separate thread. If there is even a single record that matches the key range, then a success event is fired on the returned object, with its `result` set to the IDBCursor object for the new cursor. If no records match the key range, then a success event is fired on the returned object, with its `result` set to null.
```

IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises(DOMException);
```

#### Parameters

range

The key range to use as the cursor's range. If this parameter is unspecified or null, then the range includes all the records in the object store.

direction

The cursor's direction (en-US).

##### Returns

`IDBRequest`

A request object on which subsequent events related to this operation are fired.

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| TransactionInactiveError | This IDBObjectStore's transaction is inactive. |
| DataError | The key or key range provided contains and invalid key. |
| `InvalidStateError` | The IDBObjectStore has been deleted or removed. |
| `TypeError` | The value of the `direction` parameter is invalid. |

### put()

Returns an IDBRequest object, and, in a separate thread, creates a structured clone of the `value`, and stores the cloned value in the object store. If the record is successfully stored, then a success event is fired on the returned request object with the `result` (en-US) set to the key for the stored record, and `transaction` (en-US) set to the transaction in which this object store is opened.

The put method is an *update or insert* method. See also the add() method.
```

IDBRequest put (in any value, in optional any key) raises (DOMException);
```

#### Parameters

value

The value to be stored.

key

The key to use to identify the record. If unspecified, it results to null.

##### Returns

IDBRequest

A request object on which subsequent events related to this operation are fired.

##### Exceptions

This method may raise a DOMException (en-US) with a DOMError (en-US) of the following types:

| Exception | Description |
| --- | --- |
| ReadOnlyError |
 The transaction associated with this operation is in read-only
 mode (en-US).
  |
| TransactionInactiveError | This IDBObjectStore's transaction is inactive. |
| DataError | Any of the following conditions apply:* The object store uses in-line keys or has a key generator, and a key
 parameter was provided.
* The object store uses out-of-line keys and has no key generator, and
 no key parameter was provided.
* The object store uses in-line keys but no key generator, and the
 object store's key path does not yield a valid key.
* The key parameter was provided but does not contain a valid key.
 |
| `InvalidStateError` | The IDBObjectStore has been deleted or removed. |
| `DataCloneError` |
 The data being stored could not be cloned by the internal structured
 cloning algorithm.
  |

Example
-------

This example shows a variety of different uses of object stores, from updating the data structure with `IDBObjectStore.createIndex` (en-US) inside an `onupgradeneeded`function, to adding a new item to our object store with `IDBObjectStore.add`. For a full working example, see our To-do Notifications app (view example live.)

```js
// Let us open our database
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

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

  // store the result of opening the database in db.
  db = DBOpenRequest.result;
};

// This event handles the event whereby a new version of
// the database needs to be created Either one has not
// been created before, or a new version number has been
// submitted via the window.indexedDB.open line above
DBOpenRequest.onupgradeneeded = function (event) {
  var db = event.target.result;

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

  // Create an objectStore for this database

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

  // define what data items the objectStore will contain

  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>";
};

// Create a new item to add in to the object store
var newItem = [
  {
    taskTitle: "Walk dog",
    hours: 19,
    minutes: 30,
    day: 24,
    month: "December",
    year: 2013,
    notified: "no",
  },
];

// open a read/write db transaction, ready for adding the data
var transaction = db.transaction(["toDoList"], "readwrite");

// report on the success of the transaction completing, when everything is done
transaction.oncomplete = function (event) {
  note.innerHTML += "<li>Transaction completed.</li>";
};

transaction.onerror = function (event) {
  note.innerHTML +=
    "<li>Transaction not opened due to error. Duplicate items not allowed.</li>";
};

// create an object store on the transaction
var objectStore = transaction.objectStore("toDoList");
// make a request to add our newItem object to the object store
var objectStoreRequest = objectStore.add(newItem[0]);

objectStoreRequest.onsuccess = function (event) {
  note.innerHTML += "<li>Request successful .</li>";
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # object-store-interface |

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

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

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-dataand send us a pull request.

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.)


WebGLProgram - Web API 接口参考

WebGLProgram
============

**WebGLProgram** 是 WebGL API 的一部分，它由两个`WebGLShader`s（webgl 着色器）组成，分别为顶点着色器和片元着色器（两种着色器都是采用 GLSL 语言编写的）。创建一个 **WebGLProgram** 需要调用 GL 上下文的`createProgram()` 方法，然后调用`attachShader()`方法附加上着色器，之后你才能将它们连接到一个可用的程序。

WebGLProgram 的创建过程请参考下面的代码：

```js
var program = gl.createProgram();

// 添加预先存在的着色器
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);

gl.linkProgram(program);

if (!gl.getProgramParameter(program, gl.LINK\_STATUS)) {
  var info = gl.getProgramInfoLog(program);
  throw "WebGL program 不能编译。\n\n" + info;
}
```

查看 `WebGLShader` api 了解更多关于创建以上例子中的`顶点着色器`和`片元着色器`的信息。

示例
--

### 使用着色器程序

着色器程序在使用的过程中要分为几步，包括告知 GPU 来使用这段着色器程序，绑定合适的数据缓冲区，配置相关选项，最终把图像绘制到屏幕上。

```js
// Use the program
gl.useProgram(program);

// Bind existing attribute data
gl.bindBuffer(gl.ARRAY\_BUFFER, buffer);
gl.enableVertexAttribArray(attributeLocation);
gl.vertexAttribPointer(attributeLocation, 3, gl.FLOAT, false, 0, 0);

// Draw a single triangle
gl.drawArrays(gl.TRIANGLES, 0, 3);
```

### 删除着色器程序

如果在连接着色器程序的过程中发生了错误，或者你希望删除一个已经存在的着色器程序，你可以调用代码 `WebGLRenderingContext.deleteProgram()`，这将释放连接着色器程序的内存。

```js
gl.deleteProgram(program);
```

规范
--

| Specification |
| --- |
| WebGL Specification # 5.6 |

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

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

相关链接
----

* `WebGLShader`
* `WebGLRenderingContext.attachShader()`
* `WebGLRenderingContext.compileShader()`
* `WebGLRenderingContext.createProgram()`
* `WebGLRenderingContext.createShader()`
* `WebGLRenderingContext.deleteProgram()`
* `WebGLRenderingContext.deleteShader()`
* `WebGLRenderingContext.detachShader()`
* `WebGLRenderingContext.getAttachedShaders()` (en-US)
* `WebGLRenderingContext.getProgramParameter()` (en-US)
* `WebGLRenderingContext.getProgramInfoLog()`
* `WebGLRenderingContext.getShaderParameter()`
* `WebGLRenderingContext.getShaderPrecisionFormat()` (en-US)
* `WebGLRenderingContext.getShaderInfoLog()` (en-US)
* `WebGLRenderingContext.getShaderSource()`
* `WebGLRenderingContext.isProgram()`
* `WebGLRenderingContext.isShader()`
* `WebGLRenderingContext.linkProgram()`
* `WebGLRenderingContext.shaderSource()`
* `WebGLRenderingContext.useProgram()`
* `WebGLRenderingContext.validateProgram()`


FileSystemSyncAccessHandle - Web API 接口参考

FileSystemSyncAccessHandle
==========================

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

文件系统 API 的 **`FileSystemSyncAccessHandle`** 接口用于表示一个指向某个文件系统条目的同步句柄。

这个类只在用于处理对终端用户不可见的源私有文件系统上的文件的专用 Web Worker 中可以访问（这样它的方法就不会阻塞主线程的执行）。

因此，它的方法不受与运行在用户可见文件系统中的文件上的方法相同的安全性检查，从而具有更优秀的性能。这使得这些方法适用于重要的、大规模的文件更新，例如对 SQLite 数据库进行更改。

这个接口通过 `FileSystemFileHandle.createSyncAccessHandle()` 方法来访问。

**备注：** 在规范早期版本中，`FileSystemSyncAccessHandle` 的 `close()`、`flush()`、`getSize()` 和 `truncate()` 被错误地规定为异步方法。某些浏览器的旧版本是依照异步方式来实现这些方法的，不过，现今所有支持这些方法的浏览器都将它们实现为同步方法。

实例属性
----

无。

实例方法
----

`close()`

关闭一个打开的同步文件句柄，禁止之后对其的任何操作并且释放之前加在与文件句柄相关联的文件上的独占锁。

`flush()`

将通过 `write()` 方法对句柄相关联的文件所做的所有更改持久化保存到磁盘上。

`getSize()`

返回与句柄相关联文件的字节大小。

`read()`

将与句柄相关联文件的内容读取到指定的缓冲区中，可选择在给定的偏移处开始读取。

`truncate()`

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

`write()`

将指定缓冲区中的内容写入到与句柄相关联的文件，可选择在给定的偏移处开始写入。

示例
--

下面的异步事件处理函数包含在一个 Web Worker 中。当收到来自主线程的消息时，它将执行：

* 创建一个同步文件访问句柄。
* 获取文件的大小然后创建一个 `ArrayBuffer` 来容纳其内容。
* 将文件内容读取到缓冲区。
* 将收到的消息编码然后写入到文件的末尾。
* 将更改保存到磁盘然后关闭访问句柄。

```js
onmessage = async (e) => {
  // 接收从主线程发来的消息
  const message = e.data;

  // 获取草稿文件的句柄
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // 获取文件的大小
  const fileSize = accessHandle.getSize();
  // 读取文件内容到缓冲区
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // 将消息写入文件末尾
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // 将更改持久化至磁盘
  accessHandle.flush();

  // 用完 FileSystemSyncAccessHandle 后记得把它关闭
  accessHandle.close();
};
```

规范
--

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

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

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

参见
--

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


URL API - Web API 接口参考

URL API
=======

URL API 是一个 URL 标准的组件，它定义了有效的Uniform Resource Locator和访问、操作 URL 的 API。URL 标准还定义了像域名、主机和 IP 地址等概念，并尝试以标准的方式去描述用于以键/值对的形式提交 web 表单内容的遗留`application/x-www-form-urlencoded` MIME type 。

URL 的概念和用法
----------

URL 标准的主要内容是由 URL 的定义以及它的结构和解析方式决定的。还介绍了与网络上计算机寻址有关的各种术语的定义，并指定了解析 IP 地址和 DOM 地址的算法。大多数开发人员更感兴趣的是 API 本身。

### 使用 URL 组件

给指定的 URL 创建一个 `URL` 对象将解析 URL 并通过其属性对其组成部分的快速访问。

```js
let addr = new URL("https://developer.mozilla.org/zh-CN/docs/Web/API/URL\_API");
let host = addr.host;
let path = addr.pathname;
```

上面的代码片段为你正在阅读的文章创建一个`URL`对象，然后获取 `host` 和 `pathname` 属性。在本例中，这些字符串的值分别是`developer.mozilla.org` 和`/zh-CN/docs/Web/API/URL_API`。

### 修改 URL

`URL`对象的大部分属性都是可设置的；你可以向它们写入新值来更改对象所表示的 URL。例如，要创建一个 URL 对象并设置它的用户名：

```js
let myUsername = "someguy";
let addr = new URL("https://mysite.com/login");
addr.username = myUsername;
```

设置 `username` 值不仅是设置该属性的值，而且更新整个 URL。执行上面的代码片段后， `addr.href` 的返回值是`https://someguy@mysite.com/login`。对于任何可写属性都是如此。

### 查询

`search` 属性在 URL 上包含 URL 的查询字符串部分。例如，如果 URL 是`https://mysite.com/login?user=someguy&page=news`，那么`search` 属性的值是`?user=someguy&page=news`。你还可以使用 `URLSearchParams` 对象的 `get()` 查找单个参数的值：
```

let addr = new URL("https://mysite.com/login?user=someguy&page=news");
try {
  loginUser(addr.searchParams.get("user"));
  gotoPage(addr.searchParams.get("page"));
} catch(err) {
  showErrorMessage(err);
}
```

例如，在上面的代码片段中，从查询中提取用户名和目标页面，并将其传递给适当的函数，站点代码使用这些函数登录并将用户路由到站点的目的页面。

`URLSearchParams`中的其他函数允许修改改、添加和删除键和值，甚至对参数列表进行排序。

URL API 接口
----------

URL API 是一个简单的 API，它的名字只有几个接口：

* `URL`
* `URLSearchParams`

该规范的旧版本包括一个名为`URLUtilsReadOnly` (en-US)的接口，该接口已经合并到`WorkerLocation` (en-US) 接口中。

例子
--

如果希望处理 URL 中包含的参数，可以手动进行处理，但是创建一个 URL 对象更容易。下面的`fillTableWithParameters()`函数接受一个表示`<table>`的 `HTMLTableElement` 对象作为输入。将行添加到表中，每个行对应参数中找到的键，第一列包含键，第二列包含值。

注意，在生成表之前调用 `URLSearchParams.sort()` 对参数列表进行排序。

```js
function fillTableWithParameters(tbl) {
  let url = new URL(document.location.href);
  url.searchParams.sort();
  let keys = url.searchParams.keys();

  for (let key of keys) {
    let val = url.searchParams.get(key);
    let row = document.createElement("tr");
    let cell = document.createElement("td");
    cell.innerText = key;
    row.appendChild(cell);
    cell = document.createElement("td");
    cell.innerText = val;
    row.appendChild(cell);
    tbl.appendChild(row);
  }
}
```

在 found on Glitch上可以找到这个例子的工作版本。只要在加载页面时向 URL 添加参数，就可以在表中看到它们。例如，试试`https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable`。

规范
--

| Specification |
| --- |
| URL Standard # api |

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

### api.URL

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

### api.URLSearchParams

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

另见
--

* Fetch API
* CSS `<url>()` type


GPUCanvasContext - Web API 接口参考

GPUCanvasContext
================

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

WebGPU API 的 **`GPUCanvasContext`** 接口表示 `<canvas>` 元素的 WebGPU 渲染上下文，通过 `HTMLCanvasElement.getContext()` 调用返回 `"webgpu"` 的 `contextType`。

实例属性
----

`canvas` (en-US)
实验性
 只读

返回创建上下文的 canvas 的引用。

实例方法
----

`configure()`
实验性

使用给定的 `GPUDevice` 配置渲染上下文并清除 canvas 为透明的黑色。

`getCurrentTexture()` (en-US)
实验性

返回一个由 canvas 上下文合成到文档的 `GPUTexture` (en-US)。

`unconfigure()` (en-US)
实验性

移除预设的上下文配置，并销毁在配置 canvas 上下文时生成的任何配置。

示例
--

```js
const canvas = document.querySelector("#gpuCanvas");
const context = canvas.getContext("webgpu");

context.configure({
  device: device,
  format: navigator.gpu.getPreferredCanvasFormat(),
  alphaMode: "premultiplied",
});
```

规范
--

| Specification |
| --- |
| WebGPU # gpucanvascontext |

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

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

参见
--

* WebGPU API


MutationObserver - Web API 接口参考

MutationObserver
================

`MutationObserver` 接口提供了监视对 DOM 树所做更改的能力。它被设计为旧的 Mutation Events 功能的替代品，该功能是 DOM3 Events 规范的一部分。

构造函数
----

`MutationObserver()`

创建并返回一个新的 `MutationObserver` 它会在指定的 DOM 发生变化时被调用。

方法
--

`disconnect()`

阻止 `MutationObserver` 实例继续接收的通知，直到再次调用其 `observe()` 方法，该观察者对象包含的回调函数都不会再被调用。

`observe()`

配置 `MutationObserver` 在 DOM 更改匹配给定选项时，通过其回调函数开始接收通知。

`takeRecords()`

从 MutationObserver 的通知队列中删除所有待处理的通知，并将它们返回到 `MutationRecord` 对象的新 `Array` 中。

Mutation Observer & customize resize event listener & demo
----------------------------------------------------------

https://codepen.io/webgeeker/full/YjrZgg/

示例
--

以下示例改编自这篇博客。

```js
// 选择需要观察变动的节点
const targetNode = document.getElementById("some-id");

// 观察器的配置（需要观察什么变动）
const config = { attributes: true, childList: true, subtree: true };

// 当观察到变动时执行的回调函数
const callback = function (mutationsList, observer) {
  // Use traditional 'for loops' for IE 11
  for (let mutation of mutationsList) {
    if (mutation.type === "childList") {
      console.log("A child node has been added or removed.");
    } else if (mutation.type === "attributes") {
      console.log("The " + mutation.attributeName + " attribute was modified.");
    }
  }
};

// 创建一个观察器实例并传入回调函数
const observer = new MutationObserver(callback);

// 以上述配置开始观察目标节点
observer.observe(targetNode, config);

// 之后，可停止观察
observer.disconnect();
```

规范
--

| Specification |
| --- |
| DOM Standard # interface-mutationobserver |

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

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

参见
--

* `PerformanceObserver`
* `ResizeObserver`
* `IntersectionObserver`
* A brief overview
* A more in-depth discussion
* A screencast by Chromium developer Rafael Weinstein


Lock - Web API 接口参考

Lock
====

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

Web Locks API 的 **`Lock`** 接口提供锁的名称和模式。这可能是在 `LockManager.request()` 方法的回调中接收到的新请求的锁，也可能是 `LockManager.query()` 方法返回的活动状态的锁或队列中的锁请求。

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

实例属性
----

`Lock.mode` 只读

返回请求锁时传递给 `LockManager.request()` 的访问模式。模式可以是 `"exclusive"`（默认值）或 `"shared"`。

`Lock.name` 只读

返回请求锁时传递给 `LockManager.request()` 方法的名称。

示例
--

以下示例展示如何在对 `LockManager.request()` 的调用中传递模式和名称参数。`LockManager` 是 `navigator.locks` 属性返回的对象。

```js
navigator.locks.request("net\_db\_sync", show_lock_properties);
navigator.locks.request(
  "another\_lock",
  { mode: "shared" },
  show_lock_properties,
);

function show\_lock\_properties(lock) {
  console.log(`锁的名称是：${lock.name}`);
  console.log(`锁的模式是：${lock.mode}`);
}
```

规范
--

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

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

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


Web Audio API - Web API 接口参考

Web Audio API
=============

Web Audio API 提供了在 Web 上控制音频的一个非常有效通用的系统，允许开发者来自选音频源，对音频添加特效，使音频可视化，添加空间效果（如平移），等等。

Web audio 概念与使用
---------------

Web Audio API 使用户可以在**音频上下文**（AudioContext）中进行音频操作，具有**模块化路由**的特点。在**音频节点**上操作进行基础的音频，它们连接在一起构成**音频路由图**。即使在单个上下文中也支持多源，尽管这些音频源具有多种不同类型通道布局。这种模块化设计提供了灵活创建动态效果的复合音频的方法。

音频节点通过它们的输入输出相互连接，形成一个链或者一个简单的网。一般来说，这个链或网起始于一个或多个音频源。音频源可以提供一个片段一个片段的音频采样数据（以数组的方式），一般，一秒钟的音频数据可以被切分成几万个这样的片段。这些片段可以是经过一些数学运算得到（比如`OscillatorNode`），也可以是音频或视频的文件读出来的（比如`AudioBufferSourceNode`和`MediaElementAudioSourceNode`），又或者是音频流（`MediaStreamAudioSourceNode`）。其实，音频文件本身就是声音的采样数据，这些采样数据可以来自麦克风，也可以来自电子乐器，然后混合成一个单一的复杂的波形。

这些节点的输出可以连接到其他节点的输入上，然后新节点可以对接收到的采样数据再进行其他的处理，再形成一个结果流。一个最常见的操作是通过把输入的采样数据放大来达到扩音器的作用（缩小就是一个弱音器）（参见`GainNode`）。声音处理完成之后，可以连接到一个目的地（`AudioContext.destination`），这个目的地负责把声音数据传输给扬声器或者耳机。注意，只有当用户期望听到声音时，才需要进行最后一个这个连接。

一个简单而典型的 web audio 流程如下：

1. 创建音频上下文
2. 在音频上下文里创建源 — 例如 `<audio>`, 振荡器，流
3. 创建效果节点，例如混响、双二阶滤波器、平移、压缩
4. 为音频选择一个目的地，例如你的系统扬声器
5. 连接源到效果器，对目的地进行效果输出

![A simple box diagram with an outer box labeled Audio context, and three inner boxes labeled Sources, Effects and Destination. The three inner boxes have arrow between them pointing from left to right, indicating the flow of audio information.](/zh-CN/docs/Web/API/Web_Audio_API/audio-context_.png)

使用这个 API，时间可以被非常精确地控制，几乎没有延迟，这样开发人员可以准确地响应事件，并且可以针对采样数据进行编程，甚至是较高的采样率。这样，鼓点和节拍是准确无误的。

Web Audio API 也使我们能够控制音频的*空间化*。在基于*源 - 侦听器模型*的系统中，它允许控制*平移模型*和处理*距离引起的衰减*或移动源（移动侦听）引起的*多普勒效应*。

**备注：** 你可以阅读我们关于 Web Audio API 的文章来了解更多细节 Web Audio API 背后的基本概念。

Web Audio API 接口
----------------

Web Audio API 共有一系列接口和相关的事件，我们已经把它们分成了九类功能。

### 通用音频图定义

Web Audio API 中与生成音频图相关的定义与通用容器。

`AudioContext`

**`AudioContext`** 接口代表由音频模块构成的音频处理图。音频上下文控制其所包含节点的创建和音频处理、解码。使用其他接口前你必需创建一个`音频上下文`，一切操作都在这个环境里进行。

`AudioNode`

**`音频节点`** 接口是一个音频处理模块，例如音频源（`<audio>`或`<video>`），音频输出、中间处理模块（例如：滤波器 `BiquadFilterNode` 或者音量控制器 `GainNode`）。

`AudioParam`

**`AudioParam`** 接口代表音频相关的参数，比如一个 `AudioNode`的参数。它可以设置为特定值或值的变化，并且可以在指定的时间之后以指定模式变更。

`ended`结束事件

当媒体播放停止时，会触发`ended`事件。

### 定义音频源

Web Audio API 使用的音频源接口。

`OscillatorNode`

**`OscillatorNode`** 接口代表一种随时间变化的波形，比如正弦波形或三角波形。类型是`AudioNode`，功能是音频处理模块，可以产生指定*频率*的波形。

`AudioBuffer`

**`AudioBuffer`** 代表内存中的一段音频数据，可以通过`AudioContext.decodeAudioData()`方法从音频文件创建，也可以通过`AudioContext.createBuffer()`方法从原始数据创建。当音频数据被解码成这种格式之后，就可以被放入一个`AudioBufferSourceNode`中使用。

`AudioBufferSourceNode`

**`AudioBufferSourceNode`** 表示由内存音频数据组成的音频源，音频数据存储在`AudioBuffer`中。这是一个作为音频源的`AudioNode`。

`MediaElementAudioSourceNode`

**`MediaElementAudioSourceNode`** 接口表示由 HTML5 `<audio>`或`<video>`元素生成的音频源。这是一个作为音频源的`AudioNode`。

`MediaStreamAudioSourceNode`

**`MediaStreamAudioSourceNode`** 接口表示由 WebRTC `MediaStream`（如网络摄像头或麦克风）生成的音频源。这是一个作为音频源的`AudioNode`。

### 定义音效

应用到音频源上的音效。

`BiquadFilterNode`

**`BiquadFilterNode`** 接口表示一个简单的低阶滤波器。它是一个`AudioNode`，可以表示不同种类的滤波器、调音器或图形均衡器。`BiquadFilterNode` 总是只有一个输入和一个输出。

`ConvolverNode`

**`ConvolverNode`** 接口是一个`AudioNode`，对给定的 AudioBuffer 执行线性卷积，通常用于实现混响效果。

`DelayNode` (en-US)

**`DelayNode`** 接口表示延迟线；是`AudioNode` 类型的音频处理模块，使输入的数据延时输出。

`DynamicsCompressorNode`

**`DynamicsCompressorNode`** 提供了一个压缩效果，当多个音频在同时播放并且混合的时候，可以通过它降低音量最大的部分的音量来帮助避免发生削波和失真。

`GainNode`

**`GainNode`** 接口用于音量变化。它是一个 `AudioNode` 类型的音频处理模块，输入后应用*增益* 效果，然后输出。

`StereoPannerNode` (en-US)

**`StereoPannerNode`** 接口表示一个简单立体声控制节点，用来左右移动音频流。

`WaveShaperNode`

**`WaveShaperNode`** 接口表示一个非线性的扭曲。它是`AudioNode`类型，可以利用曲线来对信号进行扭曲。除了一些效果明显的扭曲，还常被用来给声音添加温暖的感觉。

`PeriodicWave`

用来定义周期性的波形，可被用来重塑 `OscillatorNode`的输出。

### 定义音频目的地

在你处理完音频之后，这些接口定义了输出到哪里。

`AudioDestinationNode`

**`AudioDestinationNode`** 定义了最后音频要输出到哪里，通常是输出到你的扬声器。

`MediaStreamAudioDestinationNode` (en-US)

**`MediaStreamAudioDestinationNode`** 定义了使用 WebRTC (en-US) 的`MediaStream`（只包含单个 AudioMediaStreamTrack）应该连接的目的地，AudioMediaStreamTrack 的使用方式和从`getUserMedia()`中得到`MediaStream`相似。这个接口是`AudioNode`类型的音频目的地。

### 数据分析和可视化

如果你想从音频里提取时间、频率或者其他数据，你需要 AnalyserNode。

`AnalyserNode`

**`AnalyserNode`** 表示一个可以提供实时频率分析与时域分析的切点，这些分析数据可以用做数据分析和可视化。

### 分离、合并声道

你将使用这些接口来拆分、合并声道。

`ChannelSplitterNode` (en-US)

**`ChannelSplitterNode`** 可以把输入流的每个声道输出到一个独立的输出流。

`ChannelMergerNode`

**`ChannelMergerNode`** 用于把一组输入流合成到一个输出流。输出流的每一个声道对应一个输入流。

### 声音空间效果

这些接口用来添加空间平移效果到音频源。

`AudioListener`

\*\*`AudioListener`\*\*代表场景中正在听声音的人的位置和朝向。

`PannerNode` (en-US)

**`PannerNode`** 用于表示场景是声音的空间行为。它是`AudioNode`类型的音频处理模块，这个节点用于表示右手笛卡尔坐标系里声源的位置信息，运动信息（通过一个速度向量表示），方向信息（通过一个方向圆锥表示）。

### 使用 JavaScript 处理音频

可以编写 JavaScript 代码来处理音频数据。当然，这需要用到下面的接口和事件。

**备注：** 这些功能在 Web Audio API 的 2014 年 8 月 9 日版本中已经标记为不推荐的，这些功能很快会被Audio\_Workers代替。

`ScriptProcessorNode`

**`ScriptProcessorNode`** 接口用于通过 JavaScript 代码生成，处理，分析音频。它是一个`AudioNode`类型的音频处理模块，但是它与两个缓冲区相连接，一个缓冲区里包含当前的输入数据，另一个缓冲区里包含着输出数据。每当新的音频数据被放入输入缓冲区，就会产生一个`AudioProcessingEvent` (en-US)事件，当这个事件处理结束时，输出缓冲区里应该写好了新数据。

`audioprocess` (en-US) (event)

当一个 Web Audio API `ScriptProcessorNode`已经准备好进行处理时，这个事件回调会被调用。

`AudioProcessingEvent` (en-US)

当`ScriptProcessorNode`的输入流数据准备好了时，`AudioProcessingEvent`事件会产生。

### 离线（后台）音频处理

在后台进行音频的快速处理也是可以的。仅仅生成包含音频数据的`AudioBuffer`，而不在扬声器里播放它。

`OfflineAudioContext`

**`OfflineAudioContext`** 离线音频上下文也是音频上下文`AudioContext`，也表示把`AudioNode`连接到一起的一个音频处理图。但是，与一个标准的音频上下文相比，离线上下文不能把音频渲染到扬声器，仅仅是把音频渲染到一个缓冲区。

`complete` (event)

Complete 事件，当离线音频上下文被终止时产生。

`OfflineAudioCompletionEvent` (en-US)

`OfflineAudioCompletionEvent`表示上下文被终止时的事件。

### 音频工作者

在了解这一部分内容之前，你可以先了解一个新的 WebWorker 方面的内容。音频工作者提供了一种可以在一个WebWorker上下文中直接进行音频处理的方式。现在已经定义了一些这部分功能的新接口，接口定义是在 2014 年的 8 月 29 日文档中。到目前为止，还没有浏览器已经对这些接口进行了实现。当这些接口被实现后，`ScriptProcessorNode`和前文中提到的其他接口都会被替代。

`AudioWorkerNode`

AudioWorkerNode 也是`AudioNode`类型，但是它用于与工作者线程合作来直接完成音频的生成，处理或分析等操作。

`AudioWorkerGlobalScope`

`AudioWorkerGlobalScope` 继承于 `DedicatedWorkerGlobalScope`。代表一个工作者上下文。这个工作者上下文里运行着对音频进行处理的脚本。设计这个接口的目的，是为了直接通过编写 JavaScript 代码，来完成对音频数据的生成，处理，分析工作。

`AudioProcessEvent`

这是一个事件对象。这个对象会被分发给`AudioWorkerGlobalScope`对象来进行处理。

过时的接口
-----

下面介绍到的这些接口定义于比较老的 Web Audio API 标准，现在已经过时了，而且已经被新接口取代。

`JavaScriptNode`

用于通过编写 JavaScript 代码直接处理音频数据，现在已经被`ScriptProcessorNode`取代。

`WaveTableNode`

用于定义一个周期性波形，现在已经被`PeriodicWave`取代。

示例
--

下面的这个示例使用了较多的 Web Audio API 接口，可以通过访问网址来查看它的时时运行情况，也可以访问 GitHub 上它的源代码。这个示例里会对声音的音量进行改变，打开页面时，可以先把扬声器的音量调小一些。

Web Audio API 接口在下面的代码里已经高亮显示。

```js
var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); // define audio context
// Webkit/blink browsers need prefix, Safari won't work without window.

var voiceSelect = document.getElementById("voice"); // select box for selecting voice effect options
var visualSelect = document.getElementById("visual"); // select box for selecting audio visualization options
var mute = document.querySelector(".mute"); // mute button
var drawVisual; // requestAnimationFrame

var analyser = audioCtx.createAnalyser();
var distortion = audioCtx.createWaveShaper();
var gainNode = audioCtx.createGain();
var biquadFilter = audioCtx.createBiquadFilter();

function makeDistortionCurve(amount) {
  // function to make curve shape for distortion/wave shaper node to use
  var k = typeof amount === "number" ? amount : 50,
    n_samples = 44100,
    curve = new Float32Array(n_samples),
    deg = Math.PI / 180,
    i = 0,
    x;
  for (; i < n_samples; ++i) {
    x = (i \* 2) / n_samples - 1;
    curve[i] = ((3 + k) \* x \* 20 \* deg) / (Math.PI + k \* Math.abs(x));
  }
  return curve;
}

navigator.getUserMedia(
  // constraints - only audio needed for this app
  {
    audio: true,
  },

  // Success callback
  function (stream) {
    source = audioCtx.createMediaStreamSource(stream);
    source.connect(analyser);
    analyser.connect(distortion);
    distortion.connect(biquadFilter);
    biquadFilter.connect(gainNode);
    gainNode.connect(audioCtx.destination); // connecting the different audio graph nodes together

    visualize(stream);
    voiceChange();
  },

  // Error callback
  function (err) {
    console.log("The following gUM error occured: " + err);
  },
);

function visualize(stream) {
  WIDTH = canvas.width;
  HEIGHT = canvas.height;

  var visualSetting = visualSelect.value;
  console.log(visualSetting);

  if (visualSetting == "sinewave") {
    analyser.fftSize = 2048;
    var bufferLength = analyser.frequencyBinCount; // half the FFT value
    var dataArray = new Uint8Array(bufferLength); // create an array to store the data

    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);

    function draw() {
      drawVisual = requestAnimationFrame(draw);

      analyser.getByteTimeDomainData(dataArray); // get waveform data and put it into the array created above

      canvasCtx.fillStyle = "rgb(200, 200, 200)"; // draw wave with canvas
      canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);

      canvasCtx.lineWidth = 2;
      canvasCtx.strokeStyle = "rgb(0, 0, 0)";

      canvasCtx.beginPath();

      var sliceWidth = (WIDTH \* 1.0) / bufferLength;
      var x = 0;

      for (var i = 0; i < bufferLength; i++) {
        var v = dataArray[i] / 128.0;
        var y = (v \* HEIGHT) / 2;

        if (i === 0) {
          canvasCtx.moveTo(x, y);
        } else {
          canvasCtx.lineTo(x, y);
        }

        x += sliceWidth;
      }

      canvasCtx.lineTo(canvas.width, canvas.height / 2);
      canvasCtx.stroke();
    }

    draw();
  } else if (visualSetting == "off") {
    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);
    canvasCtx.fillStyle = "red";
    canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);
  }
}

function voiceChange() {
  distortion.curve = new Float32Array();
  biquadFilter.gain.value = 0; // reset the effects each time the voiceChange function is run

  var voiceSetting = voiceSelect.value;
  console.log(voiceSetting);

  if (voiceSetting == "distortion") {
    distortion.curve = makeDistortionCurve(400); // apply distortion to sound using waveshaper node
  } else if (voiceSetting == "biquad") {
    biquadFilter.type = "lowshelf";
    biquadFilter.frequency.value = 1000;
    biquadFilter.gain.value = 25; // apply lowshelf filter to sounds using biquad
  } else if (voiceSetting == "off") {
    console.log("Voice settings turned off"); // do nothing, as off option was chosen
  }
}

// event listeners to change visualize and voice settings

visualSelect.onchange = function () {
  window.cancelAnimationFrame(drawVisual);
  visualize(stream);
};

voiceSelect.onchange = function () {
  voiceChange();
};

mute.onclick = voiceMute;

function voiceMute() {
  // toggle to mute and unmute sound
  if (mute.id == "") {
    gainNode.gain.value = 0; // gain set to 0 to mute sound
    mute.id = "activated";
    mute.innerHTML = "Unmute";
  } else {
    gainNode.gain.value = 1; // gain set to 1 to unmute sound
    mute.id = "";
    mute.innerHTML = "Mute";
  }
}
```

规范
--

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

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

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

相关链接
----

* Using the Web Audio API
* Visualizations with Web Audio API
* Voice-change-O-matic example
* Violent Theremin example
* Web audio spatialisation basics (en-US)
* Mixing Positional Audio and WebGL
* Developing Game Audio with the Web Audio API
* Porting webkitAudioContext code to standards based AudioContext (en-US)
* Tones: a simple library for playing specific tones/notes using the Web Audio API.
* howler.js: a JS audio library that defaults to Web Audio API and falls back to HTML5 Audio, as well as providing other useful features.


Cache - Web API 接口参考

Cache
=====

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

**`Cache`** 接口为缓存的 `Request` / `Response` 对象对提供存储机制，例如，作为`ServiceWorker` 生命周期的一部分。请注意，Cache 接口像 workers 一样，是暴露在 window 作用域下的。尽管它被定义在 service worker 的标准中，但是它不必一定要配合 service worker 使用。

一个域可以有多个命名 Cache 对象。你需要在你的脚本 (例如，在 `ServiceWorker` 中) 中处理缓存更新的方式。除非明确地更新缓存，否则缓存将不会被更新；除非删除，否则缓存数据不会过期。使用 `CacheStorage.open(cacheName)` 打开一个 Cache 对象，再使用 Cache 对象的方法去处理缓存。

你需要定期地清理缓存条目，因为每个浏览器都硬性限制了一个域下缓存数据的大小。缓存配额使用估算值，可以使用 `StorageEstimate` API 获得。浏览器尽其所能去管理磁盘空间，但它有可能删除一个域下的缓存数据。浏览器要么自动删除特定域的全部缓存，要么全部保留。确保按名称安装版本缓存，并仅从可以安全操作的脚本版本中使用缓存。查看 Deleting old caches (en-US) 获取更多信息。

**备注：** `Cache.put`, `Cache.add`和`Cache.addAll`只能在`GET`请求下使用。

**备注：** Initial Cache implementations (in both Blink and Gecko) resolve `Cache.add`, `Cache.addAll`, and `Cache.put` promises when the response body is fully written to storage. More recent spec versions have newer language stating that the browser can resolve the promise as soon as the entry is recorded in the database even if the response body is still streaming in.

**备注：** 自 Chrome 46 版本起，Cache API 只保存安全来源的请求，即那些通过 HTTPS 服务的请求。

**备注：** The key matching algorithm depends on the VARY header in the value. So matching a new key requires looking at both key and value for entries in the Cache.

**备注：** Cache API 不支持 HTTP 缓存头。

方法
--

`Cache.match(request, options)`

返回一个 `Promise`对象，resolve 的结果是跟 `Cache` 对象匹配的第一个已经缓存的请求。

`Cache.matchAll(request, options)`

返回一个`Promise` 对象，resolve 的结果是跟`Cache`对象匹配的所有请求组成的数组。

`Cache.add(request)`

抓取这个 URL，检索并把返回的 response 对象添加到给定的 Cache 对象。这在功能上等同于调用 fetch(), 然后使用 Cache.put() 将 response 添加到 cache 中。

`Cache.addAll(requests)`

抓取一个 URL 数组，检索并把返回的 response 对象添加到给定的 Cache 对象。

`Cache.put(request, response)`

同时抓取一个请求及其响应，并将其添加到给定的 cache。

`Cache.delete(request, options)`

搜索 key 值为 request 的`Cache` 条目。如果找到，则删除该`Cache` 条目，并且返回一个 resolve 为 true 的`Promise`对象；如果未找到，则返回一个 resolve 为 false 的`Promise`对象。

`Cache.keys(request, options)`

返回一个`Promise`对象，resolve 的结果是`Cache`对象 key 值组成的数组。

示例
--

此代码段来自 service worker selective caching sample. (请参阅 selective caching live) 。该代码使用`CacheStorage.open(cacheName)` 打开任何具有以`font/开始的`Content-Type 头的`Cache`对象。

代码然后使用`Cache.match(request, options)`查看缓存中是否已经有一个匹配的 font，如果是，则返回它。如果没有匹配的字体，代码将通过网络获取字体，并使用 `Cache.put(request, response)`来缓存获取的资源。

代码处理从`fetch()` 操作抛出的异常。请注意，HTTP 错误响应（例如 404）不会触发异常。它将返回一个具有相应错误代码集的正常响应对象。

该代码片段还展示了服务工作线程使用的缓存版本控制的最佳实践。虽然在这个例子中只有一个缓存，但同样的方法可用于多个缓存。它将缓存的速记标识符映射到特定的版本化缓存名称。代码还会删除命名不在 CURRENT\_CACHES 中的所有缓存。

**备注：** 在 Chrome 中，请访问 chrome://inspect/#service-workers，然后单击注册的服务工作线程下面的“inspect”链接，查看 service-worker.js 脚本正在执行的各种操作的日志记录。

```js
var CACHE\_VERSION = 1;

// 简写标识符映射到特定版本的缓存。
var CURRENT\_CACHES = {
  font: "font-cache-v" + CACHE\_VERSION,
};

self.addEventListener("activate", function (event) {
  var expectedCacheNames = Object.keys(CURRENT\_CACHES).map(function (key) {
    return CURRENT\_CACHES[key];
  });

  // 在 promise 成功完成之前，活跃的 worker 不会被视作已激活。
  event.waitUntil(
    caches.keys().then(function (cacheNames) {
      return Promise.all(
        cacheNames.map(function (cacheName) {
          if (expectedCacheNames.indexOf(cacheName) == -1) {
            console.log("Deleting out of date cache:", cacheName);

            return caches.delete(cacheName);
          }
        }),
      );
    }),
  );
});

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

  event.respondWith(
    // 打开以'font'开头的 Cache 对象。
    caches.open(CURRENT\_CACHES["font"]).then(function (cache) {
      return cache
        .match(event.request)
        .then(function (response) {
          if (response) {
            console.log(" Found response in cache:", response);

            return response;
          }
        })
        .catch(function (error) {
          // 处理 match() 或 fetch() 引起的异常。
          console.error(" Error in fetch handler:", error);

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

规范
--

| Specification |
| --- |
| Service Workers # cache-interface |

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

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

参见
--

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


Window.performance - Web API 接口参考

Window.performance
==================

Web Performance API 允许网页访问某些函数来测量网页和 Web 应用程序的性能，包括 Navigation Timing (en-US) API 和高分辨率时间数据。方法
--

`performance.mark()`

通过一个给定的名称，将该名称（作为键）和对应的`DOMHighResTimeStamp`（作为值）保存在一个哈希结构里。该键值对表示了从某一时刻（译者注：某一时刻通常是 navigationStart 事件发生时刻）到记录时刻间隔的毫秒数。（译者注：该方法一般用来多次记录时间，用于求得各记录间的时间差）

`performance.now()`

该方法返回一个`DOMHighResTimeStamp`对象，该对象表示从某一时刻（译者注：某一时刻通常是 navigationStart 事件发生时刻）到调用该方法时刻的毫秒数。

属性
--

`performance.timing`

是一个`PerformanceTiming` 对象，包含延迟相关的性能信息。

`performance.navigation`

是一个 `PerformanceNavigation` 对象，该对象表示在当前给定浏览上下文中网页导航的类型（译者注：TYPE\_BACK\_FORWARD，TYPE\_NAVIGATE，TYPE\_RELOAD，TYPE\_RESERVED）以及次数。

performance.memory

在 Chrome 中添加的一个非标准扩展。


MediaList - Web API 接口参考

MediaList
=========

**`MediaList`** 接口表示样式表的媒体查询，例如使用了 `media` 属性的`<link>` 元素。

**备注：** `MediaList` 是一个实时列表；使用以下属性或方法更新列表会立刻更新文档的表现。

属性
--

`MediaList.mediaText` (en-US)

一个字符串转化器，返回一个`DOMString`，以文本形式表示 `MediaList`，也可以通过这个方法设置新的 `MediaList`。

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

返回 `MediaList` 中媒体查询的数量。

方法
--

`MediaList.appendMedium()` (en-US)

向 `MediaList` 中添加一个媒体查询。

`MediaList.deleteMedium()` (en-US)

从 `MediaList` 中移除一个媒体查询。

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

一个获取函数，返回一个`CSSOMString` (en-US)，表示文本形式的媒体查询，需要提供媒体查询在 `MediaList` 中的索引位置。

示例
--

下述例子会在控制台记录 `MediaList` 的文本表示，其来自应用到当前文档的第一个样式表。

```js
const stylesheets = document.styleSheets;
let stylesheet = stylesheets[0];
console.log(stylesheet.media.mediaText);
```

规范
--

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

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

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


WebGLUniformLocation - Web API 接口参考

WebGLUniformLocation
====================

**WebGLUniformLocation** 接口是 WebGL API 的一部分，在一个着色器程序中表示一个统一变量的位置。

说明
--

`WebGLUniformLocation` 对象未定义任何属于自己并能直接访问其内容的方法和属性。在使用 `WebGLUniformLocation` 对象时，`WebGLRenderingContext` 的方法是有用的：

* `WebGLRenderingContext.getUniformLocation()` (en-US)
* `WebGLRenderingContext.uniform()`
示例
--

### 获取一个统一位置

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

var location = gl.getUniformLocation(WebGLProgram, "uniformName");
```

规范
--

| Specification |
| --- |
| WebGL Specification # 5.10 |

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

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

参见
--

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


PerformanceNavigationTiming - Web API 接口参考

PerformanceNavigationTiming
===========================

**`PerformanceNavigationTiming`** 提供了用于存储和检索有关浏览器文档事件的指标的方法和属性。例如，此接口可用于确定加载或卸载文档需要多少时间。

性能时间线中只包含当前文档，因此性能时间线中只有一个 `PerformanceNavigationTiming` 对象。它继承了 `PerformanceResourceTiming` 和 `PerformanceEntry` 的所有属性和方法。

PerformanceEntry

PerformanceResourceTiming

PerformanceNavigationTiming
下图显示了 `PerformanceNavigationTiming` 中定义的所有时间戳属性。

![按获取文档记录的顺序列出时间戳的时间戳图](/zh-CN/docs/Web/API/PerformanceNavigationTiming/timestamp-diagram.svg)

实例属性
----

该接口扩展了 `PerformanceEntry` 属性，修订和约束以下性能条目：

`PerformanceEntry.entryType` 只读

返回 `"navigation"`。

`PerformanceEntry.name` 只读

返回文档的 URL。

`PerformanceEntry.startTime` (en-US) 只读

返回值为 0 的 `DOMHighResTimeStamp`。

`PerformanceEntry.duration` (en-US) 只读

返回 `timestamp` 值，即 `PerformanceNavigationTiming.loadEventEnd` (en-US) 和 `PerformanceEntry.startTime` (en-US) 属性之间的差值。

该接口还扩展 `PerformanceResourceTiming` 属性，修订和约束以下性能条目：

`PerformanceResourceTiming.initiatorType` (en-US)只读

返回 `"navigation"`。

该接口还支持以下属性：

`PerformanceNavigationTiming.domComplete` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示用户代理将文档的 `readyState` 设置为 `"complete"` 的时间。

`PerformanceNavigationTiming.domContentLoadedEventEnd` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示当前文档的 `DOMContentLoaded` 事件处理器结束的时间。

`PerformanceNavigationTiming.domContentLoadedEventStart` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示当前文档的 `DOMContentLoaded` 事件处理器开始的时间。

`PerformanceNavigationTiming.domInteractive` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示用户代理将文档的 `readyState` 设置为 `"interactive"` 的时间。

`PerformanceNavigationTiming.loadEventEnd` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示当前文档的 `load` 事件处理器结束的时间。

`PerformanceNavigationTiming.loadEventStart` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示当前文档的 `load` 事件处理器开始的时间。

`PerformanceNavigationTiming.redirectCount` (en-US) 只读

表示在当前浏览上下文中上次非重定向导航以来的重定向次数的数字。

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

一个表示导航类型的字符串，取值为：`"navigate"`、`"reload"`、`"back_forward"` 或 `"prerender"`。

`PerformanceNavigationTiming.unloadEventEnd` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示当前文档的 `unload` 事件处理程序结束的时间。

`PerformanceNavigationTiming.unloadEventStart` (en-US) 只读

一个 `DOMHighResTimeStamp` 表示当前文档的 `unload` 事件处理程序开始的时间。

实例方法
----

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

返回一个表示 `PerformanceNavigationTiming` 对象的 JSON。

规范
--

| Specification |
| --- |
| Navigation Timing Level 2 # sec-PerformanceNavigationTiming |

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

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

参见
--

* `Performance.navigation`
* `PerformanceNavigation`


媒体捕捉与媒体流 API（媒体流） - Web API 接口参考

媒体捕捉与媒体流 API（媒体流）
=================

**媒体捕捉与媒体流 API**（Media Capture and Streams API），通常被称为**媒体流 API**（Media Streams API、MediaStream API），是与 WebRTC 相关的 API，提供对音频或视频数据流的支持。

它提供了用于处理媒体流及其组成轨道的接口和方法、与数据格式相关的约束、异步使用数据时成功和错误的回调以及在处理期间触发的事件。

概念和用法
-----

这个 API 基于对表示音视频相关数据流的 `MediaStream` 对象的所有操作。参见获取媒体流中的示例。

一个 `MediaStream` 包含零个或多个代表各种声音和视频**轨道**的 `MediaStreamTrack` 对象。每一个 `MediaStreamTrack` 可能有一个或多个**通道**。这个通道代表着媒体流的最小单元，比如一个音频信号对应着一个对应的扬声器，像是在立体声道中的*左*声道或*右*声道。

`MediaStream` 对象有着单一的**输入**和**输出**。由 `getUserMedia()` 创建的 `MediaStream` 对象是在*本地*借助用户相机和麦克风的源输入。非本地的 `MediaStream` 可能代表一个媒体元素（如 `<video>` 或 `<audio>`），或是一个通过 WebRTC `RTCPeerConnection` API 获得的源自网络的媒体流，又或是一个使用 Web 音频 API 的 `MediaStreamAudioDestinationNode` (en-US) 创建的媒体流。

`MediaStream` 对象的输出能连接到一个**消费端**（consumer）。它可以是一个媒体元素（如 `<audio>` 或 `<video>`），也可以是 WebRTC `RTCPeerConnection` API 或 Web 音频 API 的 `MediaStreamAudioSourceNode`。

接口
--

在这些参考文章中，你将找到需要了解的构成媒体捕捉和媒体流 API 的每个接口的基本信息。

* `CanvasCaptureMediaStreamTrack`
* `InputDeviceInfo` (en-US)
* `MediaDeviceInfo` (en-US)
* `MediaDevices`
* `MediaStream`
* `MediaStreamEvent`
* `MediaStreamTrack`
* `MediaStreamTrackEvent` (en-US)
* `MediaTrackConstraints`
* `MediaTrackSettings` (en-US)
* `MediaTrackSupportedConstraints` (en-US)
* `OverconstrainedError` (en-US)
* `URL`
事件
--

* `addtrack` (en-US)
* `ended` (en-US)
* `mute` (en-US)
* `overconstrained` (en-US)
* `removetrack` (en-US)
* `unmute` (en-US)
指南和教程
-----

功能、约束和设置 (en-US)文章讨论了**约束**、**功能**以及媒体设置的概念，并包含了一个约束练习器 (en-US)，它允许你尝试应用于来自计算机音视频输入设备（如网络摄像头和麦克风）的音频和视频轨道的不同约束集的结果。

使用 getUserMedia() 拍摄静态照片文章展示了如何使用 `getUserMedia()` 来访问支持 `getUserMedia()` 的计算机或移动设备上的摄像头，并使用它拍摄照片。

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

### api.MediaStream

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

### api.MediaStreamTrack

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

### api.MediaDevices

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

### api.MediaDeviceInfo

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

### api.InputDeviceInfo

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

### api.CanvasCaptureMediaStreamTrack

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

参见
--

* WebRTC——API 介绍页面
* `mediaDevices.getUserMedia()`
* 使用 WebRTC 拍摄静态照片：有关使用 `getUserMedia()` 的演示和教程。


Location - Web API 接口参考

Location
========

**`Location`** 接口表示其链接到的对象的位置（URL）。所做的修改反映在与之相关的对象上。 `Document` 和 `Window` 接口都有这样一个链接的 Location，分别通过 `Document.location`和`Window.location` 访问。

属性
--

*`Location` 接口不继承任何属性，但是实现了那些来自 `URLUtils` 的属性。*

`Location.href`

包含整个 URL 的一个`DOMString`

`Location.protocol`

包含 URL 对应协议的一个`DOMString`，最后有一个":"。

`Location.host`

包含了域名的一个`DOMString`，可能在该串最后带有一个":"并跟上 URL 的端口号。

`Location.hostname`

包含 URL 域名的一个`DOMString`。

`Location.port` (en-US)

包含端口号的一个`DOMString`。

`Location.pathname` (en-US)

包含 URL 中路径部分的一个`DOMString`，开头有一个 `/`。

`Location.search`

包含 URL 参数的一个`DOMString`，开头有一个`“?”`。

`Location.hash`

包含块标识符的`DOMString`，开头有一个 `#`。

`Location.username` (en-US)

包含 URL 中域名前的用户名的一个`DOMString`。

`Location.password` (en-US)

包含 URL 域名前的密码的一个 `DOMString`。

`Location.origin` (en-US) 只读

包含页面来源的域名的标准形式`DOMString`。

方法
--

*`Location` 没有继承任何方法*，但实现了来自`URLUtils`*的方法。*

`Location.assign()`

加载给定 URL 的内容资源到这个 Location 对象所关联的对象上。

`Location.reload()`

重新加载来自当前 URL 的资源。他有一个特殊的可选参数，类型为 `Boolean` (en-US)，该参数为 true 时会导致该方法引发的刷新一定会从服务器上加载数据。如果是 `false`或没有制定这个参数，浏览器可能从缓存当中加载页面。

`Location.replace()`

用给定的 URL 替换掉当前的资源。与 `assign()` 方法不同的是用 `replace()`替换的新页面不会被保存在会话的历史 `History`中，这意味着用户将不能用后退按钮转到该页面。

`Location.toString()`

返回一个`DOMString`，包含整个 URL。它和读取`URLUtils.href`的效果相同。但是用它是不能够修改 Location 的值的。

例子
--

```js
// Create anchor element and use href property for the purpose of this example
// A more correct alternative is to browse to the URL and use document.location or window.location
var url = document.createElement("a");
url.href =
  "https://developer.mozilla.org/en-US/search?q=URL#search-results-close-container";
console.log(url.href); // https://developer.mozilla.org/en-US/search?q=URL#search-results-close-container
console.log(url.protocol); // https:
console.log(url.host); // developer.mozilla.org
console.log(url.hostname); // developer.mozilla.org
console.log(url.port); // (blank - https assumes port 443)
console.log(url.pathname); // /en-US/search
console.log(url.search); // ?q=URL
console.log(url.hash); // #search-results-close-container
console.log(url.origin); // https://developer.mozilla.org
```

规范
--

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

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

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

另见
--

* Two methods creating such an object: `Window.location` and `Document.location`.


CaretPosition - Web API 接口参考

CaretPosition
=============

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

`CaretPosition` 接口表示光标位置，即文本插入点的指示器。你可以使用 `Document.caretPositionFromPoint()` 方法获取 `CaretPosition`。

实例属性
----

*该接口不继承任何属性。*

`CaretPosition.offsetNode` 只读
实验性

返回一个包含光标位置节点的 `Node`。

`CaretPosition.offset` 只读
实验性

返回一个 `long`，表示光标位置在节点中的字符偏移量。

实例方法
----

`CaretPosition.getClientRect`
实验性

返回光标范围的客户端矩形。

规范
--

| Specification |
| --- |
| CSSOM View Module # caret-position |

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

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

参见
--

* `Document.caretPositionFromPoint()`
* `Range`
* `Node`


Document - Web API 接口参考

Document
========

**`Document`** 接口表示任何在浏览器中载入的网页，并作为网页内容的入口，也就是 DOM 树 (en-US)。

DOM 树包含了像 `<body>`、`<table>` 这样的元素，以及大量其他元素。它向网页文档本身提供了全局操作功能，能解决如何获取页面的 URL，如何在文档中创建一个新的元素这样的问题。

EventTarget

Node

Document
`Document` 接口描述了任何类型的文档的通用属性与方法。根据不同的文档类型（例如 HTML、XML (en-US)、SVG，...），还能使用更多 API：使用 `"text/html"` 作为内容类型（content type）的 HTML 文档，还实现了 `HTMLDocument` 接口，而 XML 和 SVG 文档则（额外）实现了 `XMLDocument` 接口。

构造函数
----

`Document()`

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

属性
--

*此接口也继承自 `Node` 和 `EventTarget` 接口。*

`Document.activeElement` 只读

返回一个目前处于聚焦状态的 `Element`。

`Document.adoptedStyleSheets` (en-US)

设置用于构造文档样式表的数组。这些样式表也可与同一文档的 shadow DOM 子树共享。

`Document.body`

返回当前文档的 `<body>` 或 `<frameset>` 节点。

`Document.characterSet` 只读

返回文档正在使用的字符集。

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

返回文档正在使用的子元素的数量。

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

返回当前文档的子元素。

`Document.compatMode` 只读

指示文档是否以*怪异模式*（quirks）或*严格模式*（strict）渲染。

`Document.contentType` 只读

根据当前文档的 MIME 标头，返回它的 Content-Type。

`Document.currentScript` 只读

返回目前正在处理且不是 JavaScript 模块的 `<script>` 元素。

`Document.doctype` 只读

返回当前文档的文档类型定义（Document Type Definition，DTD）。

`Document.documentElement` 只读

返回当前文档的直接子节点。对于 HTML 文档，`HTMLHtmlElement` 对象一般代表该文档的`<html>` 元素。

`Document.documentURI` 只读

以字符串的类型，返回当前文档的路径。

`Document.embeds` 只读

返回一个包含当前文档的嵌入式的元素 `<embed>` 的 `HTMLCollection`。

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

返回当前文档的第一个子元素。

`Document.fonts`

返回当前文档的 `FontFaceSet` 接口。

`Document.forms` 只读

返回一个包含当前文档中所有表单元素 `<form>` 的 `HTMLCollection`。

`Document.fullscreenElement` 只读

返回文档中正处于全屏模式的元素。

`Document.head` 只读

返回当前文档的 `<head>` 元素。

`Document.hidden` 只读

返回一个布尔值，表明当前页面是否隐藏。

`Document.images` 只读

返回当前文档中所包含的图片的 `HTMLCollection`。

`Document.implementation` 只读

返回与当前文档相关联的 DOM 实现。

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

返回当前文档的最后一个子元素。

`Document.links` 只读

返回一个包含文档中所有超链接的 `HTMLCollection`。

`Document.pictureInPictureElement` 只读

返回文档中正处于画中画模式的 `Element`。

`Document.pictureInPictureEnabled` 只读

若画中画特性可用，则返回 `true`。

`Document.plugins` 只读

返回一个包含可用插件的 `HTMLCollection`。

`Document.pointerLockElement` 只读

当指针被锁定时，返回鼠标事件的目标的元素集合。若锁定正处于等待状态、指针已被解锁，或是目标正处于另一个文档中，则返回 `null`。

`Document.featurePolicy` (en-US)
实验性
 只读

返回一个 `FeaturePolicy` (en-US) 接口，该结构为应用于特定文档的特性策略提供了一个简单的 API。

`Document.scripts` 只读

返回包含文档中所有的 `<script>` 元素的 `HTMLCollection`。

`Document.scrollingElement` 只读

返回对滚动文档的 `Element` 的引用。

`Document.styleSheets` 只读

返回一个包含显式链接或嵌入到文档中的 `CSSStyleSheet` 对象的 `StyleSheetList`。

`Document.timeline` 只读

返回 `DocumentTimeline` (en-US) 的一个实例，该实例是在页面加载时自动创建的。

`Document.visibilityState` 只读

返回一个 `string`，表明当前文档的可见性。可能的取值有 `visible`、`hidden`、`prerender` 和 `unloaded`。

### HTMLDocument 的扩展

*HTML 文件的 `Document` 接口继承自 `HTMLDocument` 接口，或扩展了这些方法：*

`Document.cookie`

返回一个使用分号分隔的 cookie 列表，或设置（写入）一个 cookie。

`Document.defaultView` 只读

返回一个对 `window` 对象的引用。

`Document.designMode`

获取或设置编辑整个文档的能力。

`Document.dir`

获取或设置文档的文字方向（rtl 或 ltr）。

`Document.domain`
已弃用

获取或设置当前文档的域。

`Document.lastModified` 只读

返回文档最后修改的时间。

`Document.location` 只读

返回当前文档的 URI。

`Document.readyState` 只读

返回当前文档的加载状态。

`Document.referrer` 只读

返回来源页面的 URI。

`Document.title`

获取或设置当前文档的标题。

`Document.URL` 只读

以字符串形式返回文档的地址栏链接。

### 已弃用的属性

`Document.alinkColor`
已弃用

获取或设置文档正文部分启用的链接的颜色。

`Document.all`
已弃用

返回一个以文档节点为根节点的 `HTMLAllCollection` (en-US) 集合，以访问文档中所有的元素。这是遗留的非标准属性，不应使用。

`Document.anchors`
已弃用
 只读

返回文档中所有锚点元素的列表。

`Document.applets`
已弃用
 只读

返回文档中 `applet` 对象的有序列表。

`Document.bgColor`
已弃用

获取或设置当前文档的背景颜色。

`Document.charset`
已弃用
 只读

`Document.characterSet` 的别名，请使用原始属性替换。

`Document.fullscreen`
已弃用

若文档处于全屏模式，则返回 `true`。

`Document.height`
非标准

已弃用

获取或设置当前文档的高度。

`Document.inputEncoding` (en-US) 只读
已弃用

`Document.characterSet` 的别名，请使用原始属性替换。

`Document.lastStyleSheetSet`
已弃用
 只读
非标准

返回最后启用的样式表的名字。在设置 `selectedStyleSheetSet` 前，其值都为 `null`。

`Document.linkColor`
已弃用

获取或设置文档中超链接的颜色。

`Document.preferredStyleSheetSet`
已弃用
 只读
非标准

返回文档作者首选的样式表。

`Document.rootElement` (en-US)
已弃用

类似于 `Document.documentElement`，但其仅用于 `<svg>` 根元素。请使用后者代替。

`Document.selectedStyleSheetSet`
已弃用
 只读

返回当前正使用的样式表的集合。

`Document.styleSheetSets`
已弃用
 只读
非标准

返回文档上可用样式表的集合。

`Document.vlinkColor` (en-US)
已弃用

获取或设置被访问的超链接的颜色。

`Document.width`
非标准

已弃用

返回当前文档的宽度。

`Document.xmlEncoding` (en-US)
已弃用

返回由 XML 声明的编码类型。

`Document.xmlStandalone`
已弃用

若 XML 声明指定的文档是独立的（例如：文档类型定义的外部内容会影响文档的内容），则返回 `true`，否则返回 `false`。

`Document.xmlVersion` (en-US)
已弃用

返回 XML 声明中指定的版本号，若声明不存在则为 `"1.0"`。

方法
--

*该接口同样继承了 `Node` 和 `EventTarget` 接口。*

`Document.adoptNode()`

从外部文档中采用的节点。

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

在文档的最后一个子节点后插入一个 `Node` 对象或字符串对象的集合。

`Document.captureEvents()`
已弃用

参见 `Window.captureEvents` (en-US)。

`Document.caretPositionFromPoint()`

返回一个包含 DOM 节点（包含插入符号以及该符号在节点中的字符偏移量）的 `CaretPosition` 对象。

`Document.caretRangeFromPoint()`
非标准

获取一个 `Range` 对象，其为指定坐标下的文档片段。

`Document.createAttribute()`

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

`Document.createAttributeNS()` (en-US)

在给定命名空间创建一个新的属性节点并返回。

`Document.createCDATASection()`

创建一个新的数据（CDATA）节点并返回。

`Document.createComment()`

创建一个新的注释节点并返回。

`Document.createDocumentFragment()`

创建一个新的文档片段。

`Document.createElement()`

用给定标签名创建一个新的元素。

`Document.createElementNS()`

用给定标签名和命名空间创建一个新的元素。

`Document.createEntityReference()` (en-US)
已弃用

创建一个新的实体引用对象并返回。

`Document.createEvent()`

创建一个事件对象。

`Document.createNodeIterator()`

创建一个 `NodeIterator` 对象。

`Document.createProcessingInstruction()`

创建一个新的 `ProcessingInstruction` (en-US) 对象。

`Document.createRange()`

创建一个 `Range` 对象。

`Document.createTextNode()`

创建一个文本节点。

`Document.createTouch()` (en-US)
已弃用

非标准

创建一个 `Touch` 对象。

`Document.createTouchList()` (en-US)
已弃用

非标准

创建一个 `TouchList` 对象。

`Document.createTreeWalker()`

创建一个 `TreeWalker` 对象。

`Document.elementFromPoint()`

返回指定坐标最顶层的元素。

`Document.elementsFromPoint()`

返回包含指定坐标下所有元素的数组。

`Document.enableStyleSheetsForSet()` (en-US)
已弃用

非标准

启用指定的样式表集合。

`Document.exitPictureInPicture()`

从浮动的画中画窗口中移除视频，并返回到它的原始容器。

`Document.exitPointerLock()`

释放指针锁。

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

返回包含所有目前有效的 `Animation` 对象（其目标元素为 `document`）的数组。

`Document.getBoxQuads()`
实验性

返回一个 `DOMQuad` 对象（表示节点中的 CSS 片段）的列表。

`Document.getElementById()`

返回标识元素的引用对象。

`Document.getElementsByClassName()`

返回具有给定类名的元素列表。

`Document.getElementsByTagName()`

返回具有给定标签名的元素列表。

`Document.getElementsByTagNameNS()`

返回具有给定标签名和命名空间的元素列表。

`Document.getSelection()` (en-US)

返回一个 `Selection` 对象，表示用户选择的文本范围或是插入符号当前的位置。

`Document.hasStorageAccess()`

返回一个 `Promise`，会兑现一个布尔值，用于表示文档是否有访问第一方储存的权限。

`Document.importNode()`

返回外部文档的节点的拷贝。

`Document.normalizeDocument()`
已弃用

替换实体、规范化文本节点，等待。

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

在文档的第一个子节点前插入一个 `Node` 对象或字符串对象的集合。

`Document.querySelector()`

返回文档中与指定的选择器匹配的第一个元素节点。

`Document.querySelectorAll()`

返回包含文档中与指定的选择器匹配的所有元素节点的列表。

`Document.releaseCapture()`
非标准

若鼠标在当前文档的某一个元素之上，则释放当前的鼠标捕获。

`Document.releaseEvents()`
已弃用

参见 `Window.releaseEvents()` (en-US)。

`Document.replaceChildren()` (en-US)

用一哥指定的新的子节点集合替换替换文档中现有的子节点。

`Document.requestStorageAccess()` (en-US)

返回一个 `Promise`，若第一方存储权限可用，则兑现，否则拒绝。

`Document.mozSetImageElement()` (en-US)
非标准

允许你使用具有给定 ID 的元素作为背景图片。

`Document` 接口使用 `XPathEvaluator` 接口扩展：

`Document.createExpression()`

编译一个 `XPathExpression` (en-US)，以用于（重复）执行。

`Document.createNSResolver()` (en-US)

创建一个 `XPathNSResolver` (en-US) 对象。

`Document.evaluate()`

执行一个 XPath 表达式。

### HTML 文档的扩展

HTML 文档的 `Document` 接口继承自 `HTMLDocument` 接口，或扩展了这些方法：

`Document.clear()`
已弃用

在大多数现代浏览器中，包括最新版本的 Firefox 和 Internet Explorer，这个方法没有任何作用。

`Document.close()`

关闭用于写入的文档流。

`Document.execCommand()`
已弃用

在可编辑文档中执行格式化命令。

`Document.getElementsByName()`

返回一个具有给定名称的元素的列表。

`Document.hasFocus()`

若焦点目前位于给定的文档内，则返回 `true`。

`Document.open()`

打开用于写入的文档流。

`Document.queryCommandEnabled()`
已弃用

非标准

若可在当前范围内执行格式化命令，则返回 `true`。

`Document.queryCommandIndeterm()`
已弃用

若格式化命令在当前范围内处于不确定的状态，则返回 `true`。

`Document.queryCommandState()`
已弃用

非标准

若格式化命令已在当前范围内执行，则返回 `true`。

`Document.queryCommandSupported()`
已弃用

非标准

若当前范围支持格式化命令，则返回 `true`。

`Document.queryCommandValue()`
已弃用

返回格式化命令当前的范围。

`Document.write()`

向文档写入文本。

`Document.writeln()`

向文档写入一行文本。

事件
--

列出了使用 `addEventListener()` 或为接口的事件处理器属性 `oneventname` 赋值的方式来监听的事件。

`afterscriptexecute`
非标准

在静态的 `<script>` 元素执行完其中的脚本时触发。

`beforescriptexecute`

在静态的 `<script>` 开始执行脚本时触发。

`scroll`

在滚动文档视图或元素时触发。

`visibilitychange`

在变前的内容变为可见、隐藏时触发。

`wheel` (en-US)

在用户在点击设备（通常为鼠标）上转动滚轮时触发。

### 动画事件

`animationcancel` (en-US)

在动画意外中止时触发。

`animationend` (en-US)

在动画正常完成时触发。

`animationiteration` (en-US)

在动画迭代完成时触发。

`animationstart` (en-US)

在动画开始时触发。

### 剪切板事件

`copy` (en-US)

在用户通过浏览器的用户界面使用复制操作时触发。

`cut` (en-US)

在用户通过浏览器的用户界面使用剪切操作时触发。

`paste` (en-US)

在用户通过浏览器的用户界面使用粘贴操作时触发。

### 拖放事件

`drag`

在用户拖动元素或选择的文本时每几百毫秒触发一次。

`dragend`

在拖动操作结束（通过释放鼠标按钮或按下退出键））时触发。

`dragenter`

在拖动的元素或选择的文本进入有效的放置目标时触发。

`dragleave`

在拖动的元素或选择的文本离开有效的放置目标时触发。

`dragover`

在拖动的元素或选择的文本在有效的放置目标时触发（每几百毫秒）。

`dragstart`

在用户开始拖动元素或选择的文本时触发。

`drop`

在元素或选择的文本被放置在有效的放置目标时触发。

### 全屏事件

`fullscreenchange`

在 `Document` 进入或退出全屏模式时触发。

`fullscreenerror`

在尝试进入或退出全屏模式而发生错误时触发。

### 键盘事件

`keydown` (en-US)

在某个键被按下时触发。

`keypress`
已弃用

在按下产生字符值的键时触发。

`keyup` (en-US)

在释放按键时触发。

### 加载和卸载事件

`DOMContentLoaded`

在文档完全加载并解析后触发，无需等待样式表、图像和子框架完成加载。

`readystatechange`

在文档的 `readyState` 属性发生变化时触发。

### 指针事件

`gotpointercapture` (en-US)

在使用 `setPointerCapture()` 捕获元素时触发。

`lostpointercapture` (en-US)

在捕获指针释放时触发。

`pointercancel` (en-US)

在指针事件取消时触发。

`pointerdown` (en-US)

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

`pointerenter` (en-US)

在指针移入到元素或其子元素之一的命中测试边界时触发。

`pointerleave` (en-US)

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

`pointerlockchange`

在指针被锁定或解锁时触发。

`pointerlockerror` (en-US)

在指针锁定失败时触发。

`pointermove` (en-US)

在指针坐标改变时触发。

`pointerout` (en-US)

在指正移除元素的*命中测试*边界（或其他原因）时触发。

`pointerover` (en-US)

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

`pointerup` (en-US)

在指针不再活动时触发。

### 选择事件

`selectionchange`

在文档中的选中的文本发生改变时触发。

### 触摸事件

`touchcancel`

在一个或多个接触点以特定于实现的方式中断（例如，创建了太多的接触点）时触发。

`touchend`

在从接触面移除一个或多个接触点时触发。

`touchmove`

在一个或多个接触点沿接触面移动时触发。

`touchstart`

在向接触面放置一个或多个接触点时触发。

### 过渡事件

`transitioncancel` (en-US)

在 CSS 过渡取消时触发。

`transitionend` (en-US)

在 CSS 过渡完成时触发。

`transitionrun` (en-US)

在 CSS 过渡第一次创建时触发。

`transitionstart` (en-US)

在 CSS 过渡实际开始时触发。

规范
--

| Specification |
| --- |
| DOM Standard # interface-document |
| HTML Standard # the-document-object |
| CSSOM View Module # extensions-to-the-document-interface |
| Pointer Lock 2.0 # extensions-to-the-document-interface |
| Selection API # extensions-to-document-interface |

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

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


queueMicrotask() - Web API 接口参考

queueMicrotask()
================

`Window` 或 `Worker` 接口的 **`queueMicrotask()`** 方法，将微任务加入队列以在控制返回浏览器的事件循环之前的安全时间执行。

微任务是一个简短的函数，它将在当前任务完成其工作后运行，并且在执行上下文的控制权返回到浏览器的事件循环之前没有其他代码等待运行时运行。

它让你的代码在运行时不会干扰任何可能具有更高优先级的代码的运行，但在浏览器重新获得对执行上下文的控制之前，这可能取决于你需要完成的工作。你可以在我们的微任务指南中了解更多关于如何使用微任务以及选择这样做的原因。

微任务的重要性在于它能够以特定顺序异步执行任务。查看在 JavaScript 中通过 queueMicrotask() 使用微任务的详情。

微任务对于需要执行最后阶段的任务或其他在渲染之前的任务的库和框架特别有用。

语法
--
```

queueMicrotask(() => {/* ... */});
```

### 参数

`function`

当浏览器引擎确定可以安全调用你的代码时执行的 `function`。微任务（microtask）的执行顺序在所有进行中的任务（pending task）完成之后，在对浏览器的事件循环产生控制（yielding control to the browser's event loop）之前。

### 返回值

无（`undefined`）。

示例
--

```js
queueMicrotask(() => {
  // 函数的内容
});
```

来自 `queueMicrotask` 的规范文档：

```js
MyElement.prototype.loadData = function (url) {
  if (this._cache[url]) {
    queueMicrotask(() => {
      this.\_setData(this._cache[url]);
      this.dispatchEvent(new Event("load"));
    });
  } else {
    fetch(url)
      .then((res) => res.arrayBuffer())
      .then((data) => {
        this._cache[url] = data;
        this.\_setData(data);
        this.dispatchEvent(new Event("load"));
      });
  }
};
```

规范
--

| Specification |
| --- |
| HTML Standard # microtask-queuing |

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

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

参见
--

* Polyfill of `queueMicrotask()` in `core-js`
* Using microtasks in JavaScript with queueMicrotask()
* Asynchronous JavaScript
* queueMicrotask explainer
* Tasks, microtasks, queues and schedules by Jake Archibald


GamepadPose - Web API 接口参考

GamepadPose
===========

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

Gamepad API的接口\*\*`GamepadPose`\*\* 表示 WebVR 的控制者在某个给定时间点的姿势， (包括方向、位置、速率、加速度信息)

这个接口通过 `Gamepad.pose` (en-US) 属性使用。

属性
--

`GamepadPose.hasOrientation` (en-US) 只读

Returns a boolean indicating whether the gamepad is capable of returning orientation information (`true`) or not (`false`).

`GamepadPose.hasPosition` (en-US) 只读

Returns a boolean indicating whether the gamepad is capable of returning position information (`true`) or not (`false`).

`GamepadPose.position` (en-US) 只读

Returns the position of the `Gamepad` as a 3D vector.

`GamepadPose.linearVelocity` (en-US) 只读

Returns the linear velocity of the `Gamepad`, in meters per second.

`GamepadPose.linearAcceleration` (en-US) 只读

Returns the linear acceleration of the `Gamepad`, in meters per second per second.

`GamepadPose.orientation` (en-US) 只读

Returns the orientation of the `Gamepad`, as a quarternion value.

`GamepadPose.angularVelocity` (en-US) 只读

Returns the angular velocity of the `Gamepad`, in radians per second.

`GamepadPose.angularAcceleration` (en-US) 只读

Returns the angular acceleration of the `Gamepad`, in meters per second per second.

Examples
--------

TBD.

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

| Specification |
| --- |
| Gamepad Extensions # gamepadpose-interface |

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

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

See also
--------

* WebVR API
* Gamepad API


CSS 自定义高亮 API - Web API 接口参考

CSS 自定义高亮 API
=============

CSS 自定义高亮 API 提供了一种方法，可以通过使用 JavaScript 创建范围并使用 CSS 定义样式来设置文档中任意文本范围的样式。

概念与用法
-----

在网页上设置文本范围样式非常有用。例如，文本编辑类的 Web 应用程序会突出显示拼写或语法错误，代码编辑器会突出显示语法错误。

CSS 自定义高亮 API 通过提供一种创建任意 `Range` 对象并设置其样式的方法（而不是局限于浏览器定义的范围），扩展了其他高亮伪元素的概念，例如 `::selection`、`::spelling-error`、`::grammar-error` 和 `::target-text`。

使用 CSS 自定义高亮 API，你可以通过编程方式创建文本范围并高亮显示它们，而不会影响页面中的 DOM 结构。

使用 CSS 自定义高亮 API 设置网页上文本范围的样式有四个步骤：

1. 创建 `Range` 对象。
2. 为这些范围创建 `Highlight` (en-US) 对象。
3. 使用 `HighlightRegistry` (en-US) 进行注册。
4. 使用 `::highlight()` (en-US) 伪元素定义高亮样式。
### 创建范围

第一步是使用 JavaScript 创建 `Range` 对象，标明你想设置样式的文本范围。例如：

```js
const parentNode = document.getElementById("foo");

const range1 = new Range();
range1.setStart(parentNode, 10);
range1.setEnd(parentNode, 20);

const range2 = new Range();
range2.setStart(parentNode, 40);
range2.setEnd(parentNode, 60);
```

### 创建高亮

第二步是为你的文本范围实例化 `Highlight` (en-US) 对象

多个范围可以关联到一个高亮显示。如果你希望以相同的方式高亮显示多个文本片段，只需要创建一个高亮并使用相应的范围初始化它。

```js
const highlight = new Highlight(range1, range2);
```

但你也可以根据需要创建任意多的高亮。例如，如果你正在构建一个协作文本编辑器，其中每个用户获得不同的文本颜色，那么你可以为每个用户创建一个高亮显示，如下所示：

```js
const user1Highlight = new Highlight(user1Range1, user1Range2);
const user2Highlight = new Highlight(user2Range1, user2Range2, user2Range3);
```

每个高亮可以设置不同的样式。

### 注册高亮

创建高亮显示后，使用 `HighlightRegistry` (en-US) 将其注册为 `CSS.highlights` (en-US)。

注册表是一个类 `Map` 对象，用于通过名称注册高亮，如下所示：

```js
CSS.highlights.set("user-1-highlight", user1Highlight);
CSS.highlights.set("user-2-highlight", user2Highlight);
```

在上面的代码片段中，`user-1-highlight` 和 `user-2-highlight` 是自定义标识符，用于将 CSS 中的样式应用到已注册的高亮显示上。

你可以在注册表中注册任意数量的高亮显示，也可以删除高亮显示并清除整个注册表。

```js
// 从注册表中删除一个高亮显示。
CSS.highlights.delete("user-1-highlight");

// 清除注册表。
CSS.highlights.clear();
```

### 高亮样式

最后一步是为已注册高亮显示设置样式。可以使用 `::highlight()` (en-US) 伪元素来完成。例如，为上一步注册的 `user-1-highlight` 设置高亮样式：

```css
::highlight(user-1-highlight) {
  background-color: yellow;
  color: black;
}
```

接口
--

`Highlight` (en-US)

此接口用于表示要在文档上设置样式的范围集合。

`HighlightRegistry` (en-US)

可以通过 `CSS.highlights` (en-US) 访问，类 `Map` 对象用于使用自定义标识符注册高亮显示。

示例
--

### 高亮显示搜索结果

本示例展示了如何使用 CSS 自定义高亮 API 高亮显示搜索结果。

#### HTML

下面的 HTML 代码片段定义了一个搜索框和有几段文字的文章：

```html
<label>Search within text <input id="query" type="text" /></label>
<article>
  <p>
    Maxime debitis hic, delectus perspiciatis laborum molestiae labore,
    deleniti, quam consequatur iure veniam alias voluptas nisi quo. Dolorem
    eaque alias, quo vel quas repudiandae architecto deserunt quidem, sapiente
    laudantium nulla.
  </p>
  <p>
    Maiores odit molestias, necessitatibus doloremque dolor illum reprehenderit
    provident nostrum laboriosam iste, tempore perferendis! Ab porro neque esse
    voluptas libero necessitatibus fugiat, ex, minus atque deserunt veniam
    molestiae tempora? Vitae.
  </p>
  <p>
    Dolorum facilis voluptate eaque eius similique ducimus dignissimos assumenda
    quos architecto. Doloremque deleniti non exercitationem rerum quam alias
    harum, nisi obcaecati corporis temporibus vero sapiente voluptatum est
    quibusdam id ipsa.
  </p>
</article>
```

#### JavaScript

使用 JavaScript 监听搜索框上的 `input` 事件，当事件触发，这段代码将在文章的文本中为输入文本查找匹配项。然后它创建匹配的范围，并使用 CSS 自定义高亮 API 创建并注册一个 `search-results` 高亮对象：

```js
const query = document.getElementById("query");
const article = document.querySelector("article");

// Find all text nodes in the article. We'll search within
// these text nodes.
const treeWalker = document.createTreeWalker(article, NodeFilter.SHOW\_TEXT);
const allTextNodes = [];
let currentNode = treeWalker.nextNode();
while (currentNode) {
  allTextNodes.push(currentNode);
  currentNode = treeWalker.nextNode();
}

// Listen to the input event to run the search.
query.addEventListener("input", () => {
  // If the CSS Custom Highlight API is not supported,
  // display a message and bail-out.
  if (!CSS.highlights) {
    article.textContent = "CSS Custom Highlight API not supported.";
    return;
  }

  // Clear the HighlightRegistry to remove the
  // previous search results.
  CSS.highlights.clear();

  // Clean-up the search query and bail-out if
  // if it's empty.
  const str = query.value.trim().toLowerCase();
  if (!str) {
    return;
  }

  // Iterate over all text nodes and find matches.
  const ranges = allTextNodes
    .map((el) => {
      return { el, text: el.textContent.toLowerCase() };
    })
    .map(({ text, el }) => {
      const indices = [];
      let startPos = 0;
      while (startPos < text.length) {
        const index = text.indexOf(str, startPos);
        if (index === -1) break;
        indices.push(index);
        startPos = index + str.length;
      }

      // Create a range object for each instance of
      // str we found in the text node.
      return indices.map((index) => {
        const range = new Range();
        range.setStart(el, index);
        range.setEnd(el, index + str.length);
        return range;
      });
    });

  // Create a Highlight object for the ranges.
  const searchResultsHighlight = new Highlight(...ranges.flat());

  // Register the Highlight object in the registry.
  CSS.highlights.set("search-results", searchResultsHighlight);
});
```

#### CSS

最后，在 CSS 中使用 `::highlight()` 伪元素来设置高亮样式。

```css
::highlight(search-results) {
  background-color: #f06;
  color: white;
}
```

#### 结果

结果如下所示。在输入框中输入文本就可以显示高亮匹配了：

规范
--

| Specification |
| --- |
| CSS Custom Highlight API Module Level 1  |

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

### api.Highlight

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

### api.HighlightRegistry

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

### css.selectors.highlight

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

参见
--

* CSS 自定义高亮 API：Web 高亮文本范围的未来


Notifications API - Web API 接口参考

Notifications API
=================

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

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

**Notifications API** 允许网页控制向最终用户显示系统通知——这些都在顶级浏览上下文视口之外，因此即使用户已经切换标签页或移动到不同的应用程序，也可以显示。该 API 被设计成与不同平台上的现有通知系统兼容。

概念和用法
-----

在支持该接口的平台上，显示一个系统通知通常涉及两件事。首先，用户需要为当前来源授予权限以显示系统通知，这通常在应用或站点初始化时，使用 `Notification.requestPermission()` 方法来完成。这应该通过响应用户交互来完成，例如单击按钮，例如：

```js
btn.addEventListener("click", () => {
  let promise = Notification.requestPermission();
  // 等待授权
});
```

这不仅是最佳实践——你不应该向用户发送他们不同意的通知——并且未来的浏览器将明确禁止未响应用户交互而触发的通知。例如，Firefox 从 72 版本开始就已经这样做了。

这将产生一个请求对话框，内容如下：

![一个对话框，要求用户允许来自该源的通知。有一些选项可以禁止或允许通知](/zh-CN/docs/Web/API/Notifications_API/screen_shot_2019-12-11_at_9.59.14_am.png)

从这里，用户可以选择允许来自此来源的通知或阻止来自此来源的通知。一旦做出选择，该设置通常将持续用于当前会话。

**备注：** 从 Firefox 44 开始，通知（Notification）和推送（Push）的权限已合并。如果为通知授予权限，推送也将启用。

接下来，使用 `Notification()` 构造函数创建一个新通知。这个函数必须传递一个标题参数，并且可以选择传递一个选项对象来指定选项，例如文本方向、正文、要显示的图标、要播放的通知声音等等。

此外，Notifications API 规范对 ServiceWorker API (en-US) 指定了多个添加，以允许 Service Worker 发送通知。

**备注：** 想了解怎么在你的应用里使用通知接口，请阅读使用 Notifications API。

Notifications 接口
----------------

`Notification`

定义的通知对象。

### Service worker 附加内容

`ServiceWorkerRegistration` (en-US)

该对象包含 `ServiceWorkerRegistration.showNotification()` (en-US) 和 `ServiceWorkerRegistration.getNotifications()` (en-US) 方法，用于控制通知的显示。

`ServiceWorkerGlobalScope`

该对象包含 `onnotificationclick` (en-US) 事件处理器，用于通知被点击的时候触发自定义函数。

`NotificationEvent`

该对象是功能明确的事件对象，表示一个被触发的通知事件，继承自 `ExtendableEvent`。

规范
--

| Specification |
| --- |
| Notifications API Standard  |

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

### api.Notification

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

### api.ServiceWorkerRegistration.showNotification

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

### api.ServiceWorkerRegistration.getNotifications

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

参见
--

* 使用 Notifications API


Web Crypto API - Web API 接口参考

Web Crypto API
==============

**Web Crypto API** 为脚本提供了一套关于密码学原语的接口，以便用于构建需要使用加密的系统。

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

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

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

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

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

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

接口
--

有些浏览器实现了叫作 `Crypto` 的接口，但是它缺乏良好的定义，或在密码学上是不健全的。为了避免混乱，这个接口的方法和属性已经被实现 Web Crypto API 的浏览器所移除，并且所有的 Web Crypto API 方法都可以在新的接口中使用：`SubtleCrypto`。`Crypto.subtle` 属性可以获取到一个实现了新接口的对象。

规范
--

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

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

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


Navigator - Web API 接口参考

Navigator
=========

`Navigator` 接口表示用户代理的状态和标识。它允许脚本查询它和注册自己进行一些活动。

可以使用只读的 `window.navigator` 属性检索 navigator 对象。

属性
--

不从 *`NavigatorID` (en-US)、`NavigatorLanguage` (en-US)、`NavigatorOnLine` (en-US)、`NavigatorGeolocation` (en-US)、`NavigatorPlugins` (en-US)、`NavigatorUserMedia`* 和 *`NetworkInformation`* 中继承任何属性，但是实现了定义在这些对象中的如下属性。

### 标准属性

`Navigator.activeVRDisplays` 只读
实验性

筛选所有的 `VRDisplay` 对象，把其中所有 `VRDisplay.ispresenting` (en-US) 属性的值为 `true` 的对象以数组的形式返回。

`NavigatorID.appCodeName` (en-US) 只读
已弃用

返回当前浏览器的内部“开发代号”名称。不能保证此属性返回的值是正确的。

`NavigatorID.appName` (en-US) 只读
已弃用

以 `DOMString` 的形式返回浏览器官方名称。不能保证此属性返回的值是正确的。

`NavigatorID.appVersion` (en-US) 只读
已弃用

以 `DOMString` 的形式返回浏览器版本。不能保证此属性返回的值是正确的。

`Navigator.battery` 只读
已弃用

返回一个 `BatteryManager` 对象，你可以用它来获取一些电池充电状态的信息。

`Navigator.connection` 只读
实验性

提供一个 `NetworkInformation` 对象来获取设备的网络连接信息。

`Navigator.cookieEnabled` 只读

当忽略 Cookie 时返回 false，否则返回 true

`Navigator.geolocation` 只读

返回一个 `Geolocation` 对象，据之可访问设备的地理位位置信息。

`NavigatorConcurrentHardware.hardwareConcurrency` (en-US) 只读

返回可用的逻辑处理器核心数。

`NavigatorPlugins.javaEnabled` (en-US) 只读
实验性

返回 `Boolean` (en-US) 表明浏览器是否支持 Java。

`Navigator.keyboard` 只读
实验性

返回一个 `Keyboard` (en-US) 对象，该对象提供对以下功能的访问：检索键盘布局图和切换从物理键盘捕获按键的功能。

`NavigatorLanguage.language` (en-US) 只读

返回 `DOMString` 表示用户的首先语言，通常是浏览器用户界面的语言。当未知的时，返回 null。

`NavigatorLanguage.languages` (en-US) 只读

返回一个表示用户已知语言的 `DOMString` 数组，并按优先顺序排列。

`NavigatorPlugins.mimeTypes` (en-US) 只读
实验性

返回 `MimeTypeArray` (en-US) 数组用于列举浏览器所支持的 MIME 类型。

`Navigator.locks` 只读
实验性

Returns a `LockManager` object which provides methods for requesting a new `Lock` object and querying for an existing `Lock` object

`Navigator.mediaCapabilities` (en-US) 只读
实验性

Returns a `MediaCapabilities` (en-US) object that can expose information about the decoding and encoding capabilities for a given format and output capabilities.

`Navigator.maxTouchPoints` 只读

Returns the maximum number of simultaneous touch contact points are supported by the current device.

`NavigatorOnLine.onLine` (en-US) 只读

返回 `Boolean` (en-US) 来表明浏览器是否联网。

`Navigator.oscpu`

返回当前操作系统名。

`Navigator.permissions` 只读
实验性

返回一个 `Permissions` 对象，该对象可用于查询和更新 Permissions API (en-US) 涵盖的 API 的权限状态。

`NavigatorID.platform` (en-US) 只读
实验性

返回浏览器平台名，不确定此值是否有效。

`NavigatorPlugins.plugins` (en-US) 只读
实验性

返回 `PluginArray` (en-US) 数组用于列举出浏览器安装的插件。

`NavigatorID.product` (en-US) 只读
实验性

在任意浏览器下都只返回 `'Gecko'`，此属性只用于兼容的目的。

`Navigator.serviceWorker` 只读

返回 `ServiceWorkerContainer` 对象用于提供注册、删除、更新以及为了 associated document 的 `ServiceWorker` 对象之间的通信。

`NavigatorStorage.storage` (en-US) 只读

Returns the singleton `StorageManager` object used for managing persistence permissions and estimating available storage on a site-by-site/app-by-app basis.

`NavigatorID.userAgent` (en-US) 只读

返回当前浏览器的用户代理。

`Navigator.webdriver` (en-US) 只读
实验性

TBD

### 非标准方法

`navigator.buildID`
非标准

返回浏览器识别码。这一方法返回时间戳，例如：在 Firefox 64 发行版中返回 `20181001000000`。

`Navigator.cookieEnabled`
非标准

返回布尔值以表明 Cookies 是否能再浏览器中启用

`navigator.doNotTrack`
非标准

报告用户的不追踪参数值，当值为 yes，你的网址或应用将不追踪用户

`navigator.id`
非标准

返回 `id` 对象，你能用 BrowserID 添加支持到你的网址。

`navigator.mozApps`
非标准

Returns an `Apps` object you can use to install, manage, and control Open Web apps.

`navigator.mozAudioChannelManager`
非标准

The `navigator.mozAudioChannelManager` object provides access to the `mozAudioChannelManager` interface, which is used to manage your Firefox OS device's audio channels, including setting what channel's volume to affect when the volume buttons are pressed inside a particular app.

`navigator.mozNotification`
已弃用

非标准

`navigator.webkitNotification`

Returns a `notification` object you can use to deliver notifications to the user from your web application.

`navigator.mozSocial`
非标准

The Object, returned by the `navigator.mozSocial` property, is available within the social media provider's panel to provide functionality it may need.

`navigator.productSub`
非标准

Returns the build number of the current browser (e.g., "20060909").

`navigator.securitypolicy`
非标准

Returns an empty string. In Netscape 4.7x, returns "US & CA domestic policy" or "Export policy".

`navigator.standalone`
非标准

Returns a boolean indicating whether the browser is running in standalone mode. Available on Apple's iOS Safari only.

`navigator.vendor`
非标准

返回当前浏览器的供应商的名字（例如：“Netscape6”）。

`navigator.vendorSub`
非标准

返回供应商版本号码（例如：“6.1”）。

`navigator.webkitPointer`
非标准

Returns a PointerLock object for the Mouse Lock API.

方法
--

*Doesn't inherit any method, but implements those defined in `NavigatorID` (en-US), `NavigatorContentUtils`, *`NavigatorUserMedia`,* and `NavigatorStorageUtils`.*

### 标准方法

`Navigator.getVRDisplays()` (en-US)
已弃用

Returns a promise that resolves to an array of `VRDisplay` objects representing any available VR devices connected to the computer.

`NavigatorUserMedia.getUserMedia()`
已弃用

After having prompted the user for permission, returns the audio or video stream associated to a camera or microphone on the local computer.

`navigator.registerContentHandler`

Allows web sites to register themselves as a possible handler for a given MIME type.

`navigator.registerProtocolHandler`

Allows web sites to register themselves as a possible handler for a given protocol.

`Navigator.requestMediaKeySystemAccess()` (en-US)
实验性

Returns a `Promise` for a MediaKeySystemAccess object.

`Navigator.sendBeacon()`
实验性

Used to asynchronously transfer a small amount of data using HTTP from the User Agent to a web server.

`Navigator.share()`
实验性

Invokes the native sharing mechanism of the current platform.

`NavigatorID.taintEnabled()` (en-US)
已弃用

实验性

Returns `false`. JavaScript taint/untaint functions removed in JavaScript 1.2.

`Navigator.vibrate()`

Causes vibration on devices with support for it. Does nothing if vibration support isn't available.

规范
--

| Specification |
| --- |
| HTML Standard # the-navigator-object |

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

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


媒体追踪约束 - Web API 接口参考

媒体追踪约束
======

The **`MediaTrackConstraints`** dictionary is used to describe a set of capabilities and the value or values each can take on. A constraints dictionary is passed into `applyConstraints()` (en-US) to allow a script to establish a set of exact (required) values or ranges and/or preferred values or ranges of values for the track, and the most recently-requested set of custom constraints can be retrieved by calling `getConstraints()`.

For each constraint, you can typically specify an exact value you need, an ideal value you want, a range of acceptable values, and/or a value which you'd like to be as close to as possible. The specifics vary somewhat depending on the type of the constrainable property.

To learn more about how constraints work, see Capabilities, constraints, and settings (en-US).

Properties
----------

Some combination—but not necessarily all—of the following properties will exist on the object.

### Properties of all media tracks

`deviceId` (en-US)

A `ConstrainDOMString` (en-US) object specifying a device ID or an array of device IDs which are acceptable and/or required.

`groupId` (en-US)

A `ConstrainDOMString` (en-US) object specifying a group ID or an array of group IDs which are acceptable and/or required.

### Properties of audio tracks

`autoGainControl` (en-US)

一个 `ConstrainBoolean` (en-US) 对象，用来指明是否首选或要求使用声音的自动增益。

`channelCount` (en-US)

一个 `ConstrainLong` (en-US)，用来指明可选或要求的声道数或者是声道数的范围。

`echoCancellation` (en-US)

一个 `ConstrainBoolean` (en-US) 对象，用来指明是否首选或需要开启回声消除。

`latency` (en-US)

一个 `ConstrainDouble` (en-US)，用来指明多大延迟是被可接受的。

`noiseSuppression` (en-US)

一个 `ConstrainBoolean` (en-US)，用来指明是否首选或需要开启降噪。

`sampleRate` (en-US)

一个 `ConstrainLong` (en-US)，用来指明可接受的或要求的音频采样率/采样率范围。

`sampleSize` (en-US)

一个 `ConstrainLong` (en-US)，用来指明可接受的或要求的音频采样大小/采样范围。

`volume` (en-US)

一个 `ConstrainDouble` (en-US)，用来指明可接受的或要求的音量大小/范围。

### Properties of image tracks

`whiteBalanceMode`

A `String` specifying one of `"none"`, `"manual"`, `"sigle-shot"`, or `"continuous"`.

`exposureMode`

A `String` specifying one of `"none"`, `"manual"`, `"sigle-shot"`, or `"continuous"`.

`focusMode`

A `String` specifying one of `"none"`, `"manual"`, `"sigle-shot"`, or `"continuous"`.

`pointsOfInterest`

The pixel coordinates on the sensor of one or more points of interest. This is either an object in the form { x:*value*, y:*value* } or an array of such objects, where *value* is a double-precision integer.

`exposureCompensation`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying f-stop adjustment by up to ±3.

`colorTemperature`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying a desired color temperature in degrees kelvin.

`iso`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying a desired iso setting.

`brightness`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying a desired brightness setting.

`contrast`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying the degree of difference between light and dark.

`saturation`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying the degree of color intensity.

`sharpness`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying the intensity of edges.

`focusDistance`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying distance to a focused object.

`zoom`

A `ConstrainDouble` (en-US) (a double-precision integer) specifying the desired focal length.

`torch`

A `Boolean` whter the fill light continuously connected, meaning it stays on as long as the track is active.

### Properties of video tracks

`aspectRatio` (en-US)

A `ConstrainDouble` (en-US) specifying the video aspect ratio or range of aspect ratios which are acceptable and/or required.

`facingMode` (en-US)

A `ConstrainDOMString` (en-US) object specifying a facing or an array of facings which are acceptable and/or required.

`frameRate` (en-US)

A `ConstrainDouble` (en-US) specifying the frame rate or range of frame rates which are acceptable and/or required.

`height` (en-US)

A `ConstrainLong` (en-US) specifying the video height or range of heights which are acceptable and/or required.

`width` (en-US)

A `ConstrainLong` (en-US) specifying the video width or range of widths which are acceptable and/or required.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraints |

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

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

See also
--------

* `MediaDevices.getUserMedia()`
* `MediaStreamTrack.getConstraints()`
* `MediaStreamTrack.applyConstraints()` (en-US)
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints` (en-US)
* `MediaStreamTrack.getSettings()` (en-US)


Worker - Web API 接口参考

Worker
======

Worker 接口是 Web Workers API 的一部分，指的是一种可由脚本创建的后台任务，任务执行中可以向其创建者收发信息。要创建一个 Worker，只须调用 `Worker(URL)` 构造函数，函数参数 `URL` 为指定的脚本。

Worker 也可以创建新的 Worker，当然，所有 Worker 必须与其创建者同源（注意：Blink暂时不支持嵌套 Worker）。

需要注意的是，不是所有函数和构造函数 (或者说…类) 都可以在 Worker 中使用。具体参考页面 Worker 所支持的函数和类。Worker 可以使用 `XMLHttpRequest` 发送请求，但是请求的 `responseXML` 与 `channel` 两个属性值始终返回 `null` （`fetch` 仍可正常使用，没有类似的限制）。

**备注：** 如果你要在火狐浏览器的扩展使用 Worker 访问 js-ctypes，应使用 `ChromeWorker` 对象来替代。(译者注：这里没有看懂，希望有人能驳正，或添加说明)

构造函数
----

`Worker()`

创建一个专用 Web worker，它只执行 URL 指定的脚本。使用 Blob URL 作为参数亦可。

属性
--

*继承*父对象\*`EventTarget` 的属性，以及实现对象 `AbstractWorker` (en-US)的属性。\*

### *事件句柄*

`AbstractWorker.onerror` (en-US)

当`ErrorEvent` 类型的事件冒泡到 worker 时，事件监听函数 `EventListener` 被调用。它继承于 `AbstractWorker` (en-US).

`Worker.onmessage`

当`MessageEvent`类型的事件冒泡到 worker 时，事件监听函数 `EventListener` 被调用。例如，一个消息通过 `DedicatedWorkerGlobalScope.postMessage` (en-US)，从执行者发送到父页面对象，消息保存在事件对象的 `data` (en-US) 属性中。

`Worker.onmessageerror`

当`messageerror` (en-US) 类型的事件发生时，对应的事件处理器代码被调用。

方法
--

*继承*父对象\*`EventTarget` 的方法，以及实现对象 `AbstractWorker` (en-US)的方法。\*

`Worker.postMessage()`

发送一条消息到最近的外层对象，消息可由任何 JavaScript 对象组成。

`Worker.terminate()`

立即终止 worker。该方法不会给 worker 留下任何完成操作的机会；就是简单的立即停止。Service Woker 不支持这个方法。

示例
--

下面的代码通过构造函数 `Worker()` 创建了一个 `Worker` 对象。

```js
var myWorker = new Worker("worker.js");
var first = document.querySelector("#number1");
var second = document.querySelector("#number2");

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

完整的示例，请查阅 Basic dedicated worker example (run dedicated worker).

规范
--

| Specification |
| --- |
| HTML Standard # dedicated-workers-and-the-worker-interface |

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

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

不同类型的 worker 兼容度不一致，详细参考具体定义的页面。

### 跨域行为的错误事件

浏览器的早期版本中，加载跨域的执行者脚本导致 `SecurityError`事件。根据规范的变更，而新版本的浏览器只有`error`事件发生

参见
--

* 使用 Web Worker
* Web Worker 可用的函数和类
* 其他类型的 worker：`SharedWorker` 和 ServiceWorker.
* `OffscreenCanvas` 接口


SourceBufferList - Web API 接口参考

SourceBufferList
================

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

**`SourceBufferList`** 接口表示多个 `SourceBuffer` 对象的简单容器列表。

使用 `MediaSource.sourceBuffers` 属性可以检索附加到特定 `MediaSource` 的 `SourceBuffer` 的源缓冲列表。

使用数组操作符 `[]` 可以访问到各个源缓冲区。

EventTarget

SourceBufferList属性
--

`SourceBufferList.length` 只读

返回列表中 `SourceBuffer` 对象的数量。

方法
--

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

事件
--

`addsourcebuffer`

当一个 `SourceBuffer` 增加到列表时触发。

`removesourcebuffer`

当一个 `SourceBuffer` 从列表移除时触发。

示例
--

这个示例展示了如何访问连接到一个已经在播放的 `HTMLVideoElement` 其内部的 `MediaSource` 的活动源缓冲区。

```js
// Video is an already playing video using a MediaSource srcObject
const video = document.querySelector("video");
const mediaSource = video.srcObject;
const sourceBufferList = mediaSource.activeSourceBuffers;
for (const sourceBuffer of sourceBufferList) {
  // Do something with each SourceBuffer, such as call abort()
  sourceBuffer.abort();
}
```

规范
--

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

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

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

参见
--

* `MediaSource`
* `SourceBuffer`


WritableStreamDefaultController - Web API 接口参考

WritableStreamDefaultController
===============================

Stream API 中的 **`WritableStreamDefaultController`** 接口表示一个允许控制 `WritableStream` 状态的控制器。当构造 `WritableStream` 时，会为底层的接收器提供一个相应的 `WritableStreamDefaultController` 实例以进行操作。

构造函数
----

无。`WritableStreamDefaultController` 实例会在构造 `WritableStream` 时被自动创建。

实例属性
----

`WritableStreamDefaultController.signal` (en-US) 只读

返回与 controller 相关联的 `AbortSignal`。

实例方法
----

`WritableStreamDefaultController.error()`

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

示例
--

```js
const writableStream = new WritableStream({
  start(controller) {
    // do stuff with controller
    // error stream if necessary
    controller.error('My stream is broken');
  },
  write(chunk, controller) {
    ...
  },
  close(controller) {
    ...
  },
  abort(err) {
    ...
  }
});
```

规范
--

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

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

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


RTCStatsReport - Web API 接口参考

RTCStatsReport
==============

**`RTCStatsReport`** 接口提供了通过调用 `RTCPeerConnection.getStats()` (en-US)、`RTCRtpReceiver.getStats()` (en-US) 和 `RTCRtpSender.getStats()` (en-US) 这三个方法之一所获得的统计报告。

该统计报告包含统计类别字符串名称到包含相应统计数据的对象的映射。

在 `RTCPeerConnection` 上调用 `getStats()` 可以让你指定是否希望获取连接上的出站、入站或是所有流的统计信息。`getStats()` 的 `RTCRtpReceiver` (en-US) 和 `RTCRtpSender` (en-US) 版本仅返回你调用它们的传入或传出流的统计信息。

统计对象
----

对于每种统计信息类别，都有一个字典，字典的属性提供相关信息。

### 所有统计类别共有的属性

所有 WebRTC 统计对象都基于 `RTCStats` 字典，该字典提供了最基本的信息：时间戳、统计类型字符串和唯一标识数据源的 ID。

### 统计类别

`type` 值给出了对象所代表的统计类别的名称。以及如何查找你需要的特定数据的类型。

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # rtcstatsreport-object |

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

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

参见
--

* WebRTC API
* `RTCPeerConnection`
* `RTCPeerConnection.getStats()` (en-US)、`RTCRtpReceiver.getStats()` (en-US) 和 `RTCRtpSender.getStats()` (en-US)


OscillatorNode - Web API 接口参考

OscillatorNode
==============

**`OscillatorNode`** 接口表示一个振荡器，它产生一个周期的波形信号（如正弦波）。它是一个 `AudioScheduledSourceNode` 音频处理模块，这个模块会生成一个指定频率的波形信号（即一个固定的音调）

一个 `OscillatorNode` 对象是通过 `AudioContext.createOscillator()` (en-US) 方法创建的。它总是有一个输出，但没有输入。它的基础属性（定义见 `AudioNode` ）默认如下：

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

构造函数
----

`OscillatorNode()`

创建一个 OscillatorNode 对象的示例，为 node属性提供可选的一个定义默认值的对象。如果默认值可接受，你可以简单地调用`AudioContext.createOscillator()` (en-US)工厂方法。

属性
--

*继承自父类* *`AudioScheduledSourceNode`，并添加下列属性：*

`OscillatorNode.frequency`

一个 a-rate `AudioParam` 对象的属性代表了振动的频率（单位为赫兹 hertz） (虽然返回的`AudioParam 是只读的，但是它所表示的值是可以修改的`)。默认值是 440 Hz (基本的中 A 音高).

`OscillatorNode.detune`

一个 a-rate `AudioParam` 对象的属性代表振动的音高微调（单位是 cent 音分） (虽然返回的`AudioParam 是只读的，但是它所表示的值是可以修改的`).。默认值是 0。

`OscillatorNode.type` (en-US)

一个字符串，决定 `OscillatorNode 播放的声音的周期波形`; 它的值可以是基础值中的一个或者用户使用 `PeriodicWave`。不同的波形可以产生不同的声调。基础值有 `"sine"`、`"square"`、`"sawtooth"`、`"triangle"` 和 `"custom"`。默认值是 `"sine"`。

方法
--

*继承自父级，* *`AudioScheduledSourceNode`*, 自有方法如下：

`OscillatorNode.setPeriodicWave()`

设置一个 `PeriodicWave` ,它描述了一个周期的波形常常替代标准波形之一; 调用这个方法来设置用户自定义的波形。它取代了已经废弃了的 `OscillatorNode.setWaveTable()` 方法。

示例
--

下面示例展示了 `AudioContext` 的基本使用 来创建一个 oscillator 节点 并使用它来播放音乐。这是已经在运行的例子，可以看这里 Violent Theremin demo (see app.js 是相关代码).

```js
// create web audio api context
var audioCtx = new (window.AudioContext || window.webkitAudioContext)();

// create Oscillator node
var oscillator = audioCtx.createOscillator();

oscillator.type = "square";
oscillator.frequency.value = 440; // value in hertz
oscillator.connect(audioCtx.destination);
oscillator.start();
```

规范
--

| Specification |
| --- |
| Web Audio API # OscillatorNode |

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

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

See also
--------

* Using the Web Audio API (en-US)


FontFace - Web API 接口参考

FontFace
========

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

**`FontFace`** 接口表示一个可用的字体。它允许你控制字体的源文件，作为外部资源的 URL 或缓冲区; 它还允许你控制字体的加载时间和字体当前的状态。

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

`FontFace()` (en-US)

使用 URL 指向的外部资源或`ArrayBuffer`构造并返回一个新的 `FontFace` 对象。

Properties
----------

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

`FontFace.family` (en-US)

这是不是一个`DOMString` ？是的话将表示该字体的 *family* 属性，相当于 `family` 。

`FontFace.style` (en-US)

这是不是一个 `DOMString` ？是的话将表示该字体的 *style* 属性，相当于 `style` 。

`FontFace.weight` (en-US)

这是不是一个 `DOMString` ？是的话将表示该字体的 *weight* 属性，相当于 `weight`。

`FontFace.stretch` (en-US)

这是不是一个 `DOMString` ？是的话将表示该字体的 *stretches* 属性，相当于 `stretch` 。

`FontFace.unicodeRange` (en-US)

这是不是一个 `DOMString` ？是的话将表示该字体涵盖的 *range of code*（字符编码的范围），相当于 `unicode-range` (en-US) 。

`FontFace.variant` (en-US)

这是不是一个 `DOMString` ？是的话将表示该字体的 *variant* 属性，相当于 `range` 。

`FontFace.featureSettings` (en-US)

这是不是一个 `DOMString` ？是的话将表示该字体的 *features* 属性，相当于 `feature-settings` 。

`FontFace.status` (en-US) 只读

返回一个表示字体当前状态的可枚举值，它可能是下列之一：`"unloaded"`、`"loading"`、`"loaded"`、`"error"`。

`FontFace.loaded` (en-US) 只读

当字体完全加载或加载失败时返回该 `FontFace` 的 `Promise` (en-US)。

方法
--

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

`FontFace.load()` (en-US)

加载该字体，返回该字体完全加载或加载失败时的 `Promise` (en-US)。

规范
--

| Specification |
| --- |
| CSS Font Loading Module Level 3 # fontface-interface |

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

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


CSS 对象模型 - Web API 接口参考

CSS 对象模型
========

**CSS 对象模型**是一组允许用 JavaScript 操纵 CSS 的 API。它很像 DOM，但针对的是 CSS 而不是 HTML。它允许用户动态地读取和修改 CSS 样式。

CSS 的值是没有类型的，也就是使用 `String` 对象来表示。

参考
--

* `AnimationEvent` (en-US)
* `CaretPosition`
* `CSS`
* `CSSCharsetRule`
* `CSSConditionRule`
* `CSSCounterStyleRule` (en-US)
* `CSSFontFaceRule` (en-US)
* `CSSFontFeatureValuesMap`
* `CSSFontFeatureValuesRule` (en-US)
* `CSSGroupingRule`
* `CSSImportRule` (en-US)
* `CSSKeyframeRule` (en-US)
* `CSSKeyframesRule` (en-US)
* `CSSMarginRule`
* `CSSMediaRule`
* `CSSNamespaceRule` (en-US)
* `CSSPageRule`
* `CSSRule`
* `CSSRuleList`
* `CSSStyleDeclaration`
* `CSSStyleSheet`
* `CSSStyleRule`
* `CSSSupportsRule`
* `CSSVariablesMap`
* `CSSViewportRule`
* `FontFace`
* `FontFaceSet`
* `FontFaceSetLoadEvent` (en-US)
* `GetStyleUtils`
* `MediaList`
* `MediaQueryList`
* `MediaQueryListEvent`
* `Screen`
* `StyleSheet`
* `StyleSheetList`
* `TransitionEvent`

CSSOM 相关规范也扩展了其他几个接口：`Document`、`Window`、`Element`、`HTMLElement`、`HTMLImageElement`、`Range`、`MouseEvent` 和 `SVGElement`。

### CSS 类型化对象模型
实验性

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

* `CSSImageValue` (en-US)
实验性
* `CSSKeywordValue` (en-US)
实验性
* `CSSMathInvert` (en-US)
实验性
* `CSSMathMax` (en-US)
实验性
* `CSSMathMin` (en-US)
实验性
* `CSSMathNegate` (en-US)
实验性
* `CSSMathProduct` (en-US)
实验性
* `CSSMathSum`
实验性
* `CSSMathValue` (en-US)
实验性
* `CSSMatrixComponent` (en-US)
实验性
* `CSSNumericArray` (en-US)
实验性
* `CSSNumericValue` (en-US)
实验性
* `CSSPerspective` (en-US)
实验性
* `CSSPositionValue` (en-US)
实验性
* `CSSRotate` (en-US)
实验性
* `CSSScale` (en-US)
实验性
* `CSSSkew` (en-US)
实验性
* `CSSSkewX` (en-US)
实验性
* `CSSSkewY` (en-US)
实验性
* `CSSStyleValue` (en-US)
实验性
* `CSSTransformComponent` (en-US)
实验性
* `CSSTransformValue` (en-US)
实验性
* `CSSTranslate` (en-US)
实验性
* `CSSUnitValue` (en-US)
实验性
* `CSSUnparsedValue` (en-US)
实验性
* `CSSVariableReferenceValue` (en-US)
实验性
* `StylePropertyMap`
实验性
* `StylePropertyMapReadOnly` (en-US)
实验性
### 废弃的 CSSOM 接口
已弃用

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

* `CSSPrimitiveValue` (en-US)
已弃用
* `CSSValue`
已弃用
* `CSSValueList`
已弃用
教程
--

* 决定元素的维度（这篇文档可能有点过时，因为它是在 DHTML/Ajax 时代写的）。
* 管理屏幕方向 (en-US)
规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM)  |
| CSSOM View Module  |
| CSS Typed OM Level 1  |

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

所有这些功能都是多年来一点一点地添加到不同的浏览器中的：这是一个相当复杂的过程，不能用一个简单的表格来概括。请参考具体的接口，了解其可用性。

参见
--

* 文档对象模型（DOM）
* Houdini API