recursal/MDN huggingface dataset:
RTCPeerConnection()
===================

**`RTCPeerConnection()`** 构造函数返回一个新建的 `RTCPeerConnection` 实例，它代表了本地端机器与远端机器的一条连接。

语法
--


```js
new RTCPeerConnection()
new RTCPeerConnection(configuration)
```

### 参数

`configuration` 可选

一个对象，用于提供配置新连接的选项：

`bundlePolicy` 可选

指定当远程对等点与 SDP BUNDLE 标准不兼容时，应如何处理候选的协商。如果远程端点可以感知 BUNDLE，则在协商完成时，所有媒体轨道和数据通道都将捆绑到单个传输上，而不管使用何种策略，并且最初创建的任何多余传输都将在此时关闭。

用技术术语来说，BUNDLE 允许两个对等点之间的所有媒体流流经单个 **5 元组**；也就是说，使用相同的传输协议从一个对等点的单个 IP 和端口到另一个对等点的单个 IP 和端口。

如果假定为不平衡（`balanced`），这必须是以下字符串值之一：

`balanced`

ICE 代理最初为每一种内容类型（音频、视频、数据通道）创建一个 `RTCDtlsTransport` (en-US)。如果远程端点无法感知 BUNDLE，那么每一个 DTLS 传输用于处理一种数据类型的通信。

`max-compat`

ICE 代理最初为每个媒体轨道创建一个 `RTCDtlsTransport` (en-US)，对数据通道则创建一个单独的传输。如果远程端点无法感知 BUNDLE，那么对于所有的内容都会协商一个单独的 DTLS 传输。

`max-bundle`

ICE 代理最初仅创建一个 `RTCDtlsTransport` (en-US) 来承载所有的 `RTCPeerConnection` 的数据。如果远程端点无法感知 BUNDLE，那么仅会协商一个轨道而忽略其余的轨道。


`certificates` 可选

一个由 `RTCCertificate` (en-US) 对象组成的数组，用于连接的身份验证。如果未指定该属性，则会为每一个 `RTCPeerConnection` 实例自动创建一组证书。尽管一个给定的连接只使用一个证书，但提供多个证书可以支持多种算法，从而提高某些情况下的连接成功的机率。参见使用证书以了解更多信息。

**备注：** 此配置选项在首次指定后便不能更改；一旦设置了证书，此属性将在之后调用 `RTCPeerConnection.setConfiguration()` (en-US) 时被忽略。

`iceCandidatePoolSize` 可选

一个无符号 16 位整数，其指定了预获取的 ICE 候选池的大小。其默认值为 0（表示不会发生候选的预获取）。你可能会发现，在某些情况下，通过在尝试建立连接前允许 ICE 代理预获取 ICE 候选，可以更快地建立连接，以在调用 `RTCPeerConnection.setLocalDescription()` (en-US) 时，已可以检查连接。

**备注：** 改变 ICD 候选池的大小可能会触发 ICE 收集的开始。

`iceServers` 可选

一个由 `RTCIceServer` (en-US) 对象组成的数组，每个对象描述一个可能被 ICE 代理使用的服务器；这些通常是 STUN 或 TURN 服务器。如果未指定，则将在没有可用的 STUN 或 TURN 服务器的情况下进行连接尝试，这将连接限制为本地对等点。

`iceTransportPolicy` 可选

当前的 ICE 传输策略；如果未指定策略，则默认使用 `all` 策略，允许考虑所有的候选。可能的值有：

`"all"`

所有的 ICE 候选都会被考虑。

`"public"` 
已弃用

只有拥有公共 IP 地址的 ICE 候选才会被考虑。*在 2016 年 5 月 13 日的规范工作草案中被移除。*

`"relay"`

只有 IP 地址被中继的 ICE 候选，例如那些通过 STUN 或 TURN 服务器传递的，才会被考虑。


`peerIdentity` 可选

一个字符串，用于指定 `RTCPeerConnection` 目标对等点的标识。如果设置了该值（其默认为 `null`），则在成功验证远程对等点的身份为给定的名称之前，`RTCPeerConnection` 不会与其建立连接。

`rtcpMuxPolicy` 可选

收集 ICE 候选时使用的 RTCP mux 策略，以支持非复用的 RTCP。可能的值有：

`negotiate`

指示 ICE 代理收集 RTP (en-US) 和 RTCP (en-US) 候选。如果远程对等点支持 RTCP 复用，那么 RTCP 候选将在相应的 RTP 候选之上多路复用。否则，分别返回 RTP 和 RTCP 候选。

`require`

告诉 ICE 代理仅收集 RTP 的 ICE 候选，并在它们之上多路复用 RTCP。如果远程对等点不支持 RTCP 多路复用，则会话协商失败。这是默认值。


### 返回值

一个新建的 `RTCPeerConnection` 对象，如果指定了配置信息（`configuration`），它按照指定配置进行配置，否则，它将按照基本配置进行配置。

### 使用证书

当你希望为一个 `RTCPeerConnection` 使用自己的证书，而不是让 `RTCPeerConnection` 自动生成，你可以通过调用静态函数 `RTCPeerConnection.generateCertificate()` (en-US) 来实现。

`certificates` 属性值在首次指定后便无法更改。如果在传递到调用的 `setConfiguration()` (en-US) 函数的配置信息中包含了该属性，则该属性会被忽略。

该属性支持提供多个证书，因为即使给定的 DTLS 连接仅使用一个证书，提供多个证书也可以支持多种加密算法。`RTCPeerConnection` 的实现会根据其和远程的对等点支持的算法来选择要使用的证书，这在 DTLS 握手期间确定。

如果你不提供证书，则会自动生成新的证书。提供你自己的证书有一个明显的好处：身份密钥的连续性——如果你对后续的调用使用相同的证书，则远程对等点可以告诉你是同一个调用者。这也避免生成新密钥的成本。

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection |

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

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

参见
--

* 信令和视频通话
* WebRTC 架构概述
* WebRTC 会话的生命周期
* `RTCPeerConnection`
RTCPeerConnection.setRemoteDescription()
========================================

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

**`RTCPeerConnection.setRemoteDescription()`** 方法改变与连接相关的描述，该描述主要是描述有些关于连接的属性，例如对端使用的解码器。连接受此更改影响，并且必须能够支持旧的和新的描述。方法带三个参数，`RTCSessionDescription` 对象用于设置，然后是更改成功的回调方法，一个是更改失败的回调方法。

方法是异步的，不用等待设置完成，成功会调用成功回调方法，失败则会调用错误回调方法。

连接的 offer 通常来自于负责匹配的服务器所发送的数据。执行者应调用此方法设置远程描述，然后生成发送到对端计算机的 answer。

语法
--
```

aPromise = pc.setRemoteDescription(sessionDescription);

pc.setRemoteDescription(sessionDescription, successCallback, errorCallback);
```


*这个方法没有返回值。*

### 参数

*sessionDescription*

Is a `DOMString` is the description of the parameters to be applied to the remote session.

*successCallback*

Is a `Function` without parameter which will be called when the description has been successfully set. At this point, one can send the offer to a remote server that can forward it to a remote client

*errorCallback*

Is a `RTCPeerConnectionErrorCallback` which will be called if the description can't be set. It takes the following parameter:

* *errorInformation* which is a `DOMString` describing the reason why the description has not been set.

Example
-------


```js
var pc = new PeerConnection();
pc.setRemoteDescription(new RTCSessionDescription(offer), function () {
  pc.createAnswer(function (answer) {
    pc.setLocalDescription(answer, function () {
      // send the answer to the remote connection
    });
  });
});
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-setremotedescription |

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

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

参见
--

* WebRTC
RTCPeerConnection.iceConnectionState
====================================

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

**`RTCPeerConnection.iceConnectionState`** 是一个只读属性，用于描述连接的 ICE 连接状态，返回值为枚举类型。

语法
--
```

 var state = peerConnection.iceConnectionState;
```

### 返回值

`RTCIceConnectionState` 的返回值为下面列举中的一种：

* `"new"`: ICE 代理正在搜集地址或者等待远程候选可用。
* `"checking"`: ICE 代理已收到至少一个远程候选，并进行校验，无论此时是否有可用连接。同时可能在继续收集候选。
* `"connected"`: ICE 代理至少对每个候选发现了一个可用的连接，此时仍然会继续测试远程候选以便发现更优的连接。同时可能在继续收集候选。
* `"completed"`: ICE 代理已经发现了可用的连接，不再测试远程候选。
* `"failed"`: ICE 候选测试了所有远程候选没有发现匹配的候选。也可能有些候选中发现了一些可用连接。
* `"disconnected"`: 测试不再活跃，这可能是一个暂时的状态，可以自我恢复。
* `"closed"`: ICE 代理关闭，不再应答任何请求。
例子
--
```

var pc = new RTCPeerConnection();
var state = pc.iceConnectionState;
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-ice-connection-state |

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

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

参见
--

* WebRTC
RTCPeerConnection.onaddstream
=============================

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

当类型为 `MediaStreamEvent` 的 **`addstream`** 事件发生时，通过`RTCPeerConnection` 触发 **`RTCPeerConnection.onaddstream`** 事件处理函数。当远程媒体流`MediaStream` 添加到连接后发送事件。当`RTCPeerConnection.setRemoteDescription()` 后此事件立即被调用而不需要等待 SDP 交换完成。

语法
--
```

peerconnection.onaddstream = function;
```

### 值

* `function` 是用户自定义的一个函数，写法上不带 `()` 和任何参数，也可以是一个匿名函数，例如 `function(event) {...}`。事件处理函数通常有个 event 做参数，类型为 `MediaStreamEvent`.
示例
--


```js
pc.onaddstream = function (ev) {
  alert("onaddstream event detected!");
};
```

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

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

参见
--

* WebRTC API
* `RTCPeerConnection.addStream()` (en-US)
* `MediaStreamEvent`
RTCPeerConnection.ontrack
=========================

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

**`RTCPeerConnection.ontrack`** 属性是一个事件处理器，此属性指定了在 `RTCPeerConnection`接口上触发 `track` 事件时调用的方法。该方法接收一个 `RTCTrackEvent` (en-US) 类型的 event 对象，该 event 对象将在 `MediaStreamTrack` 被创建时或者是关联到已被添加到接收集合的 `RTCRtpReceiver` (en-US) 对象中时被发送。

语法
--
```

RTCPeerConnection.ontrack = eventHandler;
```

### 参数

将`ontrack`设置为你提供的一个输入`RTCTrackEvent` (en-US)对象用于描述新的 track 将如何使用的方法。这一信息包含了代表新 track 的`MediaStreamTrack`对象、`RTCRtpReceiver` (en-US)对象、`RTCRtpTransceiver` (en-US)对象以及一个`MediaStream`对象列表，该对象列表表示该 track 是那个媒体流的一部分。

示例
--

本示例，从这篇文章的代码和视频调用的代码中，将传入的轨迹连接到将用于显示传入`<video>`元素。


```js
pc.ontrack = function (event) {
  document.getElementById("received\_video").srcObject = event.streams[0];
  document.getElementById("hangup-button").disabled = false;
};
```


在第一行代码中，我们的`ontrack` 事件处理器获取传入的第媒体流数组中的第一个，并赋值给 video 元素的`srcobject` 。这样媒体流就和页面中的 video 元素结合起来以便于呈现给用户。第二行代码简单启用了“挂断”按钮，用户可以使用它去断开呼叫。

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # event-track |

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

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

只读属性 `RTCPeerConnection` **`peerIdentity`** ，返回`Promise` 对象，成功时返回 `RTCIdentityAssertion` (en-US) ，该结构 `DOMString` 标识了远端的 ID。这个身份标识在连接过程中将不会改变（直到连接结束）.

语法
--
```

 var identity = rtcPeerConnection.peerIdentity;
```

### Value

A JavaScript `Promise` which resolves to an `RTCIdentityAssertion` (en-US) that describes the remote peer's identity.

当验证远程的身份 ID 出错时，promise 将返回拒绝。如果目标节点身份不存在，`peerIdentity` 将被设为 一个 promise 对象，并重启验证过程（一个断言）, 直到成功或者不再想继续。

**备注：** `setRemoteDescription()` 返回的 promise 将不会成功返回，除非目标节点身份信息可用。如不可用，则`setRemoteDescription()` 将被拒绝。若无目标节点 ID，就不不需要等`setRemoteDescription()` 这个返回验证成功了。

举个栗子
----

In this example, a function, `getIdentityAssertion()`, is created which asynchronously waits for the peer's identity to be verified, then returns the identity to the caller. If an error occurs and the promise is rejected, this logs the error to the console and returns `null` to the caller.
```

let pc = new RTCPeerConnection();

/* ... */

async function getIdentityAssertion(pc) {
  try {
    const identity = await pc.peerIdentity;
    return identity;
  } catch(err) {
    console.log("Error identifying remote peer: ", err);
    return null;
  }
}
```

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

| Specification |
| --- |
| Identity for WebRTC 1.0 # dom-rtcpeerconnection-peeridentity |

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

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

See also
--------

* WebRTC API
RTCPeerConnection.connectionState
=================================

**`connectionState`** 只读属性表示了当前所有被使用的 ICE 连接的状态，其返回值为以下字符串之一：`new`、`connecting`、`connected`、`disconnected`、`failed` 或 `closed`。

该状态本质上表示所有使用的 ICE 连接（类型为 `RTCIceTransport` (en-US) 或 `RTCDtlsTransport` (en-US)）的聚合状态。

当属性值变化时，一个 `connectionstatechange` (en-US) 事件将被发送给 `RTCPeerConnection` 对象实例。

语法
--


```js
var connectionState = RTCPeerConnection.connectionState;
```

返回值
---

一个用于表示当前连接状态的字符串，为以下列出的值之一：

`new`

表示至少有一个 ICE 连接（`RTCIceTransport` (en-US) 或 `RTCDtlsTransport` (en-US) 对象）处于 `new` 状态，并且没有连接处于以下状态： `connecting`、`checking`、`failed`、`disconnected`，或者这些连接都处于 `closed` 状态。

`connecting`

表示至少有一个 ICE 连接处于正在建立连接的状态；也就是说，它们的 `iceConnectionState` 值为 `checking` 或 `connected`，并且没有连接处于 `failed` 状态。

`connected`

表示每一个 ICE 连接要么正在使用（`connected` 或 `completed` 状态），要么已被关闭（`closed` 状态）；并且，至少有一个连接处于 `connected` 或 `completed` 状态。

`disconnected`

表示至少有一个 ICE 连接处于 `disconnected` 状态，并且没有连接处于 `failed`、`connecting` 或 `checking` 状态。

`failed`

表示至少有一个 ICE 连接处于 `failed` 的状态。

`closed`

表示 `RTCPeerConnection` 已关闭。

示例
--


```js
var pc = new RTCPeerConnection(configuration);

/\* ... \*/

var connectionState = pc.connectionState;
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-connection-state |

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

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

参见
--

* WebRTC 会话的生命周期
* `RTCPeerConnection`
* `connectionstatechange` (en-US)
* WebRTC
RTCPeerConnection.getReceivers()
================================

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

**`RTCPeerConnection.getReceivers()`** 方法返回一个 `RTCRtpReceiver` (en-US) 对象的数组，每个 RTCRtpReceiver 对象代表了一个 RTP receiver。每个 RTP receiver 管理在一个 `RTCPeerConnection` 上的 `MediaStreamTrack` 的数据的接收与解码。

语法
--
```

var receivers = rtcPeerConnection.getReceivers();
```

### 返回值

一个 `RTCRtpReceiver` (en-US) 数组，一个对象就是连接上的一个轨道（track）。若连接上没有 RTP receiver，则数组为空。

规范没有定义返回的 RTCRtpReceiver 实例的顺序，所以两次调用 `getReceivers()` 返回的顺序可能是不同的。

例子
--

待定

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-getreceivers |

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

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

参见
--

* WebRTC
* `RTCRtpSender` (en-US)
RTCPeerConnection.removeStream()
================================

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

**`RTCPeerConnection.removeStream()`** 方法用来移除本地音频或视频的 `媒体流` 。如果已经发生交互，远程主机可能需要使用一个新的媒体流。

当 `signalingState` (en-US) 的值为 `"closed"` 时，将抛出`InvalidStateError` 异常。当 `signalingState` (en-US) 值为 `"stable"` 时，将触发 `RTCPeerConnection` 的 `negotiationneeded` (en-US) 事件。

语法
--
```

pc.removeStream(mediaStream);
```


*此方法没有返回值。*

### 参数

*mediaStream*

是 `MediaStream` 类型的表示要移除的媒体流

示例
--


```js
var pc, videoStream;
navigator.getUserMedia({video: true}, function(stream) {
  pc = new RTCPeerConnection();
  videoStream = stream;
  pc.addStream(stream);
}
document.getElementById("closeButton").addEventListener("click", function(event) {
  pc.removeStream(videoStream);
  pc.close();
}, false);
```

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

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

参见
--

* WebRTC
GamepadEvent()
==============

**`GamepadEvent_`** 构造函数用于创建一个新的 `GamepadEvent` 对象。

语法
--
```

var gamepadEvent = new GamepadEvent(typeArg, options)
```

### 参数

*typeArg*

一个 `DOMString` ，必须为 `gamepadconnected` 或 `gamepaddisconnected`。

*options* 可选

选项如下所示：

* `gamepad`: 一个 `Gamepad` 实例，描述了与事件相关的控制器（对象）。

规范
--

| Specification |
| --- |
| Gamepad # dom-gamepadevent-constructor |

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

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

**`GamepadEvent` interface** 的 **`GamepadEvent.gamepad`** 属性返回一个 `Gamepad` 对象，为触发 `gamepadconnected` 和`gamepaddisconnected` (en-US) 事件提供相关联控制器数据的访问。

语法
--
```

只读 属性 Gamepad gamepad;
```

示例
--

在触发的 `Window.gamepadconnected` 事件上调用 `gamepad` 属性。


```js
window.addEventListener("gamepadconnected", function (e) {
  console.log(
    "控制器已连接于 %d 位：%s. %d 个按钮，%d 个坐标方向。",
    e.gamepad.index,
    e.gamepad.id,
    e.gamepad.buttons.length,
    e.gamepad.axes.length,
  );
});
```

值
-

一个 `Gamepad` 对象。

规范
--

| Specification |
| --- |
| Gamepad # dom-gamepadevent-gamepad |

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

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

参见
--

使用 Gamepad API
FileSystemDirectoryHandle：resolve() 方法
======================================

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

`FileSystemDirectoryHandle` 接口的 **`resolve()`** 方法返回一个 `Promise` 对象，会兑现一个包含从父目录前往指定子条目中间的目录的名称的数组。数组的最后一项是子条目的名称。

语法
--


```js
resolve(possibleDescendant)
```

### 参数

`possibleDescendant`

要返回其相对路径的 `FileSystemHandle`。

### 返回值

一个 `Promise` 对象，会兑现一个包含字符串的数组，或者当参数 `possibleDescendant` 不是此 `FileSystemDirectoryHandle` 的后代时，兑现 `null`。

### 异常

不抛出异常。

示例
--

下面的异步函数使用 `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);
    }
  }
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-resolve |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemDirectoryHandle：entries() 方法
======================================

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

`FileSystemDirectoryHandle` 接口的 **`entries()`** 方法返回一个异步迭代器，用于迭代调用此方法的 `FileSystemDirectoryHandle` 中的条目的键值对。键值对是一个 `[键, 值]` 形式的数组。

语法
--


```js
entries()
```

### 参数

无。

### 返回值

一个新的包含 `FileSystemDirectoryHandle` 中每个条目的键值对的异步迭代器。

示例
--

使用 `for await...of` 循环能够简化迭代过程。


```js
const dirHandle = await window.showDirectoryPicker();

for await (const [key, value] of dirHandle.entries()) {
  console.log({ key, value });
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-asynciterable |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemDirectoryHandle：keys() 方法
===================================

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

`FileSystemDirectoryHandle` 接口的 **`keys()`** 方法返回一个异步迭代器，用于迭代调用此方法的 `FileSystemDirectoryHandle` 中的条目的键。

语法
--


```js
FileSystemDirectoryHandle.keys()
```

### 参数

无。

### 返回值

一个新的包含 `FileSystemDirectoryHandle` 中每个条目的键的异步迭代器。

示例
--

使用 `for await...of` 循环能够简化迭代过程。


```js
const dirHandle = await window.showDirectoryPicker();

for await (const key of dirHandle.keys()) {
  console.log(key);
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-asynciterable |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemDirectoryHandle：values() 方法
=====================================

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

`FileSystemDirectoryHandle` 接口的 **`values()`** 方法返回一个异步迭代器，用于迭代调用此方法的 `FileSystemDirectoryHandle` 中的条目的值。

语法
--


```js
values()
```

### 参数

无。

### 返回值

一个新的包含 `FileSystemDirectoryHandle` 中每个条目的句柄的异步迭代器。

示例
--

使用 `for await...of` 循环能够简化迭代过程。


```js
const dirHandle = await window.showDirectoryPicker();

for await (const value of dirHandle.values()) {
  console.log(value);
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-asynciterable |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemDirectoryHandle：removeEntry() 方法
==========================================

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

`FileSystemDirectoryHandle` 接口的 **`removeEntry()`** 方法用于尝试将目录句柄内名为指定名称的文件或目录移除。

语法
--


```js
removeEntry(name)
removeEntry(name, options)
```

### 参数

`name`

一个字符串，表示你想要移除的条目的 `FileSystemHandle.name`。

`options` 可选

一个包含以下选项的可选对象：

`recursive`

布尔值，默认为 `false`。当设为 `true` 时，条目将会被递归移除。


### 返回值

一个 `Promise` 对象，兑现 `undefined`。

### 异常

`TypeError`

如果 `name` 不是一个合法的字符串或者包含不允许出现在文件系统中的字符时，抛出此异常。

`NotAllowedError` `DOMException`

如果 `PermissionStatus` (en-US) 不为“granted”则抛出此异常。

`InvalidModificationError` `DOMException`

如果 `recursive` 被设为 `false`，而对应的条目又有子条目时，抛出此异常。

`NotFoundError` `DOMException`

如果没有找到指定名称的条目，抛出此异常。

示例
--

下面的示例演示移除目录句柄内的一个条目。


```js
const entryName = "entryToRemove";

// 假设我们有一个目录句柄：'currentDirHandle'
currentDirHandle.removeEntry(entryName).then(() => {
  // 成功移除后要运行的代码
});
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-removeentry |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemDirectoryHandle：getDirectoryHandle() 方法
=================================================

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

`FileSystemDirectoryHandle` 接口的 **`getDirectoryHandle()`** 方法返回一个位于调用此方法的目录句柄内带有指定名称的子目录的 `FileSystemDirectoryHandle`。

语法
--


```js
getDirectoryHandle(name)
getDirectoryHandle(name, options)
```

### 参数

`name`

一个字符串，表示你想要获得的子目录的 `FileSystemHandle.name`。

`options` 可选

包含要获得的子目录的选项的可选对象，选项如下：

`create`

布尔值，默认为 `false`。当设为 `true` 时，如果没有找到对应的目录，将会创建一个指定名称的目录并将其返回。


### 返回值

一个 `Promise` 对象，会兑现一个 `FileSystemDirectoryHandle`。

### 异常

`NotAllowedError` `DOMException`

如果 `PermissionStatus` (en-US) 不为“granted”则抛出此异常。

`TypeMismatchError` `DOMException`

如果将返回的条目是个文件而不是目录时会抛出此异常。

`NotFoundError` `DOMException`

如果目录不存在，并且 `create` 选项被设为 `false` 时会抛出此异常。

示例
--

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


```js
const dirName = "directoryToGetName";

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

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-getdirectoryhandle |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemDirectoryHandle：getFileHandle() 方法
============================================

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

`FileSystemDirectoryHandle` 接口的 **`getFileHandle()`** 方法返回一个位于调用此方法的目录句柄内带有指定名称的文件的 `FileSystemFileHandle`。

语法
--


```js
getFileHandle(name)
getFileHandle(name, options)
```

### 参数

`name`

一个字符串，表示你想要获得的文件的 `FileSystemHandle.name`。

`options` 可选

包含以下属性的对象：

`create`

布尔值，默认为 `false`。当设为 `true` 时，如果没有找到对应的文件，将会创建一个指定名称的文件并将其返回。


### 返回值

一个 `Promise` 对象，会兑现一个 `FileSystemFileHandle`。

### 异常

`NotAllowedError` `DOMException`

如果 `PermissionStatus` (en-US) 不为“granted”则抛出此异常。

`TypeError`

如果指定的名称不是一个合法的字符串或者包含会干扰本地文件系统的字符则抛出此异常。

`TypeMismatchError` `DOMException`

如果指定名称的条目是个目录而不是文件，则抛出此异常。

`NotFoundError` `DOMException`

如果文件不存在，并且 `create` 选项被设为 `false` 时会抛出此异常。

示例
--

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


```js
const fileName = "fileToGetName";

// 假设我们有一个目录句柄：'currentDirHandle'
const fileHandle = currentDirHandle.getFileHandle(fileName, { create: true });
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle-getfilehandle |

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

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

参见
--

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

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

`AmbientLightSensor` 接口的 read-only 属性 **reading** 返回一个访问 `AmbientLightSensorReading` (en-US) 的接口，包含当前的光亮级别。

语法
--
```

var sensorReading = AmbientLightLevel.reading
```

### 返回值

`AmbientLightSensorReading` (en-US) 接口。

用例
--


```js
// TBD
```

规范
--

| Specification |
| --- |
| Ambient Light Sensor # ambient-light-sensor-reading-attribute |

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

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

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

通过 **`AmbinentLightSensor()`** 构造函数可以创建一个 `AmbientLightSensor` 的实例。

语法
--
```

var ambientLightSensor = new AmbientLightSensor(options)
```

### 参数

*options* 可选

以下是设置属性：

* `frequency`: TBD

规范
--

| Specification |
| --- |
| Ambient Light Sensor # dom-ambientlightsensor-ambientlightsensor |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
BarcodeDetector：BarcodeDetector() 构造方法
======================================

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

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

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

**`BarcodeDetector()`** 构造函数创建一个新的用于检测图像中条形码和二维码的 `BarcodeDetector` 对象。

语法
--


```js
new BarcodeDetector()
new BarcodeDetector(options)
```

### 参数

`options` 可选

包含一系列 `BarcodeFormats` 的选项对象，用于在后续调用 `detect()` 中搜索。选项有：

`formats` 可选

一个表示条形码格式的字符串 `Array`。如果未提供，调用 `detect()` 方法时将搜索所有支持的格式。因此，出于性能原因，建议限制为具体的格式。要查看支持格式的完整列表，请参阅受支持的条形码格式类型。


### 异常

`TypeError`

如果指定了 `formats` 参数并且该参数为空数组或包含 `unknown`，则抛出此异常。

示例
--

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


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

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

规范
--

| Specification |
| --- |
| Accelerated Shape Detection in Images # dom-barcodedetector-barcodedetector |

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

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