recursal/MDN huggingface dataset:
WebVR API
=========

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

WebVR API 能为虚拟现实设备的渲染提供支持——例如像 Oculus Rift 或者 HTC Vive 这样的头戴式设备与 Web 应用的连接。它能让开发者将位置和动作信息转换成 3D 场景中的运动。基于这项技术能产生很多有趣的应用，比如虚拟的产品展示，可交互的培训课程，以及超强沉浸感的第一人称游戏。

概念及使用方法
-------

![Sketch of a person in a chair with wearing goggles labelled "Head mounted display (HMD)" facing a monitor with a webcam labelled "Position sensor"](/zh-CN/docs/Web/API/WebVR_API/hw-setup.png)

连接到电脑的所有 VR 设备都将由 `Navigator.getVRDevices()` (en-US) 方法返回。这个方法将返回一个包含了所有已连接设备的对象数组，每个设备对应一个对象，该对象继承自 `VRDevice` (en-US)——通常一个头显将包含两个设备——头显自身由 `HMDVRDevice` (en-US) 表示，和一个跟踪头部位置的位置捕捉传感器，由 `PositionSensorVRDevice` (en-US) 表示。

`PositionSensorVRDevice` (en-US) 对象有一个 `getState()` (en-US) 方法，该方法返回一个`VRPositionState` (en-US) 对象——这个对象代表位置传感器在指定时刻的状态，包含了一些十分有用的信息，例如速度、加速度以及运动方向，可用于根据头部运动刷新画面显示。

`HMDVRDevice.getEyeParameters()` (en-US) 方法返回一个 `VREyeParameters` (en-US) 对象，可用于获取显示区域的信息——头显可以看到多少画面。 `VREyeParameters.currentFieldOfView` (en-US) 返回一个 `VRFieldOfView` (en-US) 对象，该对象包含了 4 个角度信息来描述当前的显示区域。你可以用 `HMDVRDevice.setFieldOfView()` (en-US) 来改变当前的显示区域。

**备注：** 要了解更多关于如何在你的应用程序中使用这些接口，请阅读文章使用 WebVR API。要学习更多关于 VR 技术背后的基础概念，请阅读文章 WebVR 概念。

### 使用控制器：将 WebVR 与 Gamepad API 相结合

Many WebVR hardware setups feature controllers that go along with the headset. These can be used in WebVR apps via the Gamepad API, and specifically the Gamepad Extensions API that adds API features for accessing controller pose, haptic actuators (en-US), and more.

**备注：** Our Using VR controllers with WebVR (en-US) article explains the basics of how to use VR controllers with WebVR apps.

WebVR 接口
--------

`Navigator.getVRDevices` (en-US)

返回一个会兑现连接到电脑的 VR 设备数组的 promise。

`VRDevice` (en-US)

返回一个包括了 VR 设备 IDs，描述等信息的类。由 `HMDVRDevice` 和 `PositionSensorVRDevice` 继承。

`HMDVRDevice` (en-US)

头戴设备。提供设备双眼、当前视野（FOV）信息。

`PositionSensorVRDevice` (en-US)

VR 设备的位置传感器。获取位置、方向信息。

`VRPose`

根据一个时间戳返回包括（方向、位置、速度、加速度）的状态。

`VREyeParameters` (en-US)

给双眼提供正确渲染场景的所有信息，包括 FOV。

`VRFieldOfView` (en-US)

返回以视窗的中心点为基点的，表示 FOV 的 4 个角度值（downDegrees, leftDegrees, rightDegrees, upDegrees）。

`VRFieldOfViewReadOnly`

定义一个 FOV 必须的角度属性。由 `VRFieldOfView` 继承。

示例
--

你可以在 Github 的协议中找到一系列的案例：

* mdn/webvr-tests：简单构建的演示用于阐明基本的使用方法。
* MozVR team：更多复杂的演示，关于 WebVR 特别的资源，以及更多的内容！
规范
--

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

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

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

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

参见
--

* 建立 WebVR 的运行环境
* WebVR 的相关概念
* 怎样使用 WebVR API
* Console Game on Web——一系列有趣的概念游戏演示的集合，其中有些包括了 WebVR。
* threejs-vr-boilerplate——一个当你编写 WebVR APP 时，非常有用的用于开始编程的模板。
* Oculus Rift 主页
StyleSheet
==========

表示一个实现`StyleSheet`接口的对象样式表。CSS 样式表将进一步实现更专业的 `CSSStyleSheet` 接口。

属性
--

`StyleSheet.disabled`

返回`Boolean` (en-US)表示当前样式表是否可用。

`StyleSheet.href` 只读 

返回 `DOMString` 表示样式表的位置。

`StyleSheet.media` 只读 

返回 `MediaList` 表示样式的预期目标媒体

`StyleSheet.ownerNode` (en-US) 只读 

返回 `Node` 将此样式表与当前文档相关联。

`StyleSheet.parentStyleSheet` (en-US) 只读 

返回 `StyleSheet` 如果有的话; 返回 `null` 如果没有。

`StyleSheet.title` 只读 

返回 `DOMString` 表示当前样式表的顾问标题。

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

返回 `DOMString` 表示当前样式表的语言

规范
--

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

参见
--

* `CSSStyleSheet`
AudioParam
==========

Web Audio API 的 `AudioParam` 接口代表音频相关的参数，通常是 `AudioNode`（例如 `GainNode.gain`）的参数。

`AudioParam` 可以用于安排在特定时间并遵循特定模式设置一个具体的值或者数值的变化过程。

每个 `AudioParam` 都有一个初始化为空的事件列表，用于定义值在何时发生的具体变化。当该列表不为空时，将忽略使用 `AudioParam.value` 属性进行的更改。该事件列表使我们能够使用任意基于时间线的自动化曲线来安排必须在非常精确的时间发生的更改。使用的时间定义于 `AudioContext.currentTime` 中。

AudioParam 类型
-------------

有两种类型的 `AudioParam`：*a-rate* 和 *k-rate* 参数。规范中为每个 `AudioNode` 都定义了其参数为 *a-rate* 还是 *k-rate*。

### a-rate

*a-rate* `AudioParam` 获取音频信号的每个采样帧的当前音频参数值。

### k-rate

*k-rate* `AudioParam` 对待处理的整个块使用相同的初始音频参数值，即 128 个采样帧。换句话说，其将相同的值应用于节点处理的音频中的每一帧。

实例属性
----

`AudioParam.defaultValue` (en-US) 只读 

代表被具体的 `AudioNode` 创建的 `AudioParam` 的属性的初始值。

`AudioParam.maxValue` (en-US) 只读 

代表参数有效范围的最大可能值。

`AudioParam.minValue` (en-US) 只读 

代表参数有效范围的最小可能值。

`AudioParam.value` (en-US)

代表参数的当前浮点数音量值；初始化设定为 `defaultValue` (en-US) 的值。

实例方法
----

`AudioParam.setValueAtTime()` (en-US)

参照 `AudioContext.currentTime`，安排在一个确切的时间，立即更改 `AudioParam` 的值。新的值由 `value` 参数给定。

`AudioParam.linearRampToValueAtTime()` (en-US)

调整 `AudioParam` 的值，使其逐渐按线性变化。这个变化会从*上一个*事件指定的事件开始，跟随一个线性变化到参数给定的新值，并在 `endTime` 参数给定的时间到达新值。

`AudioParam.exponentialRampToValueAtTime()` (en-US)

调整 `AudioParam` 的值，使其逐渐按指数变化。这个变化会从*上一个*事件指定的事件开始，跟随一个指数变化到参数给定的新值，并在 `endTime` 参数给定的时间到达新值。

`AudioParam.setTargetAtTime()` (en-US)

安排逐渐改变 `AudioParam` 的值的开始时间。这个变化将从 `startTime` 指定的时间开始，并且以指定的方式向目标参数给定的值改变。指数衰减速率由 `timeConstant` 参数定义，以秒为单位。

`AudioParam.setValueCurveAtTime()` (en-US)

调整 `AudioParam` 的值以跟随一组缩放到适应给定间隔的浮点数值，该间隔从给定的起始时间开始，持续一段给定的时长。

`AudioParam.cancelScheduledValues()` (en-US)

取消所有安排的对 `AudioParam` 的未来的改变。

`AudioParam.cancelAndHoldAtTime()` (en-US)

取消所有安排的对 `AudioParam` 的未来的改变，但是保持给定时间的值，直到将来的使用其他方法产生改变。

示例
--

首先，基础示例展示了如何设置 `GainNode` 的 `gain` 值。`gain` 是 *a-rate* `AudioParam` 的一个示例，因为该值可以针对音频的每个样本帧进行不同的设置。


```js
const audioCtx = new AudioContext();

const gainNode = audioCtx.createGain();
gainNode.gain.value = 0;
```


下一个示例展示了如何修改 `DynamicsCompressorNode` 的一些参数值。这是 *k-rate* `AudioParam` 的一个示例，因为它是一次可以为整个音频块设置的值。


```js
const compressor = audioCtx.createDynamicsCompressor();
compressor.threshold.setValueAtTime(-50, audioCtx.currentTime);
compressor.knee.setValueAtTime(40, audioCtx.currentTime);
compressor.ratio.setValueAtTime(12, audioCtx.currentTime);
compressor.attack.setValueAtTime(0, audioCtx.currentTime);
compressor.release.setValueAtTime(0.25, audioCtx.currentTime);
```

规范
--

| Specification |
| --- |
| Web Audio API # AudioParam |

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

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

参见
--

* 使用 Web Audio API
TextDecoderStream
=================

Encoding API 接口的 **`TextDecoderStream`** 方法将二进制编码（如 UTF-8 等）的文本流转换为字符串流。它与 `TextDecoder` 的流形式等价。

构造函数
----

`TextDecoderStream()`

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

属性
--

`TextDecoderStream.encoding`只读 

一种编码。

`TextDecoderStream.fatal`只读 

一个 `boolean`，表示错误是否是致命的。

`TextDecoderStream.ignoreBOM`只读 

一个 `boolean`，表示是否忽略字节顺序标记。

`TextDecoderStream.readable`只读 

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

`TextDecoderStream.writable`只读 

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

示例
--

* 流式传输结构化数据和 HTML 示例
* 一个使用 `TextDecoderStream` 流式处理 fetch 请求的示例。
规范
--

| Specification |
| --- |
| Encoding Standard # interface-textdecoderstream |

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

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

参见
--

* `TextEncoderStream`
* Streams API 概念
* Experimenting with the Streams API
页面可见性 API
=========

页面可见性 API 提供了一些事件，你可以通过查看这些事件来了解文档何时变为可见或隐藏，还提供了一些功能来查看页面的当前可见性状态。

通过让页面在文档不可见时避免执行不必要的任务，这对于节省资源和提高性能特别有用。

概念与用途
-----

当用户最小化窗口或切换到另一个标签页时，API 会发送 `visibilitychange` 事件，让监听者知道页面的状态已发生变化。你可以检测到该事件并执行某些操作或采取不同的行为。例如，如果你的 web 应用正在播放视频，当用户将标签页放到后台时，它可以暂停视频，当用户返回标签页时，它又可以恢复播放。用户不会失去在视频中的位置，视频的配乐也不会干扰新的前台标签页中的音频，用户在此期间也不会错过任何视频。

`<iframe>` 的可见性状态与父文档相同。使用 CSS 属性（如 `display: none;`）隐藏 `<iframe>` 不会触发可见性事件，也不会改变框架内文档的状态。

### 使用情景

让我们来看看页面可见性 API 的几个使用案例。

* 网站有图片轮播效果，只有在用户观看轮播的时候，才会自动展示下一张幻灯片。
* 显示信息仪表盘的应用程序不希望在页面不可见时轮询服务器进行更新。
* 页面想要检测何时正在预渲染，以便可以准确的计算页面浏览量。
* 当设备进入待机模式（用户按下电源键关闭屏幕）时，网站想要关闭设备声音。

开发人员在过去使用不完善的代理来检测这一点。例如，通过观察 window 上的 `blur` 和 `focus` 事件，可以帮助你了解页面何时不是活动页面，但这并不能告诉你，页面实际上已被用户隐藏。页面可见性 API 可解决这一问题。

**备注：** 虽然 `onblur` 和 `onfocus` 会告诉你用户是否切换了窗口，但这并不一定意味着它被隐藏了。只有当用户切换标签页或最小化包含标签页的浏览器窗口时，页面才会被隐藏。

### 制定有助于后台页面性能的策略

在页面可见性 API 之外，用户代理会采取许多策略来减轻后台或隐藏选项卡对性能的影响。这些可能包括：

* 大多数浏览器会停止向后台标签页或隐藏的 `<iframe>` 发送 `requestAnimationFrame()` 回调，以提高性能和电池寿命。
* 在后台或不活动标签页中，`setTimeout()` 等计时器会被节流，以帮助提高性能。详情请参阅延迟时间超过指定时间的原因。
* 浏览器实施基于预算的后台超时节流。现代浏览器的操作方式大同小异，具体细节如下：
    + 在 Firefox 中，后台标签页中的每个窗口都有自己的时间预算（以毫秒为单位），最大值和最小值分别为 +50 毫秒和 -150 毫秒。Chrome 浏览器与之非常相似，只是预算以秒为单位。
    + 窗口在 30 秒后会受到节流，节流延迟规则与为窗口定时器指定的规则相同（请再次参阅延迟时间超过指定时间的原因）。在 Chrome 浏览器中，该值为 10 秒。
    + 只有当预算为非负数时，才允许执行定时器任务。
    + 定时器代码一旦运行完毕，其执行时间就会从窗口的超时预算中扣除。
    + 在 Firefox 和 Chrome 浏览器中，预算以每秒 10 毫秒的速度重新生成。

某些进程不受这种节流行为的影响。在这种情况下，可以使用页面可见性 API 来减少标签页隐藏时对性能的影响。

* 正在播放音频的标签页被视为前台进程，不会被节流。
* 运行使用实时网络连接（WebSocket 和 WebRTC）的代码的标签页不会被节流，以避免关闭这些连接时超时和意外关闭。
* 为了避免超时，IndexedDB 进程也没有节流。
对其他接口的扩展
--------

### 实例属性

页面可见性 API 为 `Document` 接口添加了以下属性：

`Document.hidden` 
已弃用
 只读 

如果页面处于隐藏状态，则返回 `true`，否则返回 `false`。

`Document.visibilityState` 只读 

说明文档当前可见性状态的字符串。可能的值有：

`visible`

页面内容至少部分可见。在实践中，这意味着页面是非最小化窗口的前景选项卡。

`hidden`

页面内容对用户不可见，原因可能是文档标签页在后台或属于最小化窗口的一部分，也可能是设备屏幕关闭。


### 事件

页面可见性 API 为 `Document` 接口添加了以下事件：

`visibilitychange`

当标签页的内容变为可见或被隐藏时触发。

示例
--

### 在页面隐藏时暂停音频

该示例会在用户切换到不同标签页时暂停音频，并在用户切换回标签页时播放音频。

#### HTML


```html
<audio
 controls
 src="https://mdn.github.io/webaudio-examples/audio-basics/outfoxing.mp3"></audio>
```


#### JavaScript


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

// 处理页面可见性变化：
// - 如果页面隐藏，暂停音频
// - 如果页面显示，播放音频
document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    audio.pause();
  } else {
    audio.play();
  }
});
```


#### 结果

试着播放音频，然后切换到不同的标签页，然后再返回。

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-visibilitystate |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
地理位置 API
========

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

**地理位置 API**（Geolocation API）允许用户向 web 应用程序提供他们的位置。出于隐私考虑，报告地理位置前会先请求用户许可。

Web 扩展若期望使用 `Geolocation` 对象，则必须将 `"geolocation"` 权限添加到其清单（manifest）中。在第一次请求地理位置访问时，用户的操作系统将提示用户提供相应的权限。

概念和用法
-----

通常，要在地图上标出用户的位置或显示与用户地理位置相关的个性化信息时，我们需要在 web 应用程序中检索用户的位置信息。

地理位置 API 是通过调用 `navigator.geolocation` 来访问的；这将使得用户的浏览器请求获得用户位置数据相关的权限。如果用户授予了权限，则浏览器将使用设备上可用的最佳方式来获取此信息（例如 GPS）。

开发人员现在可用通过不同的方式访问位置信息：

* `Geolocation.getCurrentPosition()`：检索设备的当前位置。
* `Geolocation.watchPosition()`：注册一个处理函数，在设备位置发生改变时都会自动调用，并返回改变后的位置信息。

对于上述的几种方法，其回调函数最多有三个参数：

* 一个必须的成功的回调函数：如果位置检索成功，则调用该回调函数，并以 `GeolocationPosition` 对象（用于提供位置数据）作为其唯一的参数。
* 一个可选的错误回调函数：如果位置检索失败，则调用该回调函数，并以 `GeolocationPositionError` 对象（用于提供访问出错的信息）作为其唯一的参数。
* 一个可选的对象：用于提供检索位置数据的选项。

有关地理位置使用的信息，请参阅使用地理位置 API。

接口
--

`Geolocation`

该 API 的主类——包含检索用户当前的位置、监听位置变化以及清除先前设置的监听器的方法。

`GeolocationPosition`

表示用户的位置。`GeolocationPosition` 实例会在成功调用 `Geolocation` 中的方法时返回。包含了一个时间戳和一个 `GeolocationCoordinates` 对象实例。

`GeolocationCoordinates`

表示用户位置的坐标。`GeolocationCoordinates` 实例包含经纬度和其他相关的重要信息。

`GeolocationPositionError`

`GeolocationPositionError` 实例会在未能成功调用 `Geolocation` 中的方法时返回。包含了错误代码和错误消息。

`Navigator.geolocation`

API 的入口点。返回一个 `Geolocation` 对象实例，从中可以访问所有其他的功能。

示例
--

参见使用地理位置 API 以获取示例代码。

规范
--

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

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

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

### 可用性

基于 Wi-Fi 的位置信息通常由 Google 提供，但该原生的地理位置 API 可能无法在中国使用。你可用使用如百度、高德或腾讯等本地的第三方提供商。这些服务使用用户的 IP 地址或本地应用来提供增强的位置信息。

参见
--

* 使用地理位置 API
* w3.org 上的地理位置 API
* Who moved my geolocation? (Hacks blog)
ImageBitmap
===========

**`ImageBitmap`** 接口表示能够被绘制到 `<canvas>` 上的位图图像，具有低延迟的特性。运用 `createImageBitmap()` (en-US) 工厂方法模式，它可以从多种源中生成。 `ImageBitmap`提供了一种异步且高资源利用率的方式来为 WebGL 的渲染准备基础结构。

属性
--

`ImageBitmap.height` 只读 

无符号长整型数值，表示 ImageData 的 CSS 像素单位的高度。

`ImageBitmap.width` 只读 

无符号长整型数值，表示 ImageData 的 CSS 像素单位的宽度。

方法
--

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

释放 ImageBitmap 所相关联的所有图形资源。

规范
--

| Specification |
| --- |
| HTML Standard # imagebitmap |

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

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

另见
--

* `ImageBitmapFactories.createImageBitmap()` (en-US)
* `CanvasRenderingContext2D.drawImage()`
* `WebGLRenderingContext.texImage2D()`
* `OffScreenCanvas.transferToImageBitmap()`
NodeIterator
============

**`NodeIterator`** 接口表示一个遍历 DOM 子树中节点列表的成员的迭代器。节点将按照文档顺序返回。

NodeIterator 可以使用 `Document.createNodeIterator()` 方法创建，如下所示：


```js
var nodeIterator = document.createNodeIterator(root, whatToShow, filter);
```

属性
--

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

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

返回一个 `Node`，它代表创建 NodeIterator 时指定的根节点。

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

返回一个无符号长整型，它是一个由描述必须呈现的 `Node` 类型的常量构成的位掩码。不匹配的节点被跳过，但是如果相关，他们的子节点可能被包括在内。可能的值是：

| Constant | Numerical value | Description |
| --- | --- | --- |
| `NodeFilter.SHOW_ALL` | `-1` (that is the max value of `unsigned long`) | 显示所有节点。 |
| `NodeFilter.SHOW_ATTRIBUTE` 
已弃用
 | `2` | 显示属性 `Attr` 节点。只有当用一个 `Attr` 节点作为根节点来创建 `NodeIterator` 时才有意义; 在这种情况下，这意味着属性节点会出现在迭代或遍历的首位。因为属性永远不会是其他节点的子节点，当遍历整个文档树时它们不会出现。 |
| `NodeFilter.SHOW_CDATA_SECTION` 
已弃用
 | `8` | 显示`CDATASection` 节点。 |
| `NodeFilter.SHOW_COMMENT` | `128` | 显示`Comment` 节点。 |
| `NodeFilter.SHOW_DOCUMENT` | `256` | 显示`Document` 节点。 |
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `1024` | 显示`DocumentFragment`节点。 |
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `512` | 显示`DocumentType` 节点。 |
| `NodeFilter.SHOW_ELEMENT` | `1` | 显示`Element` 节点。 |
| `NodeFilter.SHOW_ENTITY` 
已弃用
 | `32` | 显示 `Entity` 节点。只有当用一个 `Entity` 节点作为它的根节点来创建一个 `NodeIterator` 时才有意义; 在这种情况下， `Entity` 节点会出现在迭代或遍历的首位。因为 `Entity` 永远不会是其他节点的子节点，当遍历整个文档树时它们不会出现。 |
| `NodeFilter.SHOW_ENTITY_REFERENCE` 
已弃用
 | `16` | 显示`EntityReference` 节点。 |
| `NodeFilter.SHOW_NOTATION` 
已弃用
 | `2048` | 显示 `Notation` 节点。只有当用一个 `Notation` 节点作为它的根节点时来创建一个 `NodeIterator` 才有意义; 在这种情况下， `Notation` 节点会出现在迭代或遍历的首位。因为 `Notation` 永远不会是其他节点的子节点，当遍历整个文档树时它们不会出现。 |
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `64` | 显示`ProcessingInstruction` (en-US) 节点。 |
| `NodeFilter.SHOW_TEXT` | `4` | 显示`Text` (en-US) 节点。 |

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

返回一个用来选择相关节点的 `NodeFilter` .

`NodeIterator.expandEntityReferences` 只读  
已弃用

Is a `Boolean` (en-US) indicating if, when discarding an `EntityReference` its whole sub-tree must be discarded at the same time.

`NodeIterator.referenceNode` (en-US) 只读  
实验性

返回当前遍历到的 `Node` .

`NodeIterator.pointerBeforeReferenceNode` (en-US) 只读  
实验性

Returns a `Boolean` (en-US) flag that indicates whether the `NodeIterator` is anchored before, the flag being `true`, or after, the flag being `false`, the anchor node.

方法
--

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

`NodeIterator.detach()` (en-US) 
已弃用

这个方法不是必需的。它现在什么也不做。之前用来告诉引擎，`NodeIterator` 已经不会再使用，现在已经不做任何事情。

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

返回前一个 `Node`，如果不存在则返回 `null`.

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

返回下一个 `Node`, 如果不存在则返回`null` .

规范
--

| Specification |
| --- |
| DOM Standard # interface-nodeiterator |

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

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

参见
--

* The creator method: `Document.createNodeIterator()`.
* Related interfaces: `NodeFilter`, `TreeWalker`.
structuredClone()
=================

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

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

* Learn more
* See full compatibility
* Report feedback
全局的 **`structuredClone()`** 方法使用结构化克隆算法将给定的值进行深拷贝。

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

语法
--


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

### 参数

`value`

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

`transfer` 可选

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

### 返回值

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

### 异常

`DataCloneError` `DOMException`

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

附注
--

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


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

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

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

### Transferring values

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

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

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


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

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


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


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

规范
--

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

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

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

参见
--

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

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

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

EventTarget

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

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

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

构造函数
----

`EventSource()`

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

实例属性
----

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

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

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

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

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

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

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

### 实例方法

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

`EventSource.close()`

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

事件
--

`error`

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

`message`

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

`open`

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

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

示例
--

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


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

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

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


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

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

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


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

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

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

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

规范
--

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

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

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

参见
--

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

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

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

实例
--

`AmbientLightSensor.AmbientLightSensor()`

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

属性
--

`AmbientLightSensor.reading`

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

### Examples


```js
// TBD
```

规范
--

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

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

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

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

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

属性
--

`TimeRanges.length` 只读 

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

方法
--

`TimeRanges.start()`

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

`TimeRanges.end()`

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

规范
--

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

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

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

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

构造函数
----

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

实例属性
----

`ReadableStreamDefaultController.desiredSize` 只读 

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

实例方法
----

`ReadableStreamDefaultController.close()`

关闭关联的流。

`ReadableStreamDefaultController.enqueue()`

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

`ReadableStreamDefaultController.error()`

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

示例
--

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

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

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


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

规范
--

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

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

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

参见
--

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

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

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

属性
--

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

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

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

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

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

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

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

构造函数
----

`TransitionEvent()` (en-US)

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

方法
--

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

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

已弃用

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

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

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

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

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

See also
--------

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