PointerEvent - Web API 接口参考

PointerEvent
============

**PointerEvent** 接口代表了由 *指针* 引发的 DOM 事件的状态，包括接触点的位置，引发事件的设备类型，接触表面受到的压力等。

*指针* 是输入设备的硬件层抽象（比如鼠标，触摸笔，或触摸屏上的一个触摸点）*。指针 能指向一个具体表面（如屏幕）上的一个（或一组）坐标。*

指针的 *击中检测* 指浏览器用来检测 指针事件的目标元素的过程。大多数情况下，这个目标元素是由 指针的位置和元素在文章中的位置和分层共同决定的。

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

`PointerEvent()` (en-US)

创建一个合成的且不可信的 PointerEvent。

Properties
----------

*该接口属性继承自 `MouseEvent` 和 `Event`.*

`PointerEvent.pointerId` (en-US) 只读

触发事件的 pointer 的唯一标识符。

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

Pointer 的接触面的 CSS 像素宽度（X 轴上的大小）。

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

Pointer 的接触面的 CSS 像素高度（Y 轴上的大小）。

`PointerEvent.pressure` (en-US) 只读

归一化后的 pointer 压力值，范围在 [0,1] 区间。其中 0 和 1 分别代表硬件能够检测的最小和最大压力。

`PointerEvent.tangentialPressure` (en-US) 只读

归一化后的切向压力值（也称为桶压或cylinder stress），范围在 [-1, 1] 区间，0 表示控制设备中立状态时的值。

`PointerEvent.tiltX` (en-US) 只读

由输入设备（如手写笔）与 Y 轴构成的平面，和 Y-Z 平面之间的夹角（取值在 [-90, 90] 区间）。

`PointerEvent.tiltY` (en-US) 只读

由输入设备（如手写笔）与 X 轴构成的平面，和 X-Z 平面之间的夹角（取值在 [-90, 90] 区间）。

`PointerEvent.twist` (en-US) 只读

输入设备（如手写笔）围绕自身主轴顺时针旋转的角度，取值范围是 [0, 359] 度。

`PointerEvent.pointerType` (en-US) 只读

表示触发事件的设备类型（鼠标，触控笔，触摸板等）。

`PointerEvent.isPrimary` (en-US) 只读

标识一个 pointer 是否是当前设备类型的主 pointer。

Pointer event types
-------------------

The `PointerEvent` interface has several event types. To determine which event fired, look at the event's `type` property.

**备注：** It's important to note that in many cases, both pointer and mouse events get sent (in order to let non-pointer-specific code still interact with the user). If you use pointer events, you should call `event.preventDefault()` to keep the mouse event from being sent as well.

`pointerover`

This event is fired when a pointing device is moved into an element's hit test boundaries.

`pointerenter`

This event is fired when a pointing device is moved into the hit test boundaries of an element or one of its descendants, including as a result of a `pointerdown` event from a device that does not support hover (see `pointerdown`). This event type is similar to `pointerover`, but differs in that it does not bubble.

`pointerdown`

The event is fired when a pointer becomes *active*. For mouse, it is fired when the device transitions from no buttons depressed to at least one button depressed. For touch, it is fired when physical contact is made with the digitizer. For pen, it is fired when the stylus makes physical contact with the digitizer.

`pointermove`

This event is fired when a pointer changes coordinates.

`pointerrawupdate`
实验性

This event is fired when any of a pointer's properties change.

`pointerup`

This event is fired when a pointer is no longer *active*.

`pointercancel`

A browser fires this event if it concludes the pointer will no longer be able to generate events (for example the related device is deactivated).

`pointerout`

This event is fired for several reasons including: pointing device is moved out of the hit test boundaries of an element; firing the `pointerup` event for a device that does not support hover (see `pointerup`); after firing the `pointercancel` event (see `pointercancel`); when a pen stylus leaves the hover range detectable by the digitizer.

`pointerleave`

This event is fired when a pointing device is moved out of the hit test boundaries of an element. For pen devices, this event is fired when the stylus leaves the hover range detectable by the digitizer.

`gotpointercapture`

This event is fired when an element receives pointer capture.

`lostpointercapture`

This event is fired after pointer capture is released for a pointer.

示例
--

An Example of each property, event type and global event handler is included in their respective reference page.

规范
--

| Specification |
| --- |
| Pointer Events # pointerevent-interface |

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

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

参见
--

* `Touch Events`
* `GestureEvent`
* `MSGestureEvent`
* `touch-action`


ContentVisibilityAutoStateChangeEvent - Web API 接口参考

ContentVisibilityAutoStateChangeEvent
=====================================

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

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

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

**`ContentVisibilityAutoStateChangeEvent`** 接口是 `contentvisibilityautostatechange` 事件的对象。对于设置了 `content-visibility: auto` 的任意元素，在元素开始或不再与用户相关，且正在跳过其内容时触发此事件。

在元素不再与用户相关时（在开始和结束事件之间），用户代理会跳过元素的渲染（包括布局和绘制），这可以显著提高页面渲染速度。`contentvisibilityautostatechange` 事件为应用代码在不需要时开始或停止渲染过程（如在 `<canvas>` 上绘画）提供了便利，进而节约了处理能力。

注意因为元素内容即使被隐藏不可见也仍将保持语义相关性（例如使用辅助技术的用户），所以不应使用此事件跳过重要的 DOM 语义更新。

Event

ContentVisibilityAutoStateChangeEvent构造函数
----

`ContentVisibilityAutoStateChangeEvent()`

创建新的 `ContentVisibilityAutoStateChangeEvent` 对象实例。

实例属性
----

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

`skipped` 只读

如果用户代理正在跳过元素的渲染则返回 `true`，否则返回 `false`。

示例
--

```js
const canvasElem = document.querySelector("canvas");

canvasElem.addEventListener("contentvisibilityautostatechange", stateChanged);
canvasElem.style.contentVisibility = "auto";

function stateChanged(event) {
  if (event.skipped) {
    stopCanvasUpdates(canvasElem);
  } else {
    startCanvasUpdates(canvasElem);
  }
}

// 在画布需要开始更新时调用此方法。
function startCanvasUpdates(canvas) {
  // …
}

// 在画布需要停止更新时调用此方法。
function stopCanvasUpdates(canvas) {
  // …
}
```

规范
--

| Specification |
| --- |
| CSS Containment Module Level 2 # content-visibility-auto-state-change |

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

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

参见
--

* `contentvisibilityautostatechange` 事件
* CSS 局限
* `content-visibility` 属性
* `contain` 属性


HTMLParagraphElement - Web API 接口参考

HTMLParagraphElement
====================

**`HTMLParagraphElement`** 接口可以提供超过其继承的`HTMLElement` 对象额外的属性，用以操作 `<p>` 元素。

属性
--

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

`HTMLParagraphElement.align`
已弃用

A `DOMString` representing an enumerated property indicating alignment of the element's contents with respect to the surrounding context. The possible values are `"left"`, `"right"`, `"justify"`, and `"center"`.

Methods
-------

*No specific methods, inherits methods from its parent, `HTMLElement`.*

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

| Specification |
| --- |
| HTML Standard # htmlparagraphelement |

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

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

See also
--------

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


CSSRuleList - Web API 接口参考

CSSRuleList
===========

CSS 规则列表 `CSSRuleList` 是一个（只允许间接更改的）类数组对象，包含着一个 `CSSRule` 对象的有序集合。

描述
--

CSS 规则列表内的每一条 `CSSRule` 都可以通过 `rules.item(index)`，或者更简单的 `rules[index]` 的形式访问。这里的 `rules` 是一个实现了 `CSSRuleList` 接口的对象（例如 `CSSStylesheet.cssRules`），而 `index` 是一个从 0 开始的、规则的位置索引，通过它获取规则时，顺序与 CSS 样式表中的顺序是一致的。规则对象的个数是 `rules.length`。

注意，因为只能*间接更改*（可更改，但是其本身只拥有读取方法），无法直接往规则列表中添加或移除规则，只能通过它的父样式表进行更改。事实上，`.insertRule()` 和 `.deleteRule()` 甚至都不是 CSSRuleList 的方法，而是 `CSSStyleSheet` 的。如果，处于一些原因，出现了一个没有父样式表 或者说不属于任何样式表的规则列表（可能是另一个规则列表的\*拷贝\*），那么，既不能将它分配到某个样式表下（因为没有适用的属性），它也不能被分配给任何一个样式表（因为 `stylesheet.cssRules` 是只读属性），就只能通过遍历方法，将它一条规则一条规则地**插入**已有的样式表中。

示例
--

```js
// 得到文档中第一个 CSS 样式表中的第一条规则
var first_rule = document.styleSheets[0].cssRules[0];
```

参见
--

* `CSSRule`
### CSSRuleList 的实现

在 CSS 对象模型 CSSOM 中，有多个属性的返回值是一个 `CSSRuleList`。它们分别是：

* `CSSStyleSheet` 属性 `cssRules` (en-US)
* `CSSMediaRule` 属性 `cssRules`
* `CSSKeyframesRule` (en-US) 属性 `cssRules` (en-US)
* `CSSMozDocumentRule` 属性 `cssRules`
规范
--

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

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

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


FileSystem - Web API 接口参考

FileSystem
==========

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

在 File System API 中，一个 FileSystem 对象代表着一个文件系统。这个对象是调用 requestFileSystem() (en-US) 成功的一个标志。FileSystem 对象有两个属性。

关于本文档
-----

 本文档的上次更新是 2012 年 3 月 2 日，引用来源是 2011 年 4 月 9 日的草案 W3C Specifications (Working Draft)。
 该草案似乎已经被放弃了，任何实现不应该参考这份草案，也不该引用它。

基本概念
----

你可以通过调用 `window.requestFileSystem()` (en-US) 来请求对一个沙盒文件系统的访问权限。调用 `requestFileSystem()` 会创建一个新的沙盒存储空间。成功调用之后会返回一个 `FileSystem 对象`。它有两个属性：名称和文件系统的根目录。

`FileSystem 对象`是你访问文件系统所必须的，所以你最好为它创建一个引用，然后储存起来。

属性
--

| 属性 | 类型 | 解释 |
| --- | --- | --- |
| `name` | `只读的 DOMString` | 文件系统的名称。The name must be unique across the list of exposed file systems. |
| `root` | `只读的目录实体` | 文件系统的根目录。 |

规范
--

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

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

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

参见
--

* 文件与目录条目 API
* 文件与目录条目 API 介绍
* `FileSystemEntry` (en-US)、`FileSystemFileEntry` 和 `FileSystemDirectoryEntry`


CloseEvent - Web API 接口参考

CloseEvent
==========

`CloseEvent` 会在连接关闭时发送给使用 WebSockets 的客户端。它在 `WebSocket` 对象的 `onclose` 事件监听器中使用。

构造器
---

`CloseEvent()` (en-US)

创建一个 `CloseEvent`.

属性
--

*该接口也继承了其父类 `Event` 的属性。*

`CloseEvent.code` (en-US) 只读

返回一个 unsigned short 类型的数字，表示服务端发送的关闭码，以下为已分配的状态码。

| 状态码 | ?名称 | ?描述 |
| --- | --- | --- |
| `0`–`999` |  | **保留段，未使用。** |
| `1000` | `CLOSE_NORMAL` | 正常关闭; 无论为何目的而创建，该链接都已成功完成任务。 |
| `1001` | `CLOSE_GOING_AWAY` | 终端离开，可能因为服务端错误，也可能因为浏览器正从打开连接的页面跳转离开。 |
| `1002` | `CLOSE_PROTOCOL_ERROR` | 由于协议错误而中断连接。 |
| `1003` | `CLOSE_UNSUPPORTED` | 由于接收到不允许的数据类型而断开连接 (如仅接收文本数据的终端接收到了二进制数据). |
| `1004` |  | **保留。** 其意义可能会在未来定义。 |
| `1005` | `CLOSE_NO_STATUS` | **保留。** 表示没有收到预期的状态码。 |
| `1006` | `CLOSE_ABNORMAL` | **保留。** 用于期望收到状态码时连接非正常关闭 (也就是说，没有发送关闭帧). |
| `1007` | Unsupported Data | 由于收到了格式不符的数据而断开连接 (如文本消息中包含了非 UTF-8 数据). |
| `1008` | Policy Violation | 由于收到不符合约定的数据而断开连接。这是一个通用状态码，用于不适合使用 1003 和 1009 状态码的场景。 |
| `1009` | `CLOSE_TOO_LARGE` | 由于收到过大的数据帧而断开连接。 |
| `1010` | Missing Extension | 客户端期望服务器商定一个或多个拓展，但服务器没有处理，因此客户端断开连接。 |
| `1011` | Internal Error | 客户端由于遇到没有预料的情况阻止其完成请求，因此服务端断开连接。 |
| `1012` | Service Restart | 服务器由于重启而断开连接。[Ref] |
| `1013` | Try Again Later | 服务器由于临时原因断开连接，如服务器过载因此断开一部分客户端连接。[Ref] |
| `1014` |  | **由 WebSocket 标准保留以便未来使用。** |
| `1015` | TLS Handshake | **保留。** 表示连接由于无法完成 TLS 握手而关闭 (例如无法验证服务器证书). |
| `1016`–`1999` |  | **由 WebSocket 标准保留以便未来使用。** |
| `2000`–`2999` |  | **由 WebSocket 拓展保留使用。** |
| `3000`–`3999` |  | ?可以由库或框架使用.? **不应**由应用使用。可以在 IANA 注册，先到先得。 |
| `4000`–`4999` |  | 可以由应用使用。 |

`CloseEvent.reason` (en-US) 只读

返回一个 `DOMString` 用以表示服务器关闭连接的原因。这是由服务器和子协议决定的。

`CloseEvent.wasClean` (en-US) 只读

返回一个 `Boolean` 用以表示连接是否完全关闭。

Methods
-------

*该接口也继承了其父类 `Event` 的属性。*

`CloseEvent.initCloseEvent()` (en-US)
非标准

已弃用

初始化创建的 `CloseEvent` 的值。如果该事件已经被处理，这个方法什么也不做。不要直接使用这个方法，使用 `CloseEvent()` (en-US) ?构造器来代替。

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

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

参考
--

* `WebSocket`


CustomElementRegistry - Web API 接口参考

CustomElementRegistry
=====================

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

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

* Learn more
* See full compatibility
* Report feedback
\*\*`CustomElementRegistry`\*\*接口提供注册自定义元素和查询已注册元素的方法。要获取它的实例，请使用 `window.customElements`属性。

方法
--

`CustomElementRegistry.define()`

定义一个新的自定义元素。

`CustomElementRegistry.get()`

返回指定自定义元素的构造函数，如果未定义自定义元素，则返回`undefined`。

`CustomElementRegistry.upgrade()`

Upgrades a custom element directly, even before it is connected to its shadow root.

`CustomElementRegistry.whenDefined()`

返回当使用给定名称定义自定义元素时将会执行的 `promise`。（如果已经定义了这样一个自定义元素，那么立即执行返回的 promise。）

示例
--

以下代码来自我们的 word-count-web-component 示例（查看实时运行版本）。请注意我们如何使用 `CustomElementRegistry.define()` 方法在创建其类后定义自定义元素。

```js
// Create a class for the element
class WordCount extends HTMLParagraphElement {
  constructor() {
    // Always call super first in constructor
    super();

    // count words in element's parent element
    var wcParent = this.parentNode;

    function countWords(node) {
      var text = node.innerText || node.textContent;
      return text.split(/\s+/g).length;
    }

    var count = "Words: " + countWords(wcParent);

    // Create a shadow root
    var shadow = this.attachShadow({ mode: "open" });

    // Create text node and add word count to it
    var text = document.createElement("span");
    text.textContent = count;

    // Append it to the shadow root
    shadow.appendChild(text);

    // Update count when element content changes
    setInterval(function () {
      var count = "Words: " + countWords(wcParent);
      text.textContent = count;
    }, 200);
  }
}

// Define the new element
customElements.define("word-count", WordCount, { extends: "p" });
```

规范
--

| Specification |
| --- |
| HTML Standard # custom-elements-api |

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

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


IDBIndex - Web API 接口参考

IDBIndex
========

IndexedDB API 中的 IDBIndex 接口提供了异步获取数据库中一个index (en-US)的功能。index 是一种用于在另一个 object store 中查找记录的 object store，其被称为被引用的 object store。你可以通过使用该接口来取回数据。

你可以通过记录的键或使用一个 index 取回一个 object store 中的这些记录 (cursors 提供了第三种方式：请见 `IDBCursor`)。一个 index 可以让你在 object store 的 records 中，通过使用 records 的 properties（属性）来寻找 records。

index 是一个持久的键 - 值存储，其中其记录的值部分是被引用 object store 中的 record 的关键部分。在 object store 中新增、更新或是删除 records 时，索引中的 records 将自动填充。索引中的每条记录只能指向其引用的 object store 中的唯一一条记录，但是多个索引可以引用同一个 object store。当 object store 变更时，所有引用 object store 的索引都会自动更新。

索引中的 records 总是按照 records 的 key 进行排序。然而，不像 object stores，一个给定的 index 可以包含具有相同 key 的多条记录。这些 records 将根据被引用 object store 中的主键进一步排序。

你可以设置在一个范围内的 key，点击这里查看更多： `IDBKeyRange`.

Methods
-------

Inherits from: EventTarget

`IDBIndex.count` (en-US)

Returns an `IDBRequest` object, and in a separate thread, returns the number of records within a key range.

`IDBIndex.get` (en-US)

Returns an `IDBRequest` object, and, in a separate thread, finds either the value in the referenced object store that corresponds to the given key or the first corresponding value, if `key` is a key range.

`IDBIndex.getAll` (en-US)
非标准

Instantly retrieves all objects inside an `IDBObjectStore`, setting them as the `result` of the request object.

`IDBIndex.getKey` (en-US)

Returns an `IDBRequest` object, and, in a separate thread, finds either the given key or the primary key, if `key` is a key range.

`IDBIndex.getAllKeys` (en-US)
非标准

Instantly retrieves the keys of all objects inside an `IDBObjectStore`, setting them as the `result` of the request object.

`IDBIndex.openCursor` (en-US)

Returns an `IDBRequest` object, and, in a separate thread, creates a cursor over the specified key range.

`IDBIndex.openKeyCursor` (en-US)
非标准

Returns an `IDBRequest` object, and, in a separate thread, creates a cursor over the specified key range, as arranged by this index.

Properties
----------

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

index 的名称。

`IDBIndex.objectStore` (en-US) 只读

index 所指向的 object store 的名称。

`IDBIndex.keyPath` (en-US) 只读

此 index 的关键路径。它如果为 null，则 index 不是自动填充的。

`IDBIndex.multiEntry` (en-US) 只读

影响 index 的 key 路径的计算结果生成数组时索引的行为方式。如果为 true，那么对于 key 数组中的每一项，索引中都有一条记录。如果为 false，那么对于数组中的每个 key 都有一条记录。

`IDBIndex.unique` (en-US) 只读

如果为 true，这个 index 不会允许 key 有重复值。

Examples
--------

Opening a transaction then using `get()` to retrieve an object of known key:

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

// these two event handlers act on the database being opened successfully, or not
request.onerror = function(event) {
  note.innerHTML += '<li>Error loading database.</li>';
};

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

// store the result of opening the database in the db variable.
db = request.result;

// Open a transaction on the current database and get a reference to the object store
//that we want to pull information out of
var transaction = db.transaction(["toDoList"]);
var objectStore = transaction.objectStore("toDoList");

// Use get() to get a specific object from the object store, the key of which is "Walk dog"
var request = objectStore.get("Walk dog");
request.onerror = function(event) {
  console.log("There is no record stored for " + request.result.taskTitle);
};
request.onsuccess = function(event) {
  // Do something with the request.result!
  console.log("The deadline time for " + request.result.taskTitle + " is " +
              request.result.hours + ":" + request.result.minutes + ".";
};
```

**备注：** need to work out a way to retrieve a series/range of objects using an index, or just all of them. Is this possible with get, or is this a job for cursor?

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

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

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

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

See also
--------

To learn more about various topics, see the following

* Starting transactions: `IDBDatabase`
* Setting transaction modes: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* The reference application for the examples in this reference: To-do Notifications (view example live.) Not every snippet appears in this example, but every example uses the same data structure and syntax, and they will make sense in the context of this example.


文件系统 API - Web API 接口参考

文件系统 API
========

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

文件系统 API——以及通过文件系统访问 API提供的扩展来访问设备文件系统中的文件——允许使用文件读写以及文件管理功能。

概念与用法
-----

此 API 允许程序与用户本地设备上的或是用户能够访问的网络文件系统上的文件进行交互。此 API 的核心功能包括读取文件、写入或保存文件以及访问目录结构。

大多数与文件和目录的交互都通过句柄来完成。父类 `FileSystemHandle` 派生出两个子类：`FileSystemFileHandle` 和 `FileSystemDirectoryHandle`，分别表示文件句柄和目录句柄。

一个句柄代表了用户操作系统上的一个文件或目录。你可以通过调用诸如 `window.showOpenFilePicker()` 和 `window.showDirectoryPicker()` 一类的方法向用户显示一个文件选择器或目录选择器，以此来获得句柄。一旦调用了这些函数，选择器就会出现，用户可以用它选择一个文件或目录。只要这个步骤成功完成，就会返回句柄。

你还可以从以下途径获得句柄：

* HTML 拖放 API 的 `DataTransferItem.getAsFileSystemHandle()` (en-US) 方法。
* 文件处理 API。

每种句柄都提供了其独有的功能，取决于你使用的种类，会有些许差异（详见接口部分）。在获得句柄后，你便可以访问文件的数据或是被选中的目录的信息（包含子目录）。此 API 开辟了 web 此前一直缺乏的潜在功能。但不论如何，安全性是设计 API 时的首要考量，除非用户明确授权，否则就不允许访问文件和目录的数据（注意：源私有文件系统并非如此，因为其对用户不可见）。

**备注：** 使用此 API 的特性时可能会抛出的各种异常已在规范定义的相关页面中列出。然而，API 与底层操作系统的交互使得实际情况更加复杂。这里提供一篇关于在规范中列出错误对应表的提议，其中包含了一些有用的信息。

**备注：** 基于 `FileSystemHandle` 的对象能够被序列化存储至 IndexedDB 数据库实例中，也可以通过 `postMessage()` 移交。

### 源私有文件系统

源私有文件系统（origin private file system，OPFS）属于文件系统 API，提供了页面所属的源专用的存储端点，并且不像常规文件系统那样对用户可见。它提供对一种经过高度性能优化的特殊文件的访问能力的选择，例如，对文件内容的原地写入访问。

请阅读我们的源私有文件系统，以了解如何使用它。

### 保存文件

* 对于异步句柄，使用 `FileSystemWritableFileStream` 接口。当你想要保存的数据是 `Blob`、`String` 对象、字符串字面量或 `buffer` 形式的时候，你可以打开一个写入流把数据保存到文件。可以是已经存在的文件，也可以是新文件。
* 对于同步的 `FileSystemSyncAccessHandle`，使用 `write()` 方法写入更改。你还可以选择调用 `flush()` 以使更改在指定的时间点写入磁盘（或者你也可以让底层操作系统在其认为合适的时间点执行写入，这么做大多数情况下应该都不会有问题）。
接口
--

`FileSystemHandle`

**`FileSystemHandle`** 接口的对象代表一个条目。多个句柄可以指代同一个条目。大多数情况你都不会直接用到 `FileSystemHandle`，而是会用到它的两个子接口 `FileSystemFileHandle` 和 `FileSystemDirectoryHandle`。

`FileSystemFileHandle`

提供一个文件系统条目的句柄。

`FileSystemDirectoryHandle`

提供一个文件系统目录的句柄。

`FileSystemSyncAccessHandle`

提供一个文件系统条目的同步句柄，用于在磁盘上原地操作单个文件。其在文件读写上的同步特性可在异步操作开销较大的情景中使关键方法拥有更优秀的性能，例如 WebAssembly。此类只能在专用于操作源私有文件系统上的文件的 Web Worker 中访问。

`FileSystemWritableFileStream`

属于 `WritableStream` 对象，附加了便于操作磁盘上单个文件的方法。

示例
--

### 访问文件

以下代码允许用户在文件选择器中选择一个文件。

```js
async function getFile() {
  // 打开文件选择器并从结果中解构出第一个句柄
  const [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  return file;
}
```

下面的异步函数可以显示一个文件选择器，并在选择了文件时使用 `getFile()` 方法取得内容。

```js
const pickerOpts = {
  types: [
    {
      description: "Images",
      accept: {
        "image/\*": [".png", ".gif", ".jpeg", ".jpg"],
      },
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false,
};

async function getTheFile() {
  // 打开文件选择器并从结果中解构出第一个句柄
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // 获取文件内容
  const fileData = await fileHandle.getFile();
}
```

### 访问目录

下面的示例能够取得指定名称的目录的句柄，如果目录不存在，则创建。

```js
const dirName = "directoryToGetName";

// 假设我们已经有一个目录句柄：'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true });
```

下面的异步函数使用 `resolve()` 来查找被选择文件相对于指定目录句柄的路径。

```js
async function returnPathDirectories(directoryHandle) {
  // 通过显示文件选择器来获得一个文件句柄
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // 如果用户取消了选择或者打开文件失败
    return;
  }

  // 检查文件句柄是否存在于目录句柄的目录中
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePaths === null) {
    // 不在目录句柄中
  } else {
    // relativePaths 是一个包含名称的数组，指示相对路径

    for (const name of relativePaths) {
      // 打印数组的每个元素
      console.log(name);
    }
  }
}
```

### 写入文件

以下异步函数能够打开一个文件选择器，并在选择了文件时返回一个 `FileSystemFileHandle`。然后使用 `FileSystemFileHandle.createWritable()` 方法创建一个写入流。

然后将用户定义的一个 `Blob` 写入流中，随后关闭该流。

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

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

  // 写入我们的文件
  await writableStream.write(imgBlob);

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

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

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

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

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

// 裁切文件的字节长度为 size 变量的大小
writableStream.write({ type: "truncate", size });
```

### 在 OPFS 中同步读写文件

这个示例展示如何在源私有文件系统中同步读写文件。

以下异步事件处理函数处于 Web Worker 上下文，从主线程接收消息。

* 创建一个异步文件访问句柄。
* 获取文件大小并创建一个 `ArrayBuffer` 来容纳它。
* 将文件内容读取到缓冲区中。
* 将消息编码，并将其写入到文件末尾。
* 将更改持久化至磁盘并关闭访问句柄。

```js
onmessage = async (e) => {
  // 获取从主线程发往 worker 的消息
  const message = e.data;

  // 获取 OPFS 中草稿文件的句柄
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // 获取同步访问句柄
  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();
};
```

**备注：** 在规范早期版本中，`FileSystemSyncAccessHandle` 的 `close()`、`flush()`、`getSize()` 和 `truncate()` 被不合逻辑地指定为异步方法。此问题现已被修正，但某些浏览器依然支持异步版本。

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemhandle |
| File System Standard # api-filesystemfilehandle |

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

### api.FileSystemHandle

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

### api.FileSystemFileHandle

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

参见
--

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


ProgressEvent - Web API 接口参考

ProgressEvent
=============

**`ProgressEvent`** 接口是测量如 HTTP 请求（一个`XMLHttpRequest`，或者一个 `<img>`，`<audio>`，`<video>`，`<style>` 或 `<link>` 等底层资源的加载）等底层流程进度的事件。

Event

ProgressEvent构造方法
----

`ProgressEvent()`

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

属性
--

*同时继承它的父元素 `Event` 的属性。*

`ProgressEvent.lengthComputable` 只读

是一个 `Boolean` (en-US) 标志，表示底层流程将需要完成的总工作量和已经完成的工作量是否可以计算。换句话说，它告诉我们进度是否可以被测量。

`ProgressEvent.loaded` 只读

是一个 `unsigned long long` 类型数据，表示底层流程已经执行的工作总量。可以用这个属性和 `ProgressEvent.total` 计算工作完成比例。当使用 HTTP 下载资源，它只表示内容本身的部分，不包括首部和其他开销。

`ProgressEvent.total` 只读

是一个 `unsigned long long` 类型数据，表示正在执行的底层流程的工作总量。当使用 HTTP 下载资源，它只表示内容本身的部分，不包括首部和其他开销。

方法
--

*同时继承它的父元素 `Event` 的方法。*

`ProgressEvent.initProgressEvent()` (en-US)
已弃用

非标准

使用被弃用的 `Document.createEvent("ProgressEvent")` 方法，来初始化一个已经创建好的 `ProgressEvent`。

示例
--

下面的示例为一个新建的 `XMLHTTPRequest` 添加了一个 `ProgressEvent`，并使用它来显示请求状态。

```js
var progressBar = document.getElementById("p"),
  client = new XMLHttpRequest();
client.open("GET", "magical-unicorns");
client.onprogress = function (pe) {
  if (pe.lengthComputable) {
    progressBar.max = pe.total;
    progressBar.value = pe.loaded;
  }
};
client.onloadend = function (pe) {
  progressBar.value = pe.loaded;
};
client.send();
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # interface-progressevent |

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

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

相关链接
----

* The `Event` base interface.


MimeType - Web API 接口参考

MimeType
========

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

这 **`MimeType`** 接口提供了包含以下信息 MIME 与特定插件关联的类型。`NavigatorPlugins.mimeTypes` (en-US) 返回此对象的数组。

属性
--

`MimeType.type`

返回关联的插件的 MIME 类型。

`MimeType.description`

如果没有返回相关插件或空字符串的描述。

`MimeType.suffixes`

包含插件，所显示的数据的有效文件扩展名的字符串或空字符串，如果扩展名为特定的模块无效。例如，浏览器内容解密模块可能出现在插件列表中，但支持更多文件 extenions 比可以预期。因此，它可能会返回一个空字符串。

`MimeType.enabledPlugin`

返回一个 `Plugin` 实例，其包含插件本身的信息。

规范
--

| Specification |
| --- |
| HTML Standard # mimetype |

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

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


ShadowRoot - Web API 接口参考

ShadowRoot
==========

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

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

* Learn more
* See full compatibility
* Report feedback
Shadow DOM API 的 **`ShadowRoot`** 接口是一个 DOM 子树的根节点，它与文档的主 DOM 树分开渲染。

你可以通过使用一个元素的 `Element.shadowRoot` 属性来检索它的参考，假设它是由 `Element.attachShadow()` 创建的并使 `mode` 设置为 `open`.

属性
--

`ShadowRoot.delegatesFocus` 只读
非标准

返回一个 boolean 值表明在 shadow 添加时 delegatesFocus 是否被设置 (see `Element.attachShadow()`)

`ShadowRoot.host` (en-US) 只读

`ShadowRoot` 附加的宿主 DOM 元素。

`ShadowRoot.innerHTML`

`ShadowRoot` 内部的 DOM 树。

`ShadowRoot.mode` 只读

`ShadowRoot` 的模式——可以是 `open` 或者 `closed`。这定义了 shadow root 的内部实现是否可被 JavaScript 访问及修改 — 也就是说，该实现是否公开，例如，`<video>` 标签内部实现无法被 JavaScript 访问及修改。

### 从 DocumentOrShadowRoot 中包含的属性

*`ShadowRoot` 接口包含了下列从`DocumentOrShadowRoot` mixin 中定义的属性。请注意它现在仅在 Chrome 浏览器中应用; 其他的浏览器仍在`Document`接口实现。*

`DocumentOrShadowRoot.activeElement` 只读

返回含有获取焦点了的 shadow tree 的 `Element`

`DocumentOrShadowRoot.styleSheets` 只读

返回 `CSSStyleSheet` 的 `StyleSheetList` 对象，用于代表通过链接加载到文档中或内嵌的样式表。

方法
--

*`ShadowRoot` 接口包含了下列几个在 `DocumentOrShadowRoot` mixin 中定义的方法。请注意它现在仅在 Chrome 浏览器中应用; 其他的浏览器仍在`Document`接口实现。*

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

返回一个 `Selection` 类来表明用户选择的文本选区或者光标所在的位置

`DocumentOrShadowRoot.elementFromPoint()`

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

`DocumentOrShadowRoot.elementsFromPoint()`

返回一个包含所有在指定位置上的元素的 Array

`DocumentOrShadowRoot.caretPositionFromPoint()` (en-US)

返回一个 `CaretPosition` 对象，包括包含了光标的 DOM 节点，以及光标在该节点中的字符偏移量

例子
--

下面的这段代码是从我们的 life-cycle-callbacks 示例 (查看在线示例) 中提取出来的，它创建了一个由元素的属性指定的大小相等的正方形。

Inside the `<custom-square>` element's class definition we include some life cycle callbacks that make a call to an external function, `upateStyle()`, which actually applies the size and color to the element. You'll see that we are passing it `this` (the custom element itself) as a parameter.

```js
connectedCallback() {
  console.log('Custom square element added to page.');
  updateStyle(this);
}

attributeChangedCallback(name, oldValue, newValue) {
  console.log('Custom square element attributes changed.');
  updateStyle(this);
}
```

In the `updateStyle()` function itself, we get a reference to the shadow DOM using `Element.shadowRoot`. From here we use standard DOM traversal techniques to find the `<style>` element inside the shadow DOM and then update the CSS found inside it:

```js
function updateStyle(elem) {
  var shadow = elem.shadowRoot;
  var childNodes = shadow.childNodes;
  for (var i = 0; i < childNodes.length; i++) {
    if (childNodes[i].nodeName === "STYLE") {
      childNodes[i].textContent =
        "div {" +
        "width: " +
        elem.getAttribute("l") +
        "px;" +
        "height: " +
        elem.getAttribute("l") +
        "px;" +
        "background-color: " +
        elem.getAttribute("c") +
        ";" +
        "}";
    }
  }
}
```

规范
--

| Specification |
| --- |
| DOM Standard # interface-shadowroot |

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

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


VRDisplay - Web API 接口参考

VRDisplay
=========

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

WebVR API 中的 **`VRDisplay`** 代表任何支持此 API 的 VR 设备。它包括了设备 ID、描述信息等诸如此类的通用信息，以及用于开始呈现 VR 场景、检索眼睛参数和显示能力以及其他重要的功能和方法。

可以通过调用 `Navigator.getVRDisplays()` (en-US) 方法得到所有连接的 VR 设备数组。

属性
--

`VRDisplay.capabilities` (en-US) 只读

返回一个 `VRDisplayCapabilities` (en-US) 对象，用于指示 VRDisplay 的各种功能。

`VRDisplay.depthFar` (en-US)

获取或设置眼睛可视锥的最远深度。

`VRDisplay.depthNear` (en-US)

获取或设置眼睛可视锥的最近深度。

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

返回此 VRDisplay 的标识符，它也用作与 Gamepad API 的关联（详见 `Gamepad.displayId` (en-US)）。

`VRDisplay.displayName` (en-US) 只读

返回一个不反人类的名称来标识此 `VRDisplay`。

`VRDisplay.isConnected` (en-US) 只读

返回一个 `Boolean` (en-US) 值，指示 `VRDisplay` 是否连接到计算机。

`VRDisplay.isPresenting` (en-US) 只读

返回一个 `Boolean` (en-US) 值，指示 `VRDisplay` 当前是否由内容被呈现。

`VRDisplay.stageParameters` (en-US) 只读

如果 VR 设备支持房间规模测验，则返回一个包含房间尺寸参数的 `VRStageParameters` (en-US) 对象。

方法
--

`VRDisplay.getEyeParameters()` (en-US)

返回指定一侧眼睛参数的 `VREyeParameters` (en-US) 对象。

`VRDisplay.getLayers()` (en-US)

返回 VRDisplay 当前显示的图层。

`VRDisplay.getPose()` (en-US)

Returns a `VRPose` object defining the future predicted pose of the `VRDisplay` as it will be when the current frame is actually presented.

`VRDisplay.getImmediatePose()` (en-US)

Returns a `VRPose` object defining the current pose of the `VRDisplay`, with no prediction applied.

`VRDisplay.resetPose()` (en-US)

Resets the pose for this `VRDisplay`, treating its current `VRPose.position` (en-US) and `VRPose.orientation` (en-US) as the "origin/zero" values.

`VRDisplay.cancelAnimationFrame()` (en-US)

A special implementation of `Window.cancelAnimationFrame` that allows callbacks registered with `VRDisplay.requestAnimationFrame()` to be unregistered.

`VRDisplay.requestAnimationFrame()`

A special implementation of `Window.requestAnimationFrame` containing a callback function that will be called every time a new frame of the `VRDisplay` presentation is rendered.

`VRDisplay.requestPresent()` (en-US)

Starts the `VRDisplay` presenting a scene.

`VRDisplay.exitPresent()` (en-US)

Stops the `VRDisplay` presenting a scene.

`VRDisplay.submitFrame()` (en-US)

Captures the current state of the `VRLayer` (en-US) currently being presented and displays it on the `VRDisplay`.

示例
--
```

TBD.
```

规范
--

该 API 在旧的 WebVR API（已被 WebXR Device API 取代）中定义。它不再有望成为标准。

在所有浏览器都实现新的 WebXR API (en-US) 之前，建议使用框架（如：A-Frame、Babylon.js 或 Three.js）或 polyfill 来开发适用于所有浏览器的 WebXR 应用程序。[1]

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

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

参见
--

* WebVR API


Compression Stream API - Web API 接口参考

Compression Stream API
======================

**Compression Stream API** 提供了一种 JavaScript API，使用 gzip 或者默认格式压缩和解压缩数据流。

内置的压缩库意味着 JavaScript 应用不再需要包含其它压缩库，这使得应用程序的下载大小更小。

接口
--

`CompressionStream`

压缩数据流。

`DecompressionStream`

解压缩数据流。

示例
--

在此示例中，使用 gzip 对流进行压缩。

```js
const compressedReadableStream = inputReadableStream.pipeThrough(
  new CompressionStream("gzip"),
);
```

以下示例中，函数使用 gzip 解压缩 blob。

```js
async function DecompressBlob(blob) {
  const ds = new DecompressionStream("gzip");
  const decompressedStream = blob.stream().pipeThrough(ds);
  return await new Response(decompressedStream).blob();
}
```

规范
--

| Specification |
| --- |
| Compression Streams # compression-stream |

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

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


MediaDevices - Web API 接口参考

MediaDevices
============

**`MediaDevices`** 接口提供访问连接媒体输入的设备，如照相机和麦克风，以及屏幕共享等。它可以使你取得任何硬件资源的媒体数据。

属性
--

*从父类`EventTarget`中继承的属性。*

事件
--

`devicechange`

当媒体输入或输出设备连接到用户计算机或从用户计算机移除时触发。

方法
--

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

`MediaDevices.enumerateDevices()`

获取有关系统中可用的媒体输入和输出设备的一系列信息。

`getSupportedConstraints()`

返回一个符合 `MediaTrackSupportedConstraints` (en-US) 的对象。该对象指明了 `MediaStreamTrack` 接口支持的可约束的属性。查看 Media Streams API (en-US) 以了解更多相关信息。

`getDisplayMedia()`

提示用户选择显示器或显示器的一部分（例如窗口）以捕获为`MediaStream` 以便共享或记录。返回解析为 MediaStream 的 Promise。

`MediaDevices.getUserMedia()`

在用户通过提示允许的情况下，打开系统上的相机或屏幕共享和/或麦克风，并提供 `MediaStream` 包含视频轨道和/或音频轨道的输入。

示例
--

```js
"use strict";

// Put variables in global scope to make them available to the browser console.
var video = document.querySelector("video");
var constraints = (window.constraints = {
  audio: false,
  video: true,
});
var errorElement = document.querySelector("#errorMsg");

navigator.mediaDevices
  .getUserMedia(constraints)
  .then(function (stream) {
    var videoTracks = stream.getVideoTracks();
    console.log("Got stream with constraints:", constraints);
    console.log("Using video device: " + videoTracks[0].label);
    stream.onended = function () {
      console.log("Stream ended");
    };
    window.stream = stream; // make variable available to browser console
    video.srcObject = stream;
  })
  .catch(function (error) {
    if (error.name === "ConstraintNotSatisfiedError") {
      errorMsg(
        "The resolution " +
          constraints.video.width.exact +
          "x" +
          constraints.video.width.exact +
          " px is not supported by your device.",
      );
    } else if (error.name === "PermissionDeniedError") {
      errorMsg(
        "Permissions have not been granted to use your camera and " +
          "microphone, you need to allow the page access to your devices in " +
          "order for the demo to work.",
      );
    }
    errorMsg("getUserMedia error: " + error.name, error);
  });

function errorMsg(msg, error) {
  errorElement.innerHTML += "<p>" + msg + "</p>";
  if (typeof error !== "undefined") {
    console.error(error);
  }
}
```

规范
--

| Specification |
| --- |
| Media Capture and Streams # mediadevices |

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

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

参见
--

* 媒体捕捉与媒体流 API: The API this interface is part of.
* Screen Capture API: The API defining the `getDisplayMedia()` method.
* WebRTC API
* `Navigator.mediaDevices`: Returns a reference to a `MediaDevices` object that can be used to access devices.
* CameraCaptureJS: HTML5 video capture and playback using `MediaDevices` and the MediaStream Recording API (source on GitHub)
* OpenLang: HTML5 video language lab web application using `MediaDevices` and the MediaStream Recording API for video recording (source on GitHub)


BatteryManager（电源管理） - Web API 接口参考

BatteryManager（电源管理）
====================

电池状态 API 中的 `BatteryManager` 接口提供了系统电池电量的一些信息。`navigator.getBattery()` 方法返回一个 promise 对象，该 promise 在完成状态时将返回一个 `BatteryManager` 接口。

EventTarget

BatteryManager属性
--

`BatteryManager.charging` 只读

一个布尔值，说明当前电池是否正在充电。

`BatteryManager.chargingTime` (en-US) 只读

一个数字，代表距离充电完毕还需多少秒，如果为 0 则充电完毕。

`BatteryManager.dischargingTime` (en-US) 只读

一个数字，代表距离电池耗电至空且系统挂起需要多少秒。

`BatteryManager.level` (en-US) 只读

一个数字，代表系统电量的水平，这个值放缩在 0.0 至 1.0 之间。

方法
--

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

### 事件

`chargingchange` (en-US)

当电池充电状态（`charging` 属性）更新时被触发。

`chargingtimechange` (en-US)

当电池充电时间（`chargingTime` (en-US) 属性）更新时被触发。

`dischargingtimechange` (en-US)

当电池断开充电的时间（`dischargingTime` (en-US) 属性）更新时被触发。

`levelchange` (en-US)

当电池电量（`level` (en-US) 属性）更新时被触发。

规范
--

| Specification |
| --- |
| Battery Status API # the-batterymanager-interface |

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

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

参见
--

* 电池状态 API
* `navigator.getBattery`


View Transitions API - Web API 接口参考

View Transitions API
====================

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

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

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

**View Transitions API** 提供了一种机制，可以在更新 DOM 内容的同时，轻松地创建不同 DOM 状态之间的动画过渡。同时还可以在单个步骤中更新 DOM 内容。

概念和用法
-----

视图过渡是一种流行的设计选择，可以减少用户认知负荷，帮助他们保持上下文，并减少他们在应用程序的状态或视图之间移动时感知的加载延迟。

但是，在 Web 上创建视图过渡历来很困难。在单页应用程序（SPA）中，状态之间的过渡往往需要编写大量的 CSS 和 JavaScript 来：

* 处理新旧内容的加载和定位。
* 为新旧状态添加动画以创建过渡。
* 防止用户与旧内容的意外交互而导致的问题。
* 完成过渡后删除旧内容。

像阅读位置丢失、焦点混乱和实时区域宣告的奇怪行为等无障碍问题，也可能由于新旧内容同时存在于 DOM 中而导致。此外，跨文档视图过渡（即在常规非 SPA 网站中跨越不同页面）是不可能的。

View Transitions API 提供了一种更简单的方法来处理必需的 DOM 更改和过渡动画。

**备注：** View Transitions API 目前不支持跨文档视图过渡，但这已计划在未来的规范版本中实现，并正在积极开发中。

### 创建基本视图过渡

例如，一个 SPA 应用可能包含获取新内容和响应某种事件并更新 DOM 的功能，例如点击导航链接或从服务器推送更新。在我们的基础视图过渡演示中，我们将其简化为一个 `displayNewImage()` 函数，该函数根据点击的缩略图显示新的全尺寸图像。我们将其封装在 `updateView()` 函数中，该函数仅在浏览器支持时才调用 View Transitions API：

```js
function updateView(event) {
  // 处理在 <a> 或 <img> 上触发事件的差异
  const targetIdentifier = event.target.firstChild || event.target;

  const displayNewImage = () => {
    const mainSrc = `${targetIdentifier.src.split("\_th.jpg")[0]}.jpg`;
    galleryImg.src = mainSrc;
    galleryCaption.textContent = targetIdentifier.alt;
  };

  // 浏览器不支持 View Transitions 时的回退方案：
  if (!document.startViewTransition) {
    displayNewImage();
    return;
  }

  // 开始一次视图过渡：
  const transition = document.startViewTransition(() => displayNewImage());
}
```

这段代码足以处理显示的图像之间的过渡。支持的浏览器将以平滑的交叉淡入淡出（默认的视图过渡）显示新旧图像和标题的变化。它仍可以在不支持的浏览器中工作，但没有漂亮的动画效果。

值得一提的是，`startViewTransition()` 返回一个 `ViewTransition` 实例，该实例包含了多个 Promise, 允许你在到达视图过渡过程的不同阶段时运行代码。

### 视图过渡过程

让我们来看看这是如何工作的：

1. 当调用 `document.startViewTransition()` 时，API 会截取当前页面的屏幕截图。
2. 接下来，调用传递给 `startViewTransition()` 的回调函数，即 `displayNewImage`，这会导致 DOM 发生更改。
 当回调函数成功运行时，`ViewTransition.updateCallbackDone` Promise 兑现，允许你响应 DOM 更新。
3. API 会捕获页面的新状态并实时展示。
4. API 构造了一个具有以下结构的伪元素树：
```

::view-transition
└─ ::view-transition-group(root)
   └─ ::view-transition-image-pair(root)
      ├─ ::view-transition-old(root)
      └─ ::view-transition-new(root)
```

    * `::view-transition` 是视图过渡叠加层的根元素，它包含所有视图过渡且位于所有其他页面内容的顶部。
    * `::view-transition-old` 是旧页面视图的屏幕截图，且 `::view-transition-new` 是新页面视图的实时展示。这两者都呈现为替换内容，就像 `<img>` 或 `<video>` 那样，这意味着它们可以方便的使用属性进行样式设置，例如 `object-fit` 和 `object-position`。当过渡动画即将运行时，`ViewTransition.ready` Promise 兑现，你可以响应它进行一些操作，例如运行自定义的 JavaScript 动画，而不是默认的动画。
5. 旧页面视图的 `opacity` 从 1 过渡到 0，而新视图从 0 过渡到 1，这就是默认的交叉淡入淡出效果。
6. 当过渡动画结束时，`ViewTransition.finished` Promise 兑现，你可以响应它进行一些操作。
### 为不同的元素使用不同的过渡效果

目前，当 DOM 更新时发生变化的不同元素都使用相同的过渡动画。如果你想让不同的元素以不同于默认的“root”动画的方式进行过渡，你可以使用 `view-transition-name` 属性将它们分开。例如：

```css
figcaption {
  view-transition-name: figure-caption;
}
```

我们给 `<figcaption>` 元素设置了值为 `figure-caption` 的 `view-transition-name`，以将其与页面上的其余部分分开，便于在视图过渡时进行分离。

应用此 CSS 后，伪元素树现在如下所示：
```

::view-transition
├─ ::view-transition-group(root)
│ └─ ::view-transition-image-pair(root)
│     ├─ ::view-transition-old(root)
│     └─ ::view-transition-new(root)
└─ ::view-transition-group(figure-caption)
  └─ ::view-transition-image-pair(figure-caption)
      ├─ ::view-transition-old(figure-caption)
      └─ ::view-transition-new(figure-caption)
```

第二组伪元素的存在允许将单独的视图过渡样式仅应用于 `<figcaption>`。不同的新旧页面视图之间捕获和处理是完全独立的。

`view-transition-name` 的值可以是除 `none` 之外的任何值——`none` 值表示该元素不参与视图过渡。

**备注：** `view-transition-name` 必须是唯一的。如果两个渲染元素同时具有相同的 `view-transition-name`，`ViewTransition.ready` 将拒绝并跳过过渡。

### 自定义动画

视图过渡伪元素具有默认的 CSS 动画（在其参考页面中详细介绍）。

值得注意的是，`height`、`width`、`position` 和 `transform` 的过渡不使用平滑的淡入淡出动画。相反，高度和宽度过渡使用平滑的缩放动画。同时，位置和变换过渡将使用平滑的移动动画。

你可以使用常规 CSS 以任何你想要的方式修改默认动画。

例如，你要调整动画速度：

```css
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.5s;
}
```

让我们看些更有趣的东西——`<figcaption>` 的自定义动画：

```css
@keyframes grow-x {
  from {
    transform: scaleX(0);
  }
  to {
    transform: scaleX(1);
  }
}

@keyframes shrink-x {
  from {
    transform: scaleX(1);
  }
  to {
    transform: scaleX(0);
  }
}

::view-transition-old(figure-caption),
::view-transition-new(figure-caption) {
  height: auto;
  right: 0;
  left: auto;
  transform-origin: right center;
}

::view-transition-old(figure-caption) {
  animation: 0.25s linear both shrink-x;
}

::view-transition-new(figure-caption) {
  animation: 0.25s 0.25s linear both grow-x;
}
```

在这里，我们创建了一个自定义 CSS 动画并将其应用到 `::view-transition-old(figure-caption)` 和 `::view-transition-new(figure-caption)` 伪元素上。我们还为两者添加了许多其他样式，以使它们保持在同一位置，并防止默认样式干扰我们的自定义动画。

请注意，我们还发现了另一种比上面更简单且产生更好结果的过渡选项。我们最终的 `<figcaption>` 视图过渡看起来像这样：

```css
figcaption {
  view-transition-name: figure-caption;
}

::view-transition-old(figure-caption),
::view-transition-new(figure-caption) {
  height: 100%;
}
```

这是有效的，因为默认情况下，`::view-transition-group` 在新旧视图之间过渡高度和宽度。我们只需要在两个状态上设置固定的高度，就可以使其正常工作。

**备注：** 使用 View Transitions API 实现平滑、简单的过渡包含了其他几个自定义示例。

### 使用 JavaScript 控制动画

`document.startViewTransition()` 方法返回一个 `ViewTransition` 对象实例，实例中包含多个 Promise 成员，允许你在到达不同状态的过渡时运行 JavaScript。例如，`ViewTransition.ready` 在伪元素树创建并且动画即将开始时兑现，而 `ViewTransition.finished` 在动画结束后兑现，此时新页面视图对用户可见且可交互。

例如，下面的 JavaScript 可以用于创建从用户单击位置开始的圆形揭示视图过渡，动画由 Web Animations API 提供。

```js
// 保存最后一次点击事件
let lastClick;
addEventListener("click", (event) => (lastClick = event));

function spaNavigate(data) {
  // 为不支持此 API 的浏览器提供回退方案：
  if (!document.startViewTransition) {
    updateTheDOMSomehow(data);
    return;
  }

  // 获取点击位置，或者回退到屏幕中间
  const x = lastClick?.clientX ?? innerWidth / 2;
  const y = lastClick?.clientY ?? innerHeight / 2;
  // 获取到最远角的距离
  const endRadius = Math.hypot(
    Math.max(x, innerWidth - x),
    Math.max(y, innerHeight - y),
  );

  // 开始一次视图过渡：
  const transition = document.startViewTransition(() => {
    updateTheDOMSomehow(data);
  });

  // 等待伪元素创建完成：
  transition.ready.then(() => {
    // 新视图的根元素动画
    document.documentElement.animate(
      {
        clipPath: [
          `circle(0 at ${x}px ${y}px)`,
          `circle(${endRadius}px at ${x}px ${y}px)`,
        ],
      },
      {
        duration: 500,
        easing: "ease-in",
        // 指定要附加动画的伪元素
        pseudoElement: "::view-transition-new(root)",
      },
    );
  });
}
```

该动画还需要以下 CSS，以关闭默认的 CSS 动画并防止新旧视图状态以任何方式混合（新状态从旧状态上方“擦除”，而不是过渡）：

```css
::view-transition-image-pair(root) {
  isolation: auto;
}

::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
  mix-blend-mode: normal;
  display: block;
}
```

接口
--

`ViewTransition`

表示视图过渡，并提供了在过渡到达不同状态时运行代码的功能（例如，准备运行动画或动画完成），或跳过视图过渡。

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

`Document.startViewTransition()`

开始新的视图过渡并返回一个 `ViewTransition` 对象来表示它。

CSS 扩展
------

### 属性

`view-transition-name`

为选定的元素提供单独的标识名称，并使其参与与根视图过渡不同的单独视图过渡——或者如果指定了 `none` 值，则不参与视图过渡。

### 伪元素

`::view-transition`

视图过渡叠加层的根元素，它包含所有视图过渡且位于所有其他页面内容的顶部。

`::view-transition-group()`

单个视图过渡的根元素。

`::view-transition-image-pair()`

视图过渡的旧视图和新视图的容器——过渡前和过渡后。

`::view-transition-old()`

转换前的旧视图的静态屏幕截图。

`::view-transition-new()`

转换后的新视图的实时表示。

示例
--

* 基础视图过渡演示：一个基本的图像库演示，其中包含新旧图像之间的单独过渡，以及新旧标题之间的单独过渡。
* HTTP 203 播放列表：一个更复杂的视频播放器演示应用程序，包含了许多不同的视图过渡，在使用 View Transitions API 实现平滑、简单的过渡中解释了其中的很多视图过渡。
规范
--

| Specification |
| --- |
| CSS View Transitions Module Level 1 # dom-document-startviewtransition |

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

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

参见
--

* 使用 View Transitions API 实现平滑、简单的过渡
* View Transitions API：创建平滑的页面过渡


self.crypto - Web API 接口参考

self.crypto
===========

**`crypto`** 全局只读属性返回与全局对象关联的 `Crypto` 对象。此对象允许网页访问某些加密相关的服务。

虽然该属性自身的只读的，但它的所有方法（以及其子对象的方法——`SubtleCrypto`）不仅是只读的，因此容易受到 polyfill 的攻击。

虽然 `crypto` 在所有窗口上均可用，但其返回的 `Crypto` 对象在不安全的上下文中仅有一个可用的特性：`getRandomValues()` 方法。通常，你应该仅在安全上下文中使用此 API。

值
-

`Crypto` 接口的实例，提供对通用的密码学功能和强随机数生成器的访问。

示例
--

使用 `crypto` 属性来访问 `getRandomValues()` 方法。

### JavaScript

```js
globalThis.genRandomNumbers = () => {
  const array = new Uint32Array(10);
  crypto.getRandomValues(array);

  const randText = document.getElementById("myRandText");
  randText.textContent = `随机数为：${array.join(" ")}`;
};
```

### HTML

```html
<p id="myRandText">随机数为：</p>
<button type="button" onClick="genRandomNumbers()">生成 10 个随机数</button>
```

### 结果

规范
--

| Specification |
| --- |
| Web Cryptography API # dom-windoworworkerglobalscope-crypto |

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

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

参见
--

* `Window` 全局对象
* `Crypto` 接口


Coordinates - Web API 接口参考

Coordinates
===========

**`Coordinates`** （坐标）接口表示设备在地球上的位置和海拔，以及计算这些属性的精确度。

属性
--

*The `Coordinates` interface* **doesn't inherit any property**.

`Coordinates.latitude` 只读

Returns a `double` representing the position's latitude in decimal degrees.

`Coordinates.longitude` (en-US) 只读

Returns a `double` representing the position's longitude in decimal degrees.

`Coordinates.altitude` (en-US) 只读

Returns a `double` representing the position's altitude in metres, relative to sea level. This value can be `null` if the implementation cannot provide the data.

`Coordinates.accuracy` (en-US) 只读

Returns a `double` representing the accuracy of the `latitude` and `longitude` properties, expressed in meters.

`Coordinates.altitudeAccuracy` (en-US) 只读

Returns a `double` representing the accuracy of the `altitude` expressed in meters. This value can be `null`.

`Coordinates.heading` (en-US) 只读

Returns a `double` representing the direction in which the device is traveling. This value, specified in degrees, indicates how far off from heading due north the device is. `0` degrees represents true true north, and the direction is determined clockwise (which means that east is `90` degrees and west is `270` degrees). If `speed` is `0`, `heading` is `NaN`. If the device is unable to provide `heading` information, this value is `null`.

`Coordinates.speed` (en-US) 只读

Returns a `double` representing the velocity of the device in meters per second. This value can be `null`.

方法
--

**The `Coordinates` interface *neither implements, nor inherits any method.***

规范
--

| Specification |
| --- |
| Geolocation API # coordinates\_interface |

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

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

请参见
---

* Using geolocation
* The `Geolocation` interface that uses it.


HTMLElement - Web API 接口参考

HTMLElement
===========

HTMLElement 接口表示所有的 HTML 元素。一些 HTML 元素直接实现了 HTMLElement 接口，其他的间接实现 HTMLElement 接口。

属性
--

*继承自父接口 `Element` 和 `GlobalEventHandlers` 的属性。*

| 属性名称 | 属性类型 | Description |
| --- | --- | --- |
| `HTMLElement.accessKey` | `DOMString` | 获取/设置元素访问的快捷键 |
| `HTMLElement.accessKeyLabel` | `DOMString` | 返回一个包含元素访问的快捷键的字符串（只读） |
| `HTMLElement.contentEditable` | `DOMString` | 获取/设置元素的可编辑状态 |
| `HTMLElement.isContentEditable` 只读  | `Boolean` (en-US) | 表明元素的内容是否可编辑（只读） |
| `HTMLElement.dataset` 只读  | `DOMStringMap` | 获取元素的自定义属性，是一个对象（key-value，只读） |
| `HTMLElement.dir` | `DOMString` | 获取/设置元素的方向，可选的值有：ltr，rtl，auto |
| `HTMLElement.draggable` (en-US) | `Boolean` (en-US) | 设置/获取元素是否可以拖拽 |
| `HTMLElement.dropzone` 只读  | `DOMSettableTokenList` |  |
| `HTMLElement.hidden` | `Boolean` (en-US) | 获取/设置元素是否隐藏 |
| `HTMLElement.itemScope`
实验性
 | `Boolean` (en-US) |  |
| `HTMLElement.itemType` 只读
实验性
 | `DOMSettableTokenList` |  |
| `HTMLElement.itemId`
实验性
 | `DOMString` |  |
| `HTMLElement.itemRef` 只读
实验性
 | `DOMSettableTokenList` |  |
| `HTMLElement.itemProp` 只读
实验性
 | `DOMSettableTokenList` |  |
| `HTMLElement.itemValue`
实验性
 | `object` |  |
| `HTMLElement.lang` | `DOMString` | 获取/设置元素属性、文本、内容的语言 |
| `HTMLElement.offsetHeight` 只读  | `double` | 元素自身可视高度加上上下 border 的宽度 |
| `HTMLElement.offsetLeft`只读  | `double` | 元素自己 border 左边距离父元素 border 左边或者 body 元素 border 左边的距离 |
| `HTMLElement.offsetParent`只读  | `Element` | 元素的父元素，如果没有就是 body 元素 |
| `HTMLElement.offsetTop`只读  | `double` | 元素自己 border 顶部距离父元素顶部或者 body 元素 border 顶部的距离 |
| `HTMLElement.offsetWidth`只读  | `double` | 元素自身可视宽度加上左右 border 的宽度 |
| `HTMLElement.properties` 只读
实验性
 | `HTMLPropertiesCollection` |  |
| `HTMLElement.spellcheck` (en-US) | `Boolean` (en-US) |  |
| `HTMLElement.style` | `CSSStyleDeclaration` | 获取/设置元素的 style 属性 |
| `HTMLElement.tabIndex` (en-US) | `long` | 获取/设置元素的 tab 键控制次序 |
| `HTMLElement.title` | `DOMString` | 获取/设置元素的 title 属性 |
| `HTMLElement.translate` (en-US) | `Boolean` (en-US) | 获取/设置元素是否可以被翻译 |

事件
--

Listen to these events using `addEventListener()` or by assigning an event listener to the `oneventname` property of this interface.

`copy`

Fired when the user initiates a copy action through the browser's user interface.

`cut`

Fired when the user initiates a cut action through the browser's user interface.

`paste`

Fired when the user initiates a paste action through the browser's user interface.

`invalid`

Fired when an element does not satisfy its constraints during constraint validation.

方法
--

*从父元素继承的方法，`Element`.*

| Name & Arguments | Return | Description |
| --- | --- | --- |
| `HTMLElement.blur()` (en-US) | `void` | 元素失去焦点 |
| `HTMLElement.click()` | `void` | 触发元素的点击事件 |
| `HTMLElement.focus()` (en-US) | `void` | 元素获得焦点 |
| `HTMLElement.forceSpellCheck()` (en-US)
实验性
 | `void` |  |

规范
--

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

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

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

参见
--

* `Element`


Service Worker API - Web API 接口参考

Service Worker API
==================

Service worker 本质上充当 Web 应用程序、浏览器与网络（可用时）之间的代理服务器。这个 API 旨在创建有效的离线体验，它会拦截网络请求并根据网络是否可用来采取适当的动作、更新来自服务器的的资源。它还提供入口以推送通知和访问后台同步 API。

Service worker 的概念和用法
---------------------

Service worker 是一个注册在指定源和路径下的事件驱动 worker。它采用 JavaScript 文件的形式，控制关联的页面或者网站，拦截并修改访问和资源请求，细粒度地缓存资源。你可以完全控制应用在特定情形（最常见的情形是网络不可用）下的表现。

Service worker 运行在 worker 上下文：因此它无法访问 DOM，相对于驱动应用的主 JavaScript 线程，它运行在其他线程中，所以不会造成阻塞。它被设计为完全异步；因此，同步 XHR 和 Web Storage 不能在 service worker 中使用。

出于安全考量，Service worker 只能由 HTTPS 承载，毕竟修改网络请求的能力暴露给中间人攻击会非常危险，如果允许访问这些强大的 API，此类攻击将会变得很严重。在 Firefox 浏览器的用户隐私模式，Service Worker 不可用。

**备注：** 在 Firefox，为了进行测试，你可以通过 HTTP 运行 service worker（不安全）；只需选中 Firefox 开发者选项/齿轮菜单中的 **Enable Service Workers over HTTP (when toolbox is open)** 选项。

**备注：** 与之前在该领域的尝试不同，如 AppCache），service worker 并不确定你试图去做什么，但是当这些假设不完全正确时，它们会被中断。相对地，service worker 可以更细致地控制每一件事情。

**备注：** Service worker 大量使用 Promise，因为通常它们会等待响应后继续，并根据响应返回一个成功或者失败的操作。Promise 非常适合这种场景。

### 注册

使用 `ServiceWorkerContainer.register()` 方法首次注册 service worker。如果注册成功，service worker 就会被下载到客户端并尝试安装或激活（见下文），这将作用于整个域内用户可访问的 URL，或者其特定子集。

### 下载、安装和激活

此时，你的 service worker 将遵守以下生命周期：

1. 下载
2. 安装
3. 激活

用户首次访问 service worker 控制的网站或页面时，service worker 会立刻被下载。

之后，在以下情况将会触发更新：

* 一个前往作用域内页面的导航
* 在 service worker 上的一个事件被触发并且过去 24 小时没有被下载

当下载的文件发现是最新的时，就会试图安装——要么与现有的 service worker 不同（字节对比），要么是在页面或网站遇到的第一个 service worker。

如果这是首次启用 service worker，页面会首先尝试安装，安装成功后它会被激活。

如果现有 service worker 已启用，新版本会在后台安装，但仍不会被激活——这个时序称为 *worker in waiting*。直到所有已加载的页面不再使用旧的 service worker 才会激活新的 service worker。只要页面不再依赖旧的 service worker，新的 service worker 会被激活（成为 *active worker*）。使用 `ServiceWorkerGlobalScope.skipWaiting()` 可以更快地进行激活，active worker 可以使用 `Clients.claim()` 声明现有的页面

你可以监听 `install` (en-US) 事件；该事件触发时的标准行为是准备 service worker 用于使用，例如使用内建的 storage API 来创建缓存，并且放置应用离线时所需资源。

还有一个 `activate` (en-US) 事件。此事件触发的时间点通常是清理旧缓存以及其他与你的 service worker 的先前版本相关的东西的好时机。

Servcie worker 可以通过 `FetchEvent` 事件去响应请求。通过使用 `FetchEvent.respondWith` 方法，你可以任意修改对于这些请求的响应。

**备注：** 因为 `oninstall` 和 `onactivate` 完成前需要一些时间，service worker 标准提供一个 `waitUntil()` 方法。一旦在带有 promise 的 `install` 或 `activate` 事件上调用它，那么 `fetch` 和 `push` 等功能事件将等待，直到 promise 成功兑现。

构建一个基本用例的完整教程，请阅读使用 Service Worker。

其他使用场景
------

Service workers 也可以用来做这些事情：

* 后台数据同步
* 响应来自其他源的资源请求
* 集中接收计算成本高的数据更新，比如地理位置和陀螺仪信息，这样多个页面就可以利用同一组数据
* 在客户端进行 CoffeeScript、LESS、CJS/AMD 等模块编译和依赖管理（用于开发目的）
* 后台服务钩子
* 自定义模板用于特定 URL 模式
* 性能增强，比如预取用户可能需要的资源，比如相册中的后面数张图片

未来 service worker 能够用来做更多使 web 平台接近原生应用的事。值得关注的是，其他标准也能并且将会使用 service worker，例如：

* 后台同步：启动一个 service worker 即使没有用户访问特定站点，也可以更新缓存
* 响应推送：启动一个 service worker 向用户发送一条信息通知新的内容可用
* 对时间或日期作出响应
* 进入地理围栏
接口
--

`Cache`

表示用于 `Request` / `Response` 对象对的存储，作为 `ServiceWorker` 生命周期的一部分被缓存。

`CacheStorage`

表示 `Cache` 对象的存储。提供一个所有命名缓存的主目录，`ServiceWorker` 可以访问并维护名字字符串到 `Cache` 对象的映射。

`Client`

表示 service worker client 的作用域。一个 service worker client 可以是浏览器上下文的一个文档，也可以是一个由 active worker 控制的 `SharedWorker`。

`Clients`

表示一个 `Client` 对象容器；是访问当前源的活动的 service worker client 的主要途径。

`ExtendableEvent`

扩展被分发到 `ServiceWorkerGlobalScope` 的 `install` 和 `activate` 事件时序，作为 service worker 生命周期的一部分。这会确保任何功能型事件（如 `FetchEvent`）不被分发到 `ServiceWorker`，直到它更新了数据库架构、删除过期缓存项等等以后。

`ExtendableMessageEvent` (en-US)

向 service worker 触发的 `message` (en-US) 事件的时间对象（当 `ServiceWorkerGlobalScope` 从另一个上下文收到通道消息），延长了此类事件的生命周期。

`FetchEvent`

传递给 `ServiceWorkerGlobalScope.onfetch` 处理函数的参数，`FetchEvent` 代表一个在 `ServiceWorker` 的 `ServiceWorkerGlobalScope` 中分发的请求动作。它包含关于请求和响应的结果信息，并且提供 `FetchEvent.respondWith()` 方法，这个方法允许我们提供任意的响应返回到控制页面。

`InstallEvent`
已弃用

非标准

传递给 `oninstall` 处理函数的参数，`InstallEvent` 接口代表一个在 `ServiceWorker` 的 `ServiceWorkerGlobalScope` 中分发的安装动作，作为 `ExtendableEvent` 的子事件，它保证诸如 `FetchEvent` 的功能性事件在安装过程中不会被分发。

`NavigationPreloadManager` (en-US)

提供与 service worker 一起管理资源预加载的方法。

`Navigator.serviceWorker`

返回一个 `ServiceWorkerContainer` 对象，该对象提供对相关 document 的注册、删除、更新以及与 `ServiceWorker` 对象通信的访问。

`NotificationEvent`

传递给 `onnotificationclick` 处理函数的参数，`NotificationEvent` 接口代表在 `ServiceWorker` 的 `ServiceWorkerGlobalScope` 中分发的单击事件通知。

`ServiceWorker`

表示一个 service worker。多个浏览的上下文 (例如 page、worker 等等) 都能通过相同的 `ServiceWorker` 对象相关联。

`ServiceWorkerContainer`

提供一个在网络生态中把 service worker 作为一个整体的对象，包括辅助注册，反注册以及更新 service worker，并且访问 service worker 的状态以及他们的注册信息。

`ServiceWorkerGlobalScope`

表示 service worker 的全局执行上下文。

`MessageEvent`

表示发送到 `ServiceWorkerGlobalScope` 的信息。

`ServiceWorkerRegistration` (en-US)

表示 service worker 的注册。

`SyncEvent` (en-US)
非标准

SyncEvent 接口代表在 ServiceWorker 的 `ServiceWorkerGlobalScope` 上分发的同步动作。

`SyncManager` (en-US)
非标准

提供用于注册和列出同步注册的接口。

`WindowClient` (en-US)

表示在浏览器上下文中记录的 service worker 客户端的作用域，被活动的工作者控制。是 `Client` 对象的特殊类型，包含一些附加的方法和可用的属性。

规范
--

| Specification |
| --- |
| Service Workers  |

参见
--

* ServiceWorker 烹饪书
* 使用 Service Worker (en-US)
* Service worker 基础代码示例
* 是否支持 ServiceWorker
* Promise


CSSValue - Web API 接口参考

CSSValue
========

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

`CSSValue` 接口表示经过计算的当前 CSS 属性值。属性
--

`CSSValue.cssText` (en-US)

`DOMString` 代表当前值。

`CSSValue.cssValueType` (en-US) 只读

一个 `unsigned short` 类型的数据用来定义了值的类型。可取值为：

| 值 | 说明 |
| --- | --- |
| `CSS_CUSTOM` | 该值是一个自定义值。 |
| `CSS_INHERIT` | 该值是继承来的值，并且它的 `cssText` 属性值中包含`"inherit"`。 |
| `CSS_PRIMITIVE_VALUE` | 该值是一个原始值，并且是 `CSSPrimitiveValue` (en-US) 接口的一个实例，可以通过绑定特殊的构造方法在这个 CSSValue 接口的这个实例来获得。 |
| `CSS_VALUE_LIST` | 该值是一个 `CSSValue` 列表，是`CSSValueList` 接口的一个实例，可以通过绑定特殊的构造方法在这个 CSSValue 接口的这个实例来获得。 |

规范
--

该特性最初在 DOM Style Level 2 中定义，但从那时起已从标准化工作中移除。

它已被现代、不兼容的 CSS 类型对象模型 API (en-US) 取代，该 API 已被标准化。

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

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

参见
--

* `CSSPrimitiveValue` (en-US)
* `CSSValueList`


CompressionStream - Web API 接口参考

CompressionStream
=================

Compression Streams API 的 **`CompressionStream`** 接口是一个用于压缩数据流的 API。

构造函数
----

`CompressionStream()`

创建新的 `CompressionStream`。

实例属性
----

`CompressionStream.readable`

返回由此对象控制的 `ReadableStream` 实例。

`CompressionStream.writable`

返回由此对象控制的 `WritableStream` 实例。

示例
--

在该示例中，使用 gzip 对流进行压缩。

```js
const compressedReadableStream = inputReadableStream.pipeThrough(
  new CompressionStream("gzip"),
);
```

规范
--

| Specification |
| --- |
| Compression Streams # compression-stream |

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

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


NetworkInformation - Web API 接口参考

NetworkInformation
==================

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

网络信息 API 的 **`NetworkInformation`** 接口提供有关设备正在使用的与网络进行通信的连接的信息，并提供了在连接类型发生变化时通知脚本的方法。`NetworkInformation` 接口不能被实例化，而需要通过 `Navigator` 的 `connection` 属性进行访问。

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

EventTarget

NetworkInformation实例属性
----

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

`NetworkInformation.downlink` 只读
实验性

返回以每秒兆比特为单位的有效带宽估计，四舍五入到最接近的 25 千比特每秒的倍数。

`NetworkInformation.downlinkMax` (en-US) 只读
实验性

返回底层连接技术的最大下行速度，以每秒兆比特（Mbps）为单位。

`NetworkInformation.effectiveType` (en-US) 只读
实验性

返回连接的有效类型（意思是“slow-2g”、“2g”、“3g”或“4g”中的一个）。此值是使用最近观察到的往返时间和下行链路值的组合来确定的。

`NetworkInformation.rtt` 只读
实验性

返回当前连接的有效往返时间估计，四舍五入到最接近的 25 毫秒的倍数。

`NetworkInformation.saveData` 只读
实验性

如果用户在用户代理上设置了减少数据使用的选项，则返回 `true`。

`NetworkInformation.type` (en-US) 只读
实验性

返回设备用于网络通信的连接类型。它会是以下值之一：

* `bluetooth`
* `cellular`
* `ethernet`
* `none`
* `wifi`
* `wimax`
* `other`
* `unknown`

实例方法
----

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

事件
--

`change` (en-US)
实验性

在连接信息发生变化时触发的事件。

规范
--

| Specification |
| --- |
| Network Information API # networkinformation-interface |

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

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

参见
--

* 在线和离线事件 (en-US)


DOMRectReadOnly - Web API 接口参考

DOMRectReadOnly
===============

**`DOMRectReadOnly`** 接口通过详细列出 `DOMRect` 所使用的标准属性来定义一个属性不可变的矩形。

构造函数
----

`DOMRectReadOnly()` (en-US)

用来创建新的 `DOMRectReadOnly` 对象，但请注意，该构造函数不能由第三方 JavaScript 调用：这样做将返回“Illegal constructor”类型错误。

属性
--

`DOMRectReadOnly.x` (en-US) 只读

`DOMRect` 原点的 x 坐标。

`DOMRectReadOnly.y` (en-US) 只读

`DOMRect` 原点的 y 坐标。

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

`DOMRect` 的宽度。

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

`DOMRect` 的高度。

`DOMRectReadOnly.top` (en-US) 只读

返回 `DOMRect` 的顶部坐标值（通常与 `y` 相同）。

`DOMRectReadOnly.right` (en-US) 只读

返回 `DOMRect` 的右坐标值（通常与 `x + width` 相同）。

`DOMRectReadOnly.bottom` (en-US) 只读

返回 `DOMRect` 的底部坐标值（通常与 `y + height` 相同）。

`DOMRectReadOnly.left` (en-US) 只读

返回 `DOMRect` 的左坐标值（通常与 `x` 相同）。

静态方法
----

`DOMRectReadOnly.fromRect()` (en-US)

使用指定的位置和尺寸创建一个新的 `DOMRect` 对象。

规范
--

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

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

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

其他
--

* `DOMPoint`


WebGLQuery - Web API 接口参考

WebGLQuery
==========

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

**`WebGLQuery`** 接口是 WebGL 2 API 的一部分，并且提供几种异步查询信息的方法。缺省情况下，遮蔽查询和图元查询是可用的。

另一种查询是分离定时器查询，它可以允许你测量 GPU 的性能和能力。仅当存在 `EXT_disjoint_timer_query` (en-US) 扩展时分离定时器查询才是可用的。

使用 `WebGLQuery` 对象时，`WebGL2RenderingContext` 的下列方法是有用的：

* `WebGL2RenderingContext.createQuery()` (en-US)
* `WebGL2RenderingContext.deleteQuery()` (en-US)
* `WebGL2RenderingContext.isQuery()` (en-US)
* `WebGL2RenderingContext.beginQuery()`
* `WebGL2RenderingContext.endQuery()` (en-US)
* `WebGL2RenderingContext.getQuery()` (en-US)
* `WebGL2RenderingContext.getQueryParameter()` (en-US)
示例
--

### 创建一个 `WebGLQuery` 对象

在本例中，`gl` 必须是 `WebGL2RenderingContext`. `WebGLQuery` 对象在 WebGL 1 中是不可用的。

```js
var query = gl.createQuery();
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.2 |

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

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

参见
--

* `EXT_disjoint_timer_query` (en-US)


FontData - Web API 接口参考

FontData
========

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

Local Font Access API 的 **`FontData`** 接口表示单个本地字体。

实例属性
----

`FontData.family` 只读
实验性

返回字体的字体族。

`FontData.fullName` 只读
实验性

返回字体的全名。

`FontData.postscriptName` 只读
实验性

返回字体的 PostScript 名称。

`FontData.style` 只读
实验性

返回字体的样式。

实例方法
----

`FontData.blob()`
实验性

返回一个会兑现包含底层字体文件的原始字节的 `Blob` 的 `Promise`。

示例
--

有关实时演示，请参阅字体选择演示。

### 字体枚举

以下代码片段将查询所有可用的字体并打印元数据。例如，这可以用于填充字体选择器控件。

```js
async function logFontData() {
  try {
    const availableFonts = await window.queryLocalFonts();
    for (const fontData of availableFonts) {
      console.log(fontData.postscriptName);
      console.log(fontData.fullName);
      console.log(fontData.family);
      console.log(fontData.style);
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

### 访问底层数据

`blob()` 方法提供对底层 SFNT 数据的访问——这是一种可以包含其他字体格式的字体文件格式，例如 PostScript、TrueType、OpenType 或 Web 开放字体格式（WOFF）。

```js
async function computeOutlineFormat() {
  try {
    const availableFonts = await window.queryLocalFonts({
      postscriptNames: ["ComicSansMS"],
    });
    for (const fontData of availableFonts) {
      // `blob()` 方法返回一个包含有效且完整的 SFNT 包装字体数据的 Blob。
      const sfnt = await fontData.blob();
      // 仅裁剪出我们需要的字节部分：前 4 个字节是 SFNT 版本信息。
      // 规范：https://learn.microsoft.com/zh-cn/typography/opentype/spec/otff#organization-of-an-opentype-font
      const sfntVersion = await sfnt.slice(0, 4).text();

      let outlineFormat = "UNKNOWN";
      switch (sfntVersion) {
        case "\x00\x01\x00\x00":
        case "true":
        case "typ1":
          outlineFormat = "truetype";
          break;
        case "OTTO":
          outlineFormat = "cff";
          break;
      }
      console.log("矢量字体格式：", outlineFormat);
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

规范
--

| Specification |
| --- |
| Local Font Access # fontdata-interface |

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

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

参见
--

* 使用带有本地字体的高级排版
* `@font-face`


文件 API - Web API 接口参考

文件 API
======

概念和基本使用
-------

文件 API 使得 web 应用可以访问文件和其中的内容。

当用户提供文件时，Web 应用可以通过使用文件 `<input>` 元素或拖放来访问它们。

以这种方式提供的文件集被表示为 `FileList` 对象，这使得 web 应用能够检索单个 `File` 对象。反过来，`File` 对象提供对元数据的访问，如文件的名称、大小、类型和最后修改日期。

可以将 `File` 对象传递给 `FileReader` 对象以访问文件的内容。`FileReader` 接口是异步的，`FileReaderSync` 接口提供了同步版本，但仅在 web worker 中可用。

接口
--

`Blob`

Blob 代表“二进制大对象”（类似于文件的不可变的原始数据对象）；`Blob` 可以作为文本或二进制数据被读取，或者转换为 `ReadableStream`，其方法可以用来处理数据。

`File`

提供文件的信息并允许网页中的 JavaScript 代码访问其中的内容。

`FileList`

由 HTML `<input>` 元素的 `files` 属性返回；这让你可以访问用 `<input type="file">` 元素选择的文件列表。当使用拖放 API 时，它也被用于放入网页内容的文件列表；关于这种用法的细节，请参见 `DataTransfer` 对象。

`FileReader`

使 web 应用能够异步读取存储在用户计算机上的文件（或原始数据缓冲区）的内容，使用 `File` 或 `Blob` 对象来指定要读取的文件或数据。

`FileReaderSync`

使 web 应用能够同步读取存储在用户计算机上的文件（或原始数据缓冲区）的内容，使用 `File` 或 `Blob` 对象来指定要读取的文件或数据。

### 对其他接口的扩展

`URL.createObjectURL()`

创建一个可用于获取 `File` 或 `Blob` 对象的 URL。

`URL.revokeObjectURL()`

释放先前通过调用 `URL.createObjectURL()` 创建的现有对象 URL。

示例
--

### 读取文件

在这个例子中，我们提供了一个文件 `<input>` 元素，当用户选择一个文件时，我们把选择的第一个文件的内容作为文本读取，并把结果显示在 `<div>` 元素中。

#### HTML

```html
<input type="file" />
<div class="output"></div>
```

#### CSS

```css
.output {
  overflow: scroll;
  margin: 1rem 0;
  height: 200px;
}
```

#### JavaScript

```js
const fileInput = document.querySelector("input[type=file]");
const output = document.querySelector(".output");

fileInput.addEventListener("change", () => {
  const [file] = fileInput.files;
  if (file) {
    const reader = new FileReader();
    reader.addEventListener("load", () => {
      output.innerText = reader.result;
    });
    reader.readAsText(file);
  }
});
```

### 运行结果

规范
--

| Specification |
| --- |
| File API  |

参见
--

* `<input type="file">`：文件 input 元素
* `DataTransfer` 接口


Clients - Web API 接口参考

Clients
=======

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

`Clients` 接口提供对 `Client` 对象的访问。通过在 service worker (en-US) 中使用 ``self`.clients` 访问它。

方法
--

`Clients.get()`

返回一个匹配给定 `id` 的 `Client` 的 `Promise` .

`Clients.matchAll()`

返回一个 `Client` 对象数组的 `Promise` . options 参数允许你控制返回的 clients 类型。

`Clients.openWindow()`

打开给定 URL 的新浏览器窗口，并返回新 `WindowClient` (en-US) a 的 `Promise` .

`Clients.claim()`

允许一个激活的 service worker 将自己设置为其`scope` (en-US) 内所有 clients 的 `controller` .

示例
--

下面示例显示一个已有的聊天窗口，或者当用户点击通知时创建新的窗口。

```js
addEventListener("notificationclick", (event) => {
  event.waitUntil(
    (async function () {
      const allClients = await clients.matchAll({
        includeUncontrolled: true,
      });

      let chatClient;

      // Let's see if we already have a chat window open:
      for (const client of allClients) {
        const url = new URL(client.url);

        if (url.pathname == "/chat/") {
          // Excellent, let's use it!
          client.focus();
          chatClient = client;
          break;
        }
      }

      // If we didn't find an existing chat window,
      // open a new one:
      if (!chatClient) {
        chatClient = await clients.openWindow("/chat/");
      }

      // Message the client:
      chatClient.postMessage("New chat messages!");
    })(),
  );
});
```

规范
--

| Specification |
| --- |
| Service Workers # clients-interface |

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

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

See also
--------

* Using Service Workers (en-US)
* Is ServiceWorker ready?
* `Promise`


OffscreenCanvas - Web API 接口参考

OffscreenCanvas
===============

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

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

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

**`OffscreenCanvas`** 提供了一个可以脱离屏幕渲染的 canvas 对象。它在窗口环境和web worker环境均有效。

构造函数
----

`OffscreenCanvas()`

`OffscreenCanvas` 构造函数。创建一个新的 `OffscreenCanvas` 对象。

属性
--

`OffscreenCanvas.height`

offscreen canvas 对象的高度。

`OffscreenCanvas.width` (en-US)

offscreen canvas 对象的宽度。

方法
--

`OffscreenCanvas.getContext()` (en-US)

为 offscreen canvas 对象返回一个渲染画布。

`OffscreenCanvas.toBlob()` (en-US)

创建一个代表 canvas 中的图像的`Blob`对象。

`OffscreenCanvas.transferToImageBitmap()`

从 `OffscreenCanvas` 最近渲染的图像创建一个 `ImageBitmap` 对象。

例子
--

### 同步显示 `OffscreenCanvas` 中的帧

一种方式是使用`OffscreenCanvas` API，也就是用已经包含`OffscreenCanvas`对象的`RenderingContext` 来生成新的帧。每次一个新的帧在画布中完成渲染，`transferToImageBitmap()` 方法都会被调用来保存最近渲染的图像。该方法返回一个`ImageBitmap`对象，该对象可以被用在各种 Web APIs 中，也可以用在下一个 canvas 中，并且不需要转换备份。

为了显示`ImageBitmap`，你可以用`ImageBitmapRenderingContext`上下文，通过一个 canvas（可见的）元素调用`canvas.getContext("bitmaprenderer")`方法来创建它。该上下文只提供用`ImageBitmap`替换 canvas 的内容的功能。调用`ImageBitmapRenderingContext.transferFromImageBitmap()` (en-US) 以前的渲染结果并且通过 OffscreenCanvas 保存`ImageBitmap`，会在 canvas 里显示`ImageBitmap`并且转换其所有权到 canvas。一个单独的 OffscreenCanvas 可以将帧转换到任意数量的其他`ImageBitmapRenderingContext`对象。

提供两个 `<canvas>` 元素

```html
<canvas id="one"></canvas> <canvas id="two"></canvas>
```

下面的代码会用 `OffscreenCanvas` 提供渲染结果，就像上面描述的一样。

```js
var one = document.getElementById("one").getContext("bitmaprenderer");
var two = document.getElementById("two").getContext("bitmaprenderer");

var offscreen = new OffscreenCanvas(256, 256);
var gl = offscreen.getContext("webgl");

// ... some drawing for the first canvas using the gl context ...

// Commit rendering to the first canvas
var bitmapOne = offscreen.transferToImageBitmap();
one.transferFromImageBitmap(bitmapOne);

// ... some more drawing for the second canvas using the gl context ...

// Commit rendering to the second canvas
var bitmapTwo = offscreen.transferToImageBitmap();
two.transferFromImageBitmap(bitmapTwo);
```

### 异步显示 `OffscreenCanvas` 生成的帧

另一种使用 `OffscreenCanvas` API 的方式，是在一个`<canvas>`元素上调用`transferControlToOffscreen()`，也可以在worker或主线程，上调用，这将从主线程的`HTMLCanvasElement`对象返回一个`OffscreenCanvas` 对象。调用`getContext()` (en-US) 会从这个 `OffscreenCanvas` 获取一个RenderingContext。

main.js (主线程代码):

```js
var htmlCanvas = document.getElementById("canvas");
var offscreen = htmlCanvas.transferControlToOffscreen();

var worker = new Worker("offscreencanvas.js");
worker.postMessage({ canvas: offscreen }, [offscreen]);
```

offscreencanvas.js (web work 代码):

```js
onmessage = function (evt) {
  var canvas = evt.data.canvas;
  var gl = canvas.getContext("webgl");

  // ... some drawing using the gl context ...

  // Push frames back to the original HTMLCanvasElement
  gl.commit();
};
```

也可以在 worker 中使用 requestAnimationFrame

```js
onmessage = function (evt) {
  const canvas = evt.data.canvas;
  const gl = canvas.getContext("webgl");

  function render(time) {
    // ... some drawing using the gl context ...
    requestAnimationFrame(render);
  }
  requestAnimationFrame(render);
};
```

规范
--

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

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

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

另请参见
----

* WebGL Off the Main Thread – Mozilla Hacks
* `CanvasRenderingContext2D`
* `ImageBitmap`
* `ImageBitmapRenderingContext`
* `HTMLCanvasElement.transferControlToOffscreen()`
* `WebGLRenderingContext.commit()`


GPUAdapter - Web API 接口参考

GPUAdapter
==========

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

WebGPU API 的 **`GPUAdapter`** 接口表示 GPU 适配器。这时，你可以请求一个 `GPUDevice`、适配器信息、特性和限制。

使用 `GPU.requestAdapter()` 方法去请求 `GPUAdapter` 对象。

实例属性
----

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

一个 `GPUSupportedFeatures` (en-US) 对象，其描述了适配器支持的额外的功能。

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

一个布尔值。如果适配器是备用适配器，则返回 `true` ；如果不是，则返回 `false`。

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

一个 `GPUSupportedLimits` (en-US) 对象，其描述了适配器支持的限制。

实例方法
----

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

返回 `Promise`，会兑现为一个 `GPUAdapterInfo` 对象，该对象包含适配器的识别信息。

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

返回 `Promise`，会兑现为一个 `GPUDevice` 对象，该对象是与 GPU 通信的主要接口。

示例
--

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  const device = await adapter.requestDevice();

  //...
}
```

规范
--

| Specification |
| --- |
| WebGPU # gpu-adapter |

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

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

参见
--

* WebGPU API


Request - Web API 接口参考

Request
=======

Fetch API 的 **`Request`** 接口用来表示资源请求。

你可以使用 `Request()` 构造函数创建一个新的 `Request` 对象，但是你更可能会遇到作为其他 API 操作结果返回的 Request 对象，比如 service worker 的 `FetchEvent.request`。

构造函数
----

`Request()`

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

实例属性
----

`Request.body` 只读

主体内容的 `ReadableStream`。

`Request.bodyUsed` 只读

存储 `true` 或 `false`，以指示请求是否仍然未被使用。

`Request.cache` 只读

包含请求的缓存模式（例如，`default`、`reload`、`no-cache`）。

`Request.credentials` 只读

包含请求的凭据（例如，`omit`、`same-origin`、`include`）。默认是 `same-origin`。

`Request.destination` (en-US) 只读

返回一个描述请求的目的字符串。这是一个字符串，指示所请求的内容类型。

`Request.headers` 只读

包含请求相关联的 `Headers` 对象。

`Request.integrity` (en-US) 只读

包含请求的子资源完整性值（例如 `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`）。

`Request.method` 只读

包含请求的方法（`GET`、`POST` 等）。

`Request.mode` 只读

包含请求的模式（例如，`cors`、`no-cors`、`same-origin`、`navigate`）。

`Request.redirect` (en-US) 只读

包含如何处理重定向的模式。它可能是 `follow`、`error` 或 `manual` 之一。

`Request.referrer` (en-US) 只读

包含请求的 referrer（例如，`client`）。

`Request.referrerPolicy` (en-US) 只读

包含请求的 referrer 策略（例如，`no-referrer`）。

`Request.signal` (en-US) 只读

返回与请求相关联的 `AbortSignal`。

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

包含请求的 URL。

实例方法
----

`Request.arrayBuffer()`

返回 promise，其兑现值为请求主体的 `ArrayBuffer` 表示形式。

`Request.blob()`

返回 promise，其兑现值为请求主体的 `Blob` 表示形式。

`Request.clone()`

创建一个当前 `Request` 对象的副本。

`Request.formData()`

返回 promise，其兑现值为请求主体的 `FormData` 表示形式。

`Request.json()`

返回 promise，其兑现值为请求主体经过 `JSON` 解析的结果。

`Request.text()`

返回 promise，其兑现值为请求主体的文本表示形式。

**备注：** 这些请求主体上的函数只能运行一次，随后的调用将出现 TypeError 错误，表明请求主体流已被使用。

示例
--

在下面的代码中，我们使用 `Request()` 构造函数创建了一个新的请求（用来请求与脚本处于同一目录下的图片），然后返回请求的一些属性：

```js
const request = new Request("https://www.mozilla.org/favicon.ico");

const url = request.url;
const method = request.method;
const credentials = request.credentials;
```

然后，通过将 `Request` 对象作为参数传递给 `fetch()` 调用来获取此请求，例如：

```js
fetch(request)
  .then((response) => response.blob())
  .then((blob) => {
    image.src = URL.createObjectURL(blob);
  });
```

在下面的代码片段中，我们使用 `Request()` 构造函数创建了一个新的请求，其中包含一些初始数据和主体内容，用于需要主体有效载荷的 API 请求：

```js
const request = new Request("https://example.com", {
  method: "POST",
  body: '{"foo": "bar"}',
});

const url = request.url;
const method = request.method;
const credentials = request.credentials;
const bodyUsed = request.bodyUsed;
```

**备注：** body 只能是一个 `Blob`、`ArrayBuffer`、`TypedArray`、`DataView`、`FormData`、`URLSearchParams`、`ReadableStream` 或 `String` 对象，也可以是一个字符串字面量，因此增加一个 JSON 对象的有效载荷则需要字符串化该对象。

然后，通过将 `Request` 对象作为参数传递给 `fetch()` 调用来获取此请求，并取得响应，例如：

```js
fetch(request)
  .then((response) => {
    if (response.status === 200) {
      return response.json();
    } else {
      throw new Error("Something went wrong on API server!");
    }
  })
  .then((response) => {
    console.debug(response);
    // …
  })
  .catch((error) => {
    console.error(error);
  });
```

规范
--

| Specification |
| --- |
| Fetch Standard # request-class |

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

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

参见
--

* ServiceWorker API
* 跨源资源共享（CORS）
* HTTP


AnimationTimeline - Web API 接口参考

AnimationTimeline
=================

Baseline 2022
-------------

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

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

Web 动画 API的`AnimationTimeline`接口表示动画的时间轴。这个接口用于定义时间轴功能（被`文档时间线` (en-US)和未来的时间轴类型所继承），但本身并不能被开发人员直接使用。无论何处当你要用`AnimationTimeline`，都应该使用`DocumentTimeline`或其他时间轴类型来实例化。

属性
--

`AnimationTimeline.currentTime` (en-US) 只读

返回此时间轴的时间值（以毫秒为单位），若此时间轴未激活则返回`null`。

规格
--

| Specification |
| --- |
| Web Animations # the-animationtimeline-interface |

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

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

参见
--

* 网页动画 API
* `DocumentTimeline` (en-US)
* `Document.timeline`


MediaStreamTrack - Web API 接口参考

MediaStreamTrack
================

摘要
--

**`MediaStreamTrack`** 接口在 User Agent 中表示一段媒体源，比如音轨或视频。

属性
--

`MediaStreamTrack.enabled` (en-US)

布尔值，为 true 时表示轨道有效，并且可以被渲染。为 false 时表示轨道失效，只能被渲染为静音或黑屏。如果该轨道连接中断，该值还是可以被改变但不会有任何效果了。

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

返回一个由浏览器产生的`DOMString`类型的 GUID 值，作为这个轨道的唯一标识值。

`MediaStreamTrack.kind` (en-US) 只读

返回一个`DOMString`类型的值。如果为“audio”表示轨道为音频轨道，为“video”则为视频轨道。如果该轨道从它的源上分离，这个值也不会改变。

`MediaStreamTrack.label` (en-US) 只读

返回一个`DOMString`类型。内容为一个用户代理指定的标签，来标识该轨道的来源，比如“internal microphone”。该字符串可以为空，并且在没有源与这个轨道连接的情况下会一直为空。当该轨道从它的源上分离时，这个值也不会改变。

`MediaStreamTrack.muted` (en-US) 只读

返回一个布尔类型的值，为 true 时表示轨道是静音，其他为 false。

`MediaStreamTrack.readonly` 只读

返回一个布尔类型的值，为 true 时表示该轨道是只读的，比如视频文件源或一个被设置为不能修改的摄像头源，或则为 false。

`MediaStreamTrack.readyState` 只读

返回枚举类型的值，表示轨道的当前状态。该枚举值为以下中的一个：

* "live"表示当前输入已经连接并且在尽力提供实时数据。在这种情况下，输出数据可以通过操作 MediaStreamTrack.enabled 属性进行开关。
* “ended”表示这个输出连接没有更多的数据了，而且也不会提供更多的数据了。

`MediaStreamTrack.remote` (en-US) 只读

返回布尔值类型，当为 true 时表示数据是通过`RTCPeerConnection`提供的，否则为 false。

### 事件处理

`MediaStreamTrack.onstarted`

这是 `started` 事件在这个对象上被触发时调用的事件处理器，这时一个新的 `MediaStreamTrack` 对象被添加到轨道源上。

`MediaStreamTrack.onmute` (en-US)

这是 `mute` 事件在这个对象被触发时调用的事件处理器，这时这个流被中断。

`MediaStreamTrack.onunmute` (en-US)

这是 `unmute` 事件在这个对象上被触发时调用的事件处理器，未实现。

`MediaStreamTrack.onoverconstrained` (en-US)

这是 `overconstrained` 事件在这个对象上被触发时调用的事件处理器，未实现。

`MediaStreamTrack.oneended`

这是 `ended` 事件在这个对象被触发时调用的事件处理器，未实现。

方法
--

`MediaStreamTrack.getConstraints()`

TBD

`MediaStreamTrack.applyConstraints()` (en-US)

TBD

`MediaStreamTrack.getSettings()` (en-US)

TBD

`MediaStreamTrack.getCapabilities()`

TBD

`MediaStreamTrack.clone()` (en-US)

TBD

`MediaStreamTrack.stop()`

停止播放轨道对应的源，源与轨道将脱离关联，同时轨道状态将设为“ended”。

规范
--

| Specification |
| --- |
| Media Capture and Streams # mediastreamtrack |

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

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

参见
--

* Using the MediaStream API (en-US)


WebGL2RenderingContext - Web API 接口参考

WebGL2RenderingContext
======================

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

**WebGL2RenderingContext** 接口在底层使用了 OpenGL ES 3.0 为 HTML 的 `<canvas>` 元素提供了绘图上下文。

要获取该接口的实例对象需要调用一个 <canvas> 标签对象的 `getContext()` 函数，并将 "webgl2" 作为参数传递：

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

**备注：** WebGL 2 是 WebGL 1 的扩展。 `WebGL2RenderingContext` 接口实现了 `WebGLRenderingContext` 接口的所有成员。有一些 WebGL 1 上下文中的方法在使用 WebGL 2 上下文的时候可以接受附加值。你可以通过 WebGL 1 的参考页了解这些信息。

这个 WebGL 教程 中提供了关于如何开始使用 WebGL 的更多信息、示例以及资源。

常量
--

请看 WebGL 常量 页面。

状态信息
----

`WebGL2RenderingContext.getIndexedParameter()` (en-US)

返回指定目标的索引值。

缓冲区
---

`WebGL2RenderingContext.copyBufferSubData()` (en-US)

将缓冲区的部分数据复制到另一个缓冲区。

`WebGL2RenderingContext.getBufferSubData()` (en-US)

从缓冲区中读取数据，然后将其写入到 `ArrayBuffer` 或 `SharedArrayBuffer` 中。

帧缓冲区
----

`WebGL2RenderingContext.blitFramebuffer()` (en-US)

将一个像素块从读取帧缓冲区传输到绘制帧缓冲区。

`WebGL2RenderingContext.framebufferTextureLayer()` (en-US)

附着一个单层的材质到帧缓冲区。

`WebGL2RenderingContext.invalidateFramebuffer()` (en-US)

使附着到缓冲区的内容失效。

`WebGL2RenderingContext.invalidateSubFramebuffer()` (en-US)

使附着到缓冲区的部分内容失效。

`WebGL2RenderingContext.readBuffer()` (en-US)

选择一个颜色缓冲作为像素的 source。

渲染缓冲区
-----

`WebGL2RenderingContext.getInternalformatParameter()` (en-US)

Returns information about implementation-dependent support for internal formats.

`WebGL2RenderingContext.renderbufferStorageMultisample()` (en-US)

Creates and initializes a renderbuffer object's data store and allows specifying the number of samples to be used.

纹理
--

`WebGL2RenderingContext.texStorage2D()` (en-US)

Specifies all levels of two-dimensional texture storage.

`WebGL2RenderingContext.texStorage3D()` (en-US)

Specifies all levels of a three-dimensional texture or two-dimensional array texture.

`WebGL2RenderingContext.texImage3D()`

Specifies a three-dimensional texture image.

`WebGL2RenderingContext.texSubImage3D()` (en-US)

Specifies a sub-rectangle of the current 3D texture.

`WebGL2RenderingContext.copyTexSubImage3D()` (en-US)

Copies pixels from the current `WebGLFramebuffer` into an existing 3D texture sub-image.

`WebGL2RenderingContext.compressedTexImage3D()` (en-US)

Specifies a three-dimensional texture image in a compressed format.

`WebGL2RenderingContext.compressedTexSubImage3D()` (en-US)

Specifies a three-dimensional sub-rectangle for a texture image in a compressed format.

程序和着色器
------

`WebGL2RenderingContext.getFragDataLocation()` (en-US)

Returns the binding of color numbers to user-defined varying out variables.

Uniforms 和 Attributes
---------------------

`WebGL2RenderingContext.uniform[1234][fiu][v]()`

指定一个 uniform 变量。

`WebGL2RenderingContext.uniformMatrix[1234][fv]()`

指定一个 uniform 矩阵变量。

`WebGL2RenderingContext.vertexAttribI[iuv]()` (en-US)

Methods specifying integer values for generic vertex attributes.

`WebGL2RenderingContext.vertexAttribIPointer()` (en-US)

Specifies integer data formats and locations of vertex attributes in a vertex attributes array.

绘图缓冲区
-----

`WebGL2RenderingContext.vertexAttribDivisor()` (en-US)

Modifies the rate at which generic vertex attributes advance when rendering multiple instances of primitives with `gl.drawArraysInstanced()` (en-US) and `gl.drawElementsInstanced()` (en-US).

`WebGL2RenderingContext.drawArraysInstanced()` (en-US)

Renders primitives from array data. In addition, it can execute multiple instances of the range of elements.

`WebGL2RenderingContext.drawElementsInstanced()` (en-US)

Renders primitives from array data. In addition, it can execute multiple instances of a set of elements.

`WebGL2RenderingContext.drawRangeElements()` (en-US)

Renders primitives from array data in a given range.

`WebGL2RenderingContext.drawBuffers()`

Specifies a list of color buffers to be drawn into.

`WebGL2RenderingContext.clearBuffer[fiuv]()` (en-US)

Clears buffers from the currently bound framebuffer.

查询对象
----

Methods for working with `WebGLQuery` objects.

`WebGL2RenderingContext.createQuery()` (en-US)

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

`WebGL2RenderingContext.deleteQuery()` (en-US)

删除一个指定的 `WebGLQuery` 对象。

`WebGL2RenderingContext.isQuery()` (en-US)

Returns `true` if a given object is a valid `WebGLQuery` object.

`WebGL2RenderingContext.beginQuery()`

开始一个异步查询。

`WebGL2RenderingContext.endQuery()` (en-US)

Marks the end of an asynchronous query.

`WebGL2RenderingContext.getQuery()` (en-US)

返回一个指定目标的 `WebGLQuery` 对象。

`WebGL2RenderingContext.getQueryParameter()` (en-US)

返回关于一个查询的信息。

采样对象
----

`WebGL2RenderingContext.createSampler()`

Creates a new `WebGLSampler` object.

`WebGL2RenderingContext.deleteSampler()` (en-US)

Deletes a given `WebGLSampler` object.

`WebGL2RenderingContext.bindSampler()` (en-US)

Binds a given `WebGLSampler` to a texture unit.

`WebGL2RenderingContext.isSampler()` (en-US)

Returns `true` if a given object is a valid `WebGLSampler` object.

`WebGL2RenderingContext.samplerParameter[if]()` (en-US)

Sets sampler parameters.

`WebGL2RenderingContext.getSamplerParameter()` (en-US)

Returns sampler parameter information.

同步对象
----

`WebGL2RenderingContext.fenceSync()` (en-US)

创建一个 `WebGLSync` (en-US) 对象并插入到 GL 命令流中。

`WebGL2RenderingContext.isSync()` (en-US)

Returns `true` if the passed object is a valid `WebGLSync` (en-US) object.

`WebGL2RenderingContext.deleteSync()` (en-US)

删除一个指定的 `WebGLSync` (en-US) 对象。

`WebGL2RenderingContext.clientWaitSync()` (en-US)

Blocks and waits for a `WebGLSync` (en-US) object to become signaled or a given timeout to be passed.

`WebGL2RenderingContext.waitSync()` (en-US)

Returns immediately, but waits on the GL server until the given `WebGLSync` (en-US) object is signaled.

`WebGL2RenderingContext.getSyncParameter()` (en-US)

根据一个 `WebGLSync` (en-US) 对象返回参数信息。

变换反馈
----

`WebGL2RenderingContext.createTransformFeedback()` (en-US)

创建并初始化 `WebGLTransformFeedback` (en-US) 对象。

`WebGL2RenderingContext.deleteTransformFeedback()` (en-US)

删除一个指定的 `WebGLTransformFeedback` (en-US) 对象。

`WebGL2RenderingContext.isTransformFeedback()` (en-US)

Returns `true` if the passed object is a valid `WebGLTransformFeedback` (en-US) object.

`WebGL2RenderingContext.bindTransformFeedback()` (en-US)

Binds a passed `WebGLTransformFeedback` (en-US) object to the current GL state.

`WebGL2RenderingContext.beginTransformFeedback()`

Starts a transform feedback operation.

`WebGL2RenderingContext.endTransformFeedback()` (en-US)

Ends a transform feedback operation.

`WebGL2RenderingContext.transformFeedbackVaryings()` (en-US)

Specifies values to record in `WebGLTransformFeedback` (en-US) buffers.

`WebGL2RenderingContext.getTransformFeedbackVarying()` (en-US)

Returns information about varying variables from `WebGLTransformFeedback` (en-US) buffers.

`WebGL2RenderingContext.pauseTransformFeedback()` (en-US)

Pauses a transform feedback operation.

`WebGL2RenderingContext.resumeTransformFeedback()` (en-US)

Resumes a transform feedback operation.

Uniform 缓冲对象
------------

`WebGL2RenderingContext.bindBufferBase()`

Binds a given `WebGLBuffer` to a given binding point (`target`) at a given `index`.

`WebGL2RenderingContext.bindBufferRange()` (en-US)

Binds a range of a given `WebGLBuffer` to a given binding point (`target`) at a given `index`.

`WebGL2RenderingContext.getUniformIndices()` (en-US)

Retrieves the indices of a number of uniforms within a `WebGLProgram`.

`WebGL2RenderingContext.getActiveUniforms()` (en-US)

Retrieves information about active uniforms within a `WebGLProgram`.

`WebGL2RenderingContext.getUniformBlockIndex()` (en-US)

Retrieves the index of a uniform block within a `WebGLProgram`.

`WebGL2RenderingContext.getActiveUniformBlockParameter()` (en-US)

Retrieves information about an active uniform block within a `WebGLProgram`.

`WebGL2RenderingContext.getActiveUniformBlockName()` (en-US)

Retrieves the name of the active uniform block at a given index within a `WebGLProgram`.

`WebGL2RenderingContext.uniformBlockBinding()` (en-US)

Assigns binding points for active uniform blocks.

顶点数组对象
------

Methods for working with `WebGLVertexArrayObject` (VAO) objects.

`WebGL2RenderingContext.createVertexArray()`

创建一个新的 `WebGLVertexArrayObject`。

`WebGL2RenderingContext.deleteVertexArray()` (en-US)

删除一个指定的 `WebGLVertexArrayObject`。

`WebGL2RenderingContext.isVertexArray()` (en-US)

如果一个指定的 `WebGLVertexArrayObject` 对象有效则返回 `true`。

`WebGL2RenderingContext.bindVertexArray()` (en-US)

绑定一个指定的 `WebGLVertexArrayObject` 到缓冲。

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7 |

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

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

相关链接
----

* `HTMLCanvasElement`
* `WebGLRenderingContext`


SharedWorker - Web API 接口参考

SharedWorker
============

**`SharedWorker`** 接口代表一种特定类型的 worker，可以从几个浏览上下文中*访问*，例如几个窗口、iframe 或其他 worker。它们实现一个不同于普通 worker 的接口，具有不同的全局作用域，`SharedWorkerGlobalScope` (en-US) 。

**备注：** 如果要使 **SharedWorker** 连接到多个不同的页面，这些页面必须是同源的（相同的协议、host 以及端口）。

构造函数
----

`SharedWorker()`

创建一个执行指定 url 脚本的共享 web worker。

属性
--

*继承自其父类 `EventTarget`，并实现 `AbstractWorker` (en-US) 中的属性。*

`AbstractWorker.onerror` (en-US)

一个 `EventListener`，当 `ErrorEvent` 类型的 `error` 冒泡到 worker 时触发。

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

返回一个 `MessagePort` 对象，该对象可以用来进行通信和对共享 worker 进行控制。

方法
--

*继承自其父类 `EventTarget`，并实现 `AbstractWorker` (en-US) 中的方法。*

示例
--

在这个基本的共享型 worker 示例 中（运行共享型 worker），我们有两个 HTML 页面，每个页面中使用一些 JavaScript 来执行简单的计算。这些脚本使用相同的 worker 文件来执行计算——每个脚本都可以访问这个 worker 文件，即使脚本所处的页面在不同的窗口下。

下面的代码展示了如何通过 `SharedWorker()` 方法来创建一个共享进程对象。

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

然后两个脚本都通过 `MessagePort` 对象来访问 worker，这个对象用`SharedWorker.port` (en-US) 属性获得。如果已经用 addEventListener 监听了 onmessage 事件，则可以使用 `start()` 方法手动启动端口：

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

当启动端口时，两个脚本都会向 worker 发送消息，然后使用 `port.postMessage()`和 `port.onmessage` 处理从 worker 返回的消息：

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

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

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

在 worker 中我们使用 `SharedWorkerGlobalScope.onconnect` (en-US) 处理程序连接到上面讨论的相同端口。可以在 `connect` (en-US) 事件的 `ports` 属性中获取到与该 worker 相关联的端口——然后我们使用 `MessagePort` `start()` 方法来启动端口，然后 `onmessage` 处理程序处理来自主线程的消息。

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

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

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

规范
--

| Specification |
| --- |
| HTML Standard # shared-workers-and-the-sharedworker-interface |

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

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

参见
--

* `Worker`


EyeDropper - Web API 接口参考

EyeDropper
==========

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

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

**`EyeDropper`** 接口表示一个拾色器工具的实例，用户可以打开并使用它从屏幕上选择颜色。

构造函数
----

`EyeDropper()`
实验性

返回一个新的 `EyeDropper` 实例。

实例方法
----

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

`EyeDropper.open()`
实验性

返回一个 Promise，该 Promise 会兑现一个可以访问所选颜色的对象。

示例
--

### 打开拾色器工具并进行颜色采样

以下示例演示如何打开拾色器工具，并等待用户选择屏幕上的像素，或按下 `Escape` 键取消拾色器模式。

#### HTML

```html
<button id="start-button">打开拾色器</button> <span id="result"></span>
```

#### JavaScript

```js
document.getElementById("start-button").addEventListener("click", () => {
  const resultElement = document.getElementById("result");

  if (!window.EyeDropper) {
    resultElement.textContent = "你的浏览器不支持 EyeDropper API";
    return;
  }

  const eyeDropper = new EyeDropper();

  eyeDropper
    .open()
    .then((result) => {
      resultElement.textContent = result.sRGBHex;
      resultElement.style.backgroundColor = result.sRGBHex;
    })
    .catch((e) => {
      resultElement.textContent = e;
    });
});
```

#### 结果

### 中止拾色器模式

以下示例演示如何打开拾色器工具，并等待用户选择屏幕上的像素或按下 `Escape` 键来取消拾色器模式。

#### HTML

```html
<button id="start-button">打开拾色器</button> <span id="result"></span>
```

#### JavaScript

```js
document.getElementById("start-button").addEventListener("click", () => {
  const resultElement = document.getElementById("result");

  if (!window.EyeDropper) {
    resultElement.textContent = "你的浏览器不支持 EyeDropper API";
    return;
  }

  const eyeDropper = new EyeDropper();
  const abortController = new AbortController();

  eyeDropper
    .open({ signal: abortController.signal })
    .then((result) => {
      resultElement.textContent = result.sRGBHex;
      resultElement.style.backgroundColor = result.sRGBHex;
    })
    .catch((e) => {
      resultElement.textContent = e;
    });

  setTimeout(() => {
    abortController.abort();
  }, 2000);
});
```

#### 结果

规范
--

| Specification |
| --- |
| EyeDropper API # eyedropper-interface |

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

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


PerformanceTiming - Web API 接口参考

PerformanceTiming
=================

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

**`PerformanceTiming`** 接口是为保持向后兼容性而保留的传统接口，并且提供了在加载和使用当前页面期间发生的各种事件的性能计时信息。

可以通过只读属性`window.performance.timing` 获得实现该接口的一个对象。

属性
--

*`PerformanceTiming` 接口不包含任何继承属性。*

`PerformanceTiming.navigationStart` 只读

是一个无符号 long long 型的毫秒数，表征了从同一个浏览器上下文的上一个文档卸载（unload）结束时的 UNIX 时间戳。如果没有上一个文档，这个值会和 `PerformanceTiming.fetchStart` 相同。

`PerformanceTiming.unloadEventStart` 只读

是一个无符号 long long 型的毫秒数，表征了`unload`事件抛出时的 UNIX 时间戳。如果没有上一个文档，或者重定向中的一个不同源，这个值会返回 `0`。

`PerformanceTiming.unloadEventEnd` 只读

是一个无符号 long long 型的毫秒数，表征了`unload`事件处理完成时的 UNIX 时间戳。如果没有上一个文档，或者重定向中的一个不同源，这个值会返回 `0`。

`PerformanceTiming.redirectStart` 只读

是一个无符号 long long 型的毫秒数，表征了第一个 HTTP 重定向开始时的 UNIX 时间戳。如果没有重定向，或者重定向中的一个不同源，这个值会返回 0。

`PerformanceTiming.redirectEnd` 只读

是一个无符号 long long 型的毫秒数，表征了最后一个 HTTP 重定向完成时（也就是说是 HTTP 响应的最后一个比特直接被收到的时间）的 UNIX 时间戳。如果没有重定向，或者重定向中的一个不同源，这个值会返回 `0`。

`PerformanceTiming.fetchStart` 只读

是一个无符号 long long 型的毫秒数，表征了浏览器准备好使用 HTTP 请求来获取（fetch）文档的 UNIX 时间戳。这个时间点会在检查任何应用缓存之前。

`PerformanceTiming.domainLookupStart` 只读

是一个无符号 long long 型的毫秒数，表征了域名查询开始的 UNIX 时间戳。如果使用了持久连接（persistent connection），或者这个信息存储到了缓存或者本地资源上，这个值将和 `PerformanceTiming.fetchStart` 一致。

`PerformanceTiming.domainLookupEnd` 只读

是一个无符号 long long 型的毫秒数，表征了域名查询结束的 UNIX 时间戳。如果使用了持久连接，或者这个信息存储到了缓存或者本地资源上，这个值将和 `PerformanceTiming.fetchStart` 一致。

`PerformanceTiming.connectStart` 只读

是一个无符号 long long 型的毫秒数，返回 HTTP 请求开始向服务器发送时的 Unix 毫秒时间戳。如果使用持久连接，则返回值等同于 fetchStart 属性的值。

`PerformanceTiming.connectEnd` 只读

是一个无符号 long long 型的毫秒数，返回浏览器与服务器之间的连接建立时的 Unix 毫秒时间戳。如果建立的是持久连接，则返回值等同于 fetchStart 属性的值。连接建立指的是所有握手和认证过程全部结束。

`PerformanceTiming.secureConnectionStart` 只读

是一个无符号 long long 型的毫秒数，返回浏览器与服务器开始安全链接的握手时的 Unix 毫秒时间戳。如果当前网页不要求安全连接，则返回 0。

`PerformanceTiming.requestStart` 只读

是一个无符号 long long 型的毫秒数，返回浏览器向服务器发出 HTTP 请求时（或开始读取本地缓存时）的 Unix 毫秒时间戳。

`PerformanceTiming.responseStart` 只读

是一个无符号 long long 型的毫秒数，返回浏览器从服务器收到（或从本地缓存读取）第一个字节时的 Unix 毫秒时间戳。如果传输层在开始请求之后失败并且连接被重开，该属性将会被数制成新的请求的相对应的发起时间。

`PerformanceTiming.responseEnd` 只读

是一个无符号 long long 型的毫秒数，返回浏览器从服务器收到（或从本地缓存读取，或从本地资源读取）最后一个字节时（如果在此之前 HTTP 连接已经关闭，则返回关闭时）的 Unix 毫秒时间戳。

`PerformanceTiming.domLoading` 只读

是一个无符号 long long 型的毫秒数，返回当前网页 DOM 结构开始解析时（即 `Document.readyState` 属性变为“loading”、相应的 `readystatechange`事件触发时）的 Unix 毫秒时间戳。

`PerformanceTiming.domInteractive` 只读

是一个无符号 long long 型的毫秒数，返回当前网页 DOM 结构结束解析、开始加载内嵌资源时（即 `Document.readyState` 属性变为“interactive”、相应的 `readystatechange` 事件触发时）的 Unix 毫秒时间戳。

`PerformanceTiming.domContentLoadedEventStart` 只读

是一个无符号 long long 型的毫秒数，返回当解析器发送 `DOMContentLoaded` 事件，即所有需要被执行的脚本已经被解析时的 Unix 毫秒时间戳。

`PerformanceTiming.domContentLoadedEventEnd` 只读

是一个无符号 long long 型的毫秒数，返回当所有需要立即执行的脚本已经被执行（不论执行顺序）时的 Unix 毫秒时间戳。

`PerformanceTiming.domComplete` 只读

是一个无符号 long long 型的毫秒数，返回当前文档解析完成，即 `Document.readyState` 变为 `'complete'` 且相对应的 `readystatechange` 被触发时的 Unix 毫秒时间戳。

`PerformanceTiming.loadEventStart` 只读

是一个无符号 long long 型的毫秒数，返回该文档下，`load` 事件被发送时的 Unix 毫秒时间戳。如果这个事件还未被发送，它的值将会是 `0`。

`PerformanceTiming.loadEventEnd` 只读

是一个无符号 long long 型的毫秒数，返回当 `load` 事件结束，即加载事件完成时的 Unix 毫秒时间戳。如果这个事件还未被发送，或者尚未完成，它的值将会是 `0`。

方法
--

**`Performance`** 接口不包含任何方法。

`PerformanceTiming.toJSON()` (en-US)
非标准

是一个 JSON 格式化工具，返回一个 JSON 对象，代表具体的 `PerformanceTiming` 对象。

规范
--

因为 Navigation Timing 规范已被弃用，此特性不再有望成为标准。请使用 `PerformanceNavigationTiming` 接口代替。

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

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

参见
--

* `Performance.timing` 属性会返回这样一个对象。


DeviceMotionEvent - Web API 接口参考

DeviceMotionEvent
=================

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

`DeviceMotionEvent` 为 web 开发者提供了关于设备的位置和方向的改变速度的信息。

**警告：** 目前，Firefox 和 Chrome 处理坐标的方式不同。使用时要多加注意。

构造函数
----

`DeviceMotionEvent.DeviceMotionEvent()`
非标准

创建一个新的 `DeviceMotionEvent`。

属性
--

`DeviceMotionEvent.acceleration` 只读

提供了设备在 X,Y,Z 轴方向上加速度的对象。加速度的单位为 m/s2。

`DeviceMotionEvent.accelerationIncludingGravity` 只读

提供了设备在 X,Y,Z 轴方向上带重力的加速度的对象。加速度的单位为 m/s2

`DeviceMotionEvent.rotationRate` 只读

提供了设备在 alpha、beta、gamma 轴方向上旋转的速率的对象。旋转速率的单位为度每秒。

`DeviceMotionEvent.interval` 只读

表示从设备获取数据的间隔时间，单位是毫秒。

示例
--

```js
window.addEventListener("devicemotion", function (event) {
  console.log(event.acceleration.x + " m/s2");
});
```

规范
--

| Specification |
| --- |
| DeviceOrientation Event Specification # devicemotion |

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

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

参见
--

* `deviceorientation`
* `DeviceOrientationEvent`
* `devicemotion`
* Detecting device orientation (en-US)
* Orientation and motion data explained


HTMLHtmlElement - Web API 接口参考

HTMLHtmlElement
===============

**`HTMLHtmlElement`** 接口是给定 HTML 文档的根节点。它继承了 `HTMLElement` 对象的属性和方法。

你可以通过读取 `document.documentElement` 属性的值来获取文档的 `HTMLHtmlElement` 对象。

属性
--

*继承 `HTMLElement`的属性。*

`HTMLHtmlElement.version`
已弃用

这是一个用于表示管理此文档的\*\*HTML 文档类型定义（DTD）\*\*版本的 `DOMString`。但此属性不应再使用，因为它不符合要求。请仅忽略它。

方法
--

*没有明确的方法；可从父项继承——`HTMLElement`。*

规范
--

| Specification |
| --- |
| HTML Standard # htmlhtmlelement |

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

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

还可以看看
-----

* 实现此接口的 HTML 元素 : `<html>`。


FileSystemSync - Web API 接口参考

FileSystemSync
==============

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

在 文件系统 API 中， `FileSystemSync` 对象表示文件系统。它有两个属性。

关于这个文档
------

这个文档最后更新与 2012 年 3 月 2 日，并且遵循 W3C 规范（工作草案），起草于 2011 年 4 月 19 日。

规范目前已废弃，没有得到大量的关注。

基本概念
----

`FileSystemSync` 对象是整个 API 的必经之路，你会大量使用它。所以一旦你获得了引用，将对象缓存在全局变量或类属性中。

属性
--

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `只读` `DOMString` | 文件系统的名称。名称在开放的文件系统列表中必须是唯一的。 |
| `root` | `只读 DirectoryEntry` | 文件系统的根目录。 |

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

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

另见
--

规范：File API: Directories and System Specification

参考： 文件系统 API

简介：文件系统 API 的基本概念