AudioContext.resume() - Web API 接口参考

AudioContext.resume()
=====================

`AudioContext` 的 `resume()` 方法，恢复之前暂停播放的音频。

如果在 `OfflineAudioContext` 上调用，会导致 `INVALID_STATE_ERR` 错误。

语法
--

```js
var audioCtx = new AudioContext();
audioCtx.resume().then(function() { ... });
```

### 结果

`Promise`成功的话返回空值，返回失败是因为 context 已经关闭了。

示例
--

下面的代码是 AudioContext states demo (see it running live) 的一部分。当点击暂停／恢复按钮的时候，需要`AudioContext.state`做判断：如果是运行状态，调用`suspend()`，如果是暂停状态，调用`resume()。每次点击事件成功后，按钮的文字也会随着变成对应的状态`。

```js
susresBtn.onclick = function () {
  if (audioCtx.state === "running") {
    audioCtx.suspend().then(function () {
      susresBtn.textContent = "Resume context";
    });
  } else if (audioCtx.state === "suspended") {
    audioCtx.resume().then(function () {
      susresBtn.textContent = "Suspend context";
    });
  }
};
```

规范
--

| Specification |
| --- |
| Web Audio API # dom-audiocontext-resume |

兼容性
---

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

参见
--

* Using the Web Audio API
* Web Audio API


AudioContext.createMediaStreamSource() - Web API 接口参考

AudioContext.createMediaStreamSource()
======================================

`AudioContext`接口的 `createMediaStreamSource()` 方法用于创建一个新的 `MediaStreamAudioSourceNode` 对象，需要传入一个媒体流对象 (MediaStream 对象)(可以从 `navigator.getUserMedia` 获得 MediaStream 对象实例), 然后来自 MediaStream 的音频就可以被播放和操作。

更多关于媒体流音频源 (media stream audio source nodes) 的细节，请参考`MediaStreamAudioSourceNode` 页面。

语法
--

```js
var audioCtx = new AudioContext();
var source = audioCtx.createMediaStreamSource(stream);
```

### 参数

stream

一个`MediaStream` 对象，把他传入一个音频处理器进行操作

### 返回

`MediaStreamAudioSourceNode`示例
--

本例中，我们从 `navigator.getUserMedia`获取媒体 (audio + video) 流，把它传入 `<video>`中播放，并把视频调成静音，然后把获取到的 audio 传入 `MediaStreamAudioSourceNode`。接下来我们把获取到的 audio 传入`BiquadFilterNode` (可以把声音转化为低音)，输出到 `AudioDestinationNode`.

`<video>` 元素下面滑动杆控制低音过滤器过滤的程度，滑动杆的值越大，低音更明显

**备注：** 你可以查看在线演示，或者查看源码。

```js
var pre = document.querySelector("pre");
var video = document.querySelector("video");
var myScript = document.querySelector("script");
var range = document.querySelector("input");

// getUserMedia 获取流
// 把流放入 MediaStreamAudioSourceNode
// 输出到 video 元素

if (navigator.mediaDevices) {
  console.log("getUserMedia supported.");
  navigator.mediaDevices
    .getUserMedia({ audio: true, video: true })
    .then(function (stream) {
      video.srcObject = stream;
      video.onloadedmetadata = function (e) {
        video.play();
        video.muted = true;
      };

      // 创建 MediaStreamAudioSourceNode
      // Feed the HTMLMediaElement into it
      var audioCtx = new AudioContext();
      var source = audioCtx.createMediaStreamSource(stream);

      // 创建二阶滤波器
      var biquadFilter = audioCtx.createBiquadFilter();
      biquadFilter.type = "lowshelf";
      biquadFilter.frequency.value = 1000;
      biquadFilter.gain.value = range.value;

      // 把 AudioBufferSourceNode 连接到 gainNode
      // gainNode 连接到目的地，所以我们可以播放
      // 音乐并用鼠标调节音量
      source.connect(biquadFilter);
      biquadFilter.connect(audioCtx.destination);

      // Get new mouse pointer coordinates when mouse is moved
      // then set new gain value

      range.oninput = function () {
        biquadFilter.gain.value = range.value;
      };
    })
    .catch(function (err) {
      console.log("The following gUM error occured: " + err);
    });
} else {
  console.log("getUserMedia not supported on your browser!");
}

// dump script to pre element

pre.innerHTML = myScript.innerHTML;
```

**备注：** **注意**: 调用`createMediaStreamSource()`, 来自于媒体流的音频回放将被重新传到 AudioContext 的处理器中。所以播放/暂停流仍然是可以通过 media 元素的 API 和自带的控制器控制。

规范
--

| Specification |
| --- |
| Web Audio API # dom-audiocontext-createmediastreamsource |

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

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

查看更多
----

* Using the Web Audio API (en-US)


AudioContext() - Web API 接口参考

AudioContext()
==============

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

**`AudioContext()`** 构造方法创建了一个新的 `AudioContext` 对象 它代表了一个由音频模块链接而成的音频处理图，每一个模块由 `AudioNode` 表示。

语法
--
```

var audioContext = new AudioContext(options)
```

### 参数

*options* 可选

Options 如下所示：

* `latencyHint`: 这个参数表示了重放的类型，参数是播放效果和资源消耗的一种权衡。可接受的值有 "balanced", "interactive" 和"playback"，默认值为 "interactive"。意思是 "平衡音频输出延迟和资源消耗", "提供最小的音频输出延迟最好没有干扰"和 "对比音频输出延迟，优先重放不被中断"。我们也可以用一个双精度的值来定义一个秒级的延迟数值做到更精确的控制。

规范
--

| Specification |
| --- |
| Web Audio API # dom-audiocontext-audiocontext |

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

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


AudioContext.close() - Web API 接口参考

AudioContext.close()
====================

`AudioContext`的`close()`方法可以关闭 audio context，同时释放占用的所有系统资源。

关闭的 context 不能用来创建新节点，但可以解码音频数据，创建 buffer 等等

该函数不会自动释放所有用`AudioContext 创建的对象`，除非其他引用也都已经解除了。但是，它会强制释放所有可能阻止其他`AudioContexts 被创建或使用`的系统音频资源。挂起 audio context 中音频时间的进度，并停止对音频数据的处理。所有的 AudioContext 创建/阻塞资源都被释放后，返回的`Promise`才会被释放。如果在一个`OfflineAudioContext`上调用该方法，则会抛出`INVALID_STATE_ERR` 异常。

语法
--

```js
var audioCtx = new AudioContext();
audioCtx.close().then(function() { ... });
```

### 返回值

一个 resolve void 值得 `Promise`。

例子
--

下面这段代码是AudioContext states demo (直接运行) 中的，点击停止按钮调用`close()`。promise 释放后，回到初始状态。

```js
stopBtn.onclick = function () {
  audioCtx.close().then(function () {
    startBtn.removeAttribute("disabled");
    susresBtn.setAttribute("disabled", "disabled");
    stopBtn.setAttribute("disabled", "disabled");
  });
};
```

规范
--

| Specification |
| --- |
| Web Audio API # dom-audiocontext-close |

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

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

另见
--

* Using the Web Audio API (en-US)
* Web Audio API


NetworkInformation.rtt - Web API 接口参考

NetworkInformation.rtt
======================

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

**NetworkInformation.rtt** 是一个只读属性，返回了当前连接下评估的往返时延（RTT, round-trip time），并保留该值为 25 千分秒的最接近的整数倍。该值基于最近使用中被监测的最近保持活跃连接的应用层上的 RTT 测量值。它排除了到私有地址空间的连接。如果没有最近的测量数据，该值就基于底层连接技术的属性。

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

Syntax
------
```

rtt = NetworkInformation.rtt
```

### Return value

一个数字。

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

| Specification |
| --- |
| Network Information API # dom-networkinformation-rtt |

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

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


NetworkInformation.downlink - Web API 接口参考

NetworkInformation.downlink
===========================

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

**`downlink`** 是 `NetworkInformation` 接口的一个只读属性，返回以 Mb/s 为单位的有效带宽，并保留该值为 25kb/s 的最接近的整数倍。该值基于最近监测的保持活跃连接的应用层吞吐量，排除了到私有地址空间的连接。当缺少最近的带宽测量数据时，该属性由底层连接技术属性决定。

Syntax
------
```

var downLink = NetworkInformation.downlink
```

### Value

`double` 双精度浮点数。

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

| Specification |
| --- |
| Network Information API # dom-networkinformation-downlink |

Browser Compatibility
---------------------

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


NetworkInformation.saveData - Web API 接口参考

NetworkInformation.saveData
===========================

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

**`NetworkInformation.saveData`** 是 `NetworkInformation` 接口的只读属性，如果用户设备上设置了减少数据使用的选项时返回 `true` .

语法
--
```

var saveData = NetworkInformation.saveData;
```

### 返回值

A `Boolean`.

规范
--

| Specification |
| --- |
| Save Data API # dfn-savedata |

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

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


Animation.Animation() - Web API 接口参考

Animation.Animation()
=====================

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

Animation 构造函数返回一个新的 Animation 对象实例。

语法
--

```js
var animation = new Animation(effect, timeline);
```

### 参数

effect 可选

将`KeyframeEffect` (en-US)对象分配给动画。（在将来，其他类型的效果，如 SequenceEffects 或 GroupEffects 是可能被实现的，但现在，唯一的效果是 KeyframeEffect。）

timeline 可选

指定与动画关联的时间轴。（目前唯一可用的时间轴类型是`DocumentTimeline` (en-US)，但在将来我会有与手势或滚动相关联的时间轴。）默认为`Document.timeline`。这也可以设置为 null。

例子
--

在White Rabbit示例中，Animation 构造函数用于使用文档时间轴为兔子创建关键帧动画：

```js
var rabbitDownAnimation = new Animation(rabbitDownKeyframes, document.timeline);
```

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-animation |

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

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

参见
--

* Web Animations API
* `Animation`


Animation.id - Web API 接口参考

Animation.id
============

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 Animations API 的 **`Animation.id`** 属性可返回或设置用于识别某个动画的唯一标识。

获取与设置 `animation.id`
--------------------

```js
// 获取动画的 id
var animationsId = animation.id;

// 设置动画的 id
animation.id = "newId";
```

返回值
---

当该动画已被分配 id，返回一个 `DOMString`, 当该动画未被分配 id 则返回 null.

示例
--

在 Follow the White Rabbit example 这个例子里，你可以像下面的方式一样，为 `rabbitDownAnimation` 分配一个 id:

```js
rabbitDownAnimation.effect.id = "rabbitGo";
```

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-id |

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

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

参见
--

* KeyframeEffect Interface (en-US)
* Web Animations API
* `Animation`


Animation.currentTime - Web API 接口参考

Animation.currentTime
=====================

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

Animation.currentTime 属性返回或设置动画的当前时间值（以毫秒为单位），无论动画正在运行还是已暂停。

如果动画缺少`timeline`，处于非活动状态或尚未播放，则当前时间返回值为 null。

语法
--
```

var currentTime = element.currentTime;
element.currentTime = someValue;
```

### 值

表示当前时间的数字（以毫秒为单位），或为 null。

例子
--

在Drink Me/Eat Me game中，爱丽丝的高度是可变动的，所以它可以从小到大或从大到小。在游戏开始时，通过将她的动画的 currentTime 设置为她的 keyframeEffect 的持续时间的一半让她的高度设置在两个极端之间：

```js
aliceChange.currentTime = aliceChange.effect.timing.duration / 2;
```

寻求动画的 50％标记的更通用的方法：

```js
animation.currentTime =
  animation.effect.getComputedTiming().delay +
  animation.effect.getComputedTiming().activeDuration / 2;
```

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-currenttime |

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

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

参见
--

* `Animation` for other methods and properties you can use to control web page animation.
* `Animation.startTime` (en-US) for the time an animation is scheduled to start.
* Web Animations API


Animation.finished - Web API 接口参考

Animation.finished
==================

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

Animation.finished 只读属性允许你返回动画的完成状态。

**备注：** The Promise is replaced with a new (pending) Promise object every time the animation leaves the `finished` play state.

语法
--

```js
var animationsPromise = animation.finished;
```

### 值

一个 Promise 对象。

例子
--

以下代码会等到所有动画都完成，然后再移除它们处于活动状态的元素：

```js
Promise.all(
  elem.getAnimations().map(function (animation) {
    return animation.finished;
  }),
).then(function () {
  return elem.remove();
});
```

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-finished |

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

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

参见
--

* KeyframeEffect Interface (en-US)
* Web Animations API
* `Animation`


Animation.play() - Web API 接口参考

Animation.play()
================

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 Animations API的`Animation`接口中的\*\*`play()`\*\* 方法 可开始或恢复动画的播放。如果动画结束，则调用`play()`重新启动动画，从头开始播放。

语法
--
```

animation.play();
```

### 参数

无。

### 返回值

`undefined`例子
--

在 Growing/Shrinking Alice Game 示例中，单击或点击蛋糕会导致 Alice 的增长动画 (`aliceChange`) 播放，导致她体型变大并触发蛋糕的动画。在以下示例中，使用了一个事件监听器来触发两者的动画：

```js
// 蛋糕拥有其自己的动画：
var nommingCake = document
  .getElementById("eat-me\_sprite")
  .animate(
    [{ transform: "translateY(0)" }, { transform: "translateY(-80%)" }],
    {
      fill: "forwards",
      easing: "steps(4, end)",
      duration: aliceChange.effect.timing.duration / 2,
    },
  );

// 暂停蛋糕的动画，以避免动画立即播放。
nommingCake.pause();

// 该函数会在用户点击时触发
var growAlice = function () {
  // Play Alice's animation.
  aliceChange.play();

  // Play the cake's animation.
  nommingCake.play();
};

// 当用户持续按下或点击时，调用 growAlice 函数使得所有的动画播放。
cake.addEventListener("mousedown", growAlice, false);
cake.addEventListener("touchstart", growAlice, false);
```

标准
--

| Specification |
| --- |
| Web Animations # dom-animation-play |

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

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

了解更多
----

* Web Animations API
* `Animation` for other methods and properties you can use to control web page animation.
* `Animation.pause()` (en-US) to pause an animation.
* `Animation.reverse()` (en-US) to play an animation backwards.
* `Animation.finish()` (en-US) to finish an animation.
* `Animation.cancel()` to cancel an animation.


Animation.oncancel - Web API 接口参考

Animation.oncancel
==================

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 Animations API 的 `Animation` 接口的 **`oncancel`** 属性是 `cancel` 事件的事件处理程序。

当动作从其他状态进入 `"idle"` 播放状态，例如当动画在结束播放后从元素中移除时，`cancel` 事件可以 `Animation.cancel()` 被手动触发。

**备注：** 在新的动画中，创建一个新的初始的空闲动画不会触发 `cancel` 事件。

语法
--
```

var cancelHandler = Animation.oncancel;

Animation.oncancel = cancelHandler;
```

### 值

当动画被取消时，这个函数将会被执行。默认是 `null` 。

例子
--

如果动画被取消，将会从元素中移除它。

```js
animation.oncancel = animation.effect.target.remove();
```

标准
--

| Specification |
| --- |
| Web Animations # dom-animation-oncancel |
| Web Animations # cancel-event |

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

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

参见
--

* Web Animations API
* `Animation`


Animation.effect - Web API 接口参考

Animation.effect
================

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

Animation.effect 属性可以获取或设置动画的目标效果。目标效果可以是`KeyframeEffect` (en-US)对象或 null。

语法
--

```js
// Get an Animation object's target effect
var effect = animation.effect;

// Set an Animation's target effect
animation.effect = new KeyframeEffect({ opacity: [1, 0] }, 300);
```

### 值

`KeyframeEffect` (en-US) 对象或 null。

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-effect |

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

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

参见
--

* KeyframeEffect (en-US)
* Web Animations API
* `Animation`


Animation.cancel() - Web API 接口参考

Animation.cancel()
==================

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

`Animation` 接口的 Web 动画 API 的 **`cancel()`** 方法将清除此动画造成的所有 `KeyframeEffect` (en-US)，并中止其播放。

**备注：** 当一个动画被取消时，其 `startTime` (en-US) 和 `currentTime` 被设置为 null。

语法
--
```

Animation.cancel();
```

### 参数

无。

### 返回值

无。

### 异常

这个方法不会直接抛出异常; 但是，如果动画的 `playState` 取消时是除了“空闲”之外的任何东西，current finished promise 被拒绝与一个 `DOMException` 命名的`AbortError`.

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-cancel |

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

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

相关内容
----

* Web Animations API
* `KeyframeEffect` (en-US)
* `Animation`
* `Animation.playState`
* `Animation.finished` returns the promise this action will reject if the animation's `playState` is not `"idle"`.


Animation.playState - Web API 接口参考

Animation.playState
===================

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 Animations API 的属性，**`Animation.playState`** 能够返回并设置一个可枚举值来描述一个动画的回放状态。

**备注：** 这个属性只对 CSS Animations 和 Transitions 可读。

语法
--
```

var currentPlayState = Animation.playState;

Animation.playState = newState;
```

### 可能的值

`idle`

动画当前的时间是无法解析的，并且队列里没有处于等待执行的任务。

`pending`

动画将一直等到某些等待中的任务完成方会执行。

`running`

动画处于正在运行状态。

`paused`

动画中止，并且`Animation.currentTime`该项属性不会更新。

`finished`

动画已经达到某一临界点，并且`Animation.currentTime`该项属性不会更新。

实例
--

在Growing/Shrinking Alice Game这个例子中，玩家们可以凭Alice crying into a pool of tears结束游戏。出于性能原因，游戏里，眼泪只当可见之时才能运动。因此，这些泪滴必须在下面的情况下刚好暂停运动：

```js
// 创建泪珠动画

tears.forEach(function (el) {
  el.animate(tearsFalling, {
    delay: getRandomMsRange(-1000, 1000), // 获取每一滴随机泪珠
    duration: getRandomMsRange(2000, 6000), // 获取每一滴随机泪珠
    iterations: Infinity,
    easing: "cubic-bezier(0.6, 0.04, 0.98, 0.335)",
  });
  el.playState = "paused";
});

// 结尾需要现出时播放眼泪降落动画

tears.forEach(function (el) {
  el.playState = "playing";
});

// 暂停并重置正在哭泣时的泪滴动画

tears.forEach(function (el) {
  el.playState = "paused";
  el.currentTime = 0;
});
```

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-playstate |

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

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

参见
--

* Web Animations API
* `Animation` 获取更多可用来控制网页动画的方法和属性
* `Animation.play()`, `Animation.pause()` (en-US), `Animation.finish()` (en-US)，这些方法可以设置一个动画的 `playState`


HTMLTableElement.createCaption() - Web API 接口参考

HTMLTableElement.createCaption()
================================

这个 **`HTMLTableElement.createCaption()`** 方法返回这个 table 元素的 caption(HTMLTableCaptionElement). 如果这个 table 没有 caption，这个方法创建并返回 caption.

语法
--
```

HTMLTableCaptionElement = table.createCaption()
```

示例
--

```js
mycap = mytable.createCaption();
```

Specification
-------------

* createCaption


HTMLTableElement.rows - Web API 接口参考

HTMLTableElement.rows
=====================

表中所有行的
**`HTMLTableElement.rows`** 只读属性返回表中所有行的一个活的 `HTMLCollection`。**`HTMLTableElement.rows`** 包括与之相关的`<thead>`, `<tfoot>` 和 `<tbody>` 元素。

Although the property is read-only, the returned object is live and allows the modification of its content.

Syntax
------
```

HTMLCollectionObject = table.rows
```

Example
-------

```js
myrows = mytable.rows;
firstRow = mytable.rows[0];
lastRow = mytable.rows[mytable.rows.length - 1];
```

Specification
-------------

* rows
* HTMLcollection


HTMLTableElement.deleteTHead() - Web API 接口参考

HTMLTableElement.deleteTHead()
==============================

**`HTMLTableElement.deleteTHead()`** 方法删除指定 `<table>` 的 `<thead>` 元素。

语法
--
```

HTMLTableElement.deleteTHead();
```

示例
--

本示例使用 JavaScript 删除表格的头部。

### HTML

```html
<table>
  <thead>
    <th>Name</th>
    <th>Occupation</th>
  </thead>
  <tr>
    <td>Bob</td>
    <td>Plumber</td>
  </tr>
  <tr>
    <td>Jim</td>
    <td>Roofer</td>
  </tr>
</table>
```

### JavaScript

```js
let table = document.querySelector("table");
table.deleteTHead();
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-table-deletethead-dev |

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

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


BroadcastChannel：message 事件 - Web API 接口参考

BroadcastChannel：message 事件
===========================

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
当频道收到一条消息时，会在关联的 `BroadcastChannel` 对象上触发 `message` 事件。

语法
--

在 `addEventListener()` 等方法中使用事件名称，或设置事件处理器属性。

```js
addEventListener("message", (event) => {});
onmessage = (event) => {};
```

事件类型
----

一个 `MessageEvent`。继承自 `Event`。

Event

MessageEvent事件属性
----

*除了下面列出的属性之外，还可以使用父接口 `Event` 的属性。*

`data` (en-US) 只读

由消息发送者发送的数据。

`origin` (en-US) 只读

一个表示消息发送者来源的字符串。

`lastEventId` (en-US) 只读

一个表示事件唯一 ID 的字符串。

`source` (en-US) 只读

一个*消息事件源*，可以是一个用于表示消息发送者的 WindowProxy (en-US)、`MessagePort` 或 `ServiceWorker` 对象。

`ports` (en-US) 只读

一个与发送消息（通过频道发送消息或向 SharedWorker 发送消息）的频道相关联的 `MessagePort` 对象的数组。

示例
--

在这个示例中，有一个 `<iframe>` 作为发送者，当用户点击按钮之后，会广播 `<textarea>` 中的内容。同时，有两个 `iframe` 作为接收者，会监听广播的消息，并将结果写入 `<div>` 元素。

### 发送者
```

<h1>发送者</h1>
<label for="message">请输入要广播的信息：</label><br />
<textarea id="message" name="message" rows="1" cols="40">Hello</textarea>
<button id="broadcast-message" type="button">广播信息</button>
```

```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 150px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}

textarea {
  padding: 0.2rem;
}

label,
br {
  margin: 0.5rem 0;
}

button {
  vertical-align: top;
  height: 1.5rem;
}
```

```js
const channel = new BroadcastChannel("example-channel");
const messageControl = document.querySelector("#message");
const broadcastMessageButton = document.querySelector("#broadcast-message");

broadcastMessageButton.addEventListener("click", () => {
  channel.postMessage(messageControl.value);
});
```

### 接收者 1
```

<h1>接收者 1</h1>
<div id="received"></div>
```

```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 100px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}
```

```js
const channel = new BroadcastChannel("example-channel");
channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});
```

### 接收者 2
```

<h1>接收者 2</h1>
<div id="received"></div>
```

```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 100px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}
```

```js
const channel = new BroadcastChannel("example-channel");
channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-message |
| HTML Standard # handler-broadcastchannel-onmessage |

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

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

参见
--

* 相关事件：`messageerror`。


BroadcastChannel.close() - Web API 接口参考

BroadcastChannel.close()
========================

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
通过调用 **`BroadcastChannel.close()`** 方法，可以马上断开其与对应频道的关联，并让其被垃圾回收。这是必要的步骤，因为浏览器没有其他方式知道频道不再被需要。

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

语法
--
```

var str = channel.close();
```

示例
--

```js
// 连接到指定频道
var bc = new BroadcastChannel("test\_channel");

// 其他操作 (如：postMessage, …)

// 当完成后，断开与频道的连接
bc.close();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-close-dev |

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

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

另见
--

* `BroadcastChannel`, the interface it belongs to.


BroadcastChannel: messageerror event - Web API 接口参考

BroadcastChannel: messageerror event
====================================

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
当频道收到一条无法反序列化的消息时会在 `BroadcastChannel` 对象上触发 `messageerror` 事件。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `MessageEvent` |
| Event handler property | `onmessageerror` |

示例
--

以下代码使用 `addEventListener` 来监听消息和错误：

```js
const channel = new BroadcastChannel("example-channel");

channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});

channel.addEventListener("messageerror", (event) => {
  console.error(event);
});
```

使用 `onmessage` 和 `onmessageerror` 事件处理程序来实现相同效果：

```js
const channel = new BroadcastChannel("example-channel");

channel.onmessage = (event) => {
  received.textContent = event.data;
};

channel.onmessageerror = (event) => {
  console.log(event);
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-messageerror |
| HTML Standard # handler-broadcastchannel-onmessageerror |

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

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

另见
--

* 相关事件：`message`


BroadcastChannel.postMessage() - Web API 接口参考

BroadcastChannel.postMessage()
==============================

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
可以使用 **`BroadcastChannel.postMessage()`** 发送一条任意 `Object` 类型的消息，给所有同源下监听了该频道的所有浏览器上下文。消息以 `message` 事件的形式发送给每一个绑定到该频道的广播频道。

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

语法
--
```

var str = channel.postMessage(object);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-postmessage-dev |

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

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

另见
--

* 所属接口：`BroadcastChannel`


BroadcastChannel.name - Web API 接口参考

BroadcastChannel.name
=====================

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
**`BroadcastChannel.name`** 是类型为 `DOMString` 的只读属性，是频道的唯一标识。属性 name 是在创建时传入 `BroadcastChannel()` 构造函数的，所以是只读的。

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

语法
--
```

var str = channel.name;
```

示例
--

```js
// 连接到指定频道
var bc = new BroadcastChannel("test\_channel");

// 其他操作 (如：postMessage, …)

// 在控制台打印频道名称
console.log(bc.name); // "test\_channel"

// 当完成后，断开与频道的连接
bc.close();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-name-dev |

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

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

参见
--

* 所属接口：`BroadcastChannel`


BroadcastChannel() - Web API 接口参考

BroadcastChannel()
==================

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
**`BroadcastChannel()`** 构造函数用于创建一个 `BroadcastChannel` 对象，并与底层的通道相关联。

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

语法
--

```js
new BroadcastChannel(channelName)
```

### 参数

`channelName`

表示通道名称的字符串；对于相同的来源下的所有浏览上下文，一个名称只对应一个通道。

示例
--

```js
// 创建一个监听“internal\_notification”通道的新通道。

const bc = new BroadcastChannel("internal\_notification");
bc.postMessage("New listening connected!");
```

规范
--

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

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

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

另见
--

* 所属接口：`BroadcastChannel`


HTMLTableRowElement.rowIndex - Web API 接口参考

HTMLTableRowElement.rowIndex
============================

只读属性 **`HTMLTableRowElement.rowIndex`** 用于表示元素所在行相对于整个 `<table>` 的逻辑位置。

即使 `<thead>`、`<tbody>` 和 `<tfoot>` 元素在 HTML 中乱序排列，浏览器也会以正确的顺序渲染表格。因此，行号的标记顺序为：从 `<thead>` 到 `<tbody>`，再到 `<tfoot>`。

语法
--

```js
var index = HTMLTableRowElement.rowIndex;
```

### 返回值

返回该行的索引，如果该行不属于表的一部分，则返回 `-1`。

示例
--

本示例使用 JavaScript 标记表中的所有行号。

### HTML

```html
<table>
  <thead>
    <tr>
      <th>商品</th>
      <th>价格</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>香蕉</td>
      <td>$2</td>
    </tr>
    <tr>
      <td>橘子</td>
      <td>$8</td>
    </tr>
    <tr>
      <td>西冷牛排</td>
      <td>$20</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <td>总计</td>
      <td>$30</td>
    </tr>
  </tfoot>
</table>
```

### JavaScript

```js
let rows = document.querySelectorAll("tr");

rows.forEach((row) => {
  let z = document.createElement("td");
  z.textContent = `(row #${row.rowIndex})`;
  row.appendChild(z);
});
```

### 结果

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

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


RTCPeerConnection.createOffer() - Web API 接口参考

RTCPeerConnection.createOffer()
===============================

`RTCPeerConnection`接口的 createOffer() 方法启动创建一个SDP offer，目的是启动一个新的 WebRTC 去连接远程端点。SDP offer 包含有关已附加到 WebRTC 会话，浏览器支持的编解码器和选项的所有`MediaStreamTrack`s 信息，以及ICE 代理，目的是通过信令信道发送给潜在远程端点，以请求连接或更新现有连接的配置。返回值是一个`Promise` (en-US)，创建 offer 后，将使用包含新创建的要约的`RTCSessionDescription`对象来解析该返回值。Syntax
------
```

aPromise = myPeerConnection.createOffer([options]);

myPeerConnection.createOffer(successCallback, failureCallback, [options])
 已弃用
```

### Parameters

选项 可选

`RTCOfferOptions` 词典提供要约所要求的选项。

#### RTCOfferOptions 词典

`RTCOfferOptions` 词典被用于自定义通过此方法创建 offer。

`iceRestart` (en-US) 可选

要在活动连接上重新启动 ICE，请将其设置为`true`。这将导致返回的 offer 与已经存在的凭证不同。如果你应用返回的 offer，则 ICE 将重新启动。指定`false`以保留相同的凭据，因此不重新启动 ICE。默认值为`false`。

`offerToReceiveAudio` 可选 (Legacy)

传统的布尔选项，用于控制是否向远程对等方提供尝试发送音频的机会。如果该值为`false`，即使本地端将发送音频数据，也不会提供远程端点发送音频数据。如果此值为`true`，即使本地端不会发送音频数据，也将向远程端点发送音频数据。默认行为是仅在本地发送音频时才提供接收音频，否则不提供。

 为了在现代实现中模拟此行为，该成员的值为 false 将设置所有现有音频收发器的方向以排除接收（即，设置为“仅发送”或“无效”）。
 在现代实现中，此成员的值为 true 的存在将确保至少有一个收发器集可以接收尚未停止的音频，如果没有，则将创建一个。

**备注：** 你不应该使用此旧版属性。取而代之，用 `RTCRtpTransceiver` (en-US) 去控制是否接受传入的音频。

`offerToReceiveVideo` 可选 (Legacy)

 传统的布尔选项，用于控制是否向远程对等方提供尝试发送视频的机会。如果此值为`false`，即使本地端将发送视频数据，也不会提供远程端点发送视频数据。如果此值为`true`，即使本地端将不发送视频数据，也将向远程端点发送视频数据。默认行为是仅在本地端正在发送视频时才提供接收视频，否则不提供。
 为了在现代实现中模拟这种行为，该成员的值为`false`将设置所有现有视频收发器的方向以排除接收（即设置为“仅发送”或“无效”）。
 在现代实现中，该成员的值为 true 的存在将确保至少有一个收发器集可以接收尚未停止的视频，如果没有，则将创建一个。

**备注：** 你不应该使用此旧版属性。取而代之，用 `RTCRtpTransceiver` (en-US) 去控制是否接受传入的视频。

`voiceActivityDetection` 可选

一些编解码器和硬件能够通过监视是否出现“静音”（或相对较低的声音水平）来检测音频何时开始和结束。通过仅在实际有广播内容时发送音频数据，从而减少了用于音频的网络带宽。但是，在某些情况下，这是不需要的。例如，在音乐或其他非语音传输的情况下，这可能会导致重要的低音量声音丢失。而且，紧急呼叫在安静时切勿切断音频。此选项默认为\*\*`true`\*\*（启用语音活动检测）。

### 不推荐使用的参数

在较早的代码和文档中，你可能会看到此函数的基于回调的版本。不推荐使用并强烈建议不要使用它。你应该更新任何现有代码，以使用基于 `Promise`的`createOffer()`版本。下面介绍了这种形式的`createOffer()`的参数，以帮助更新现有代码。

`successCallback`
已弃用

`RTCSessionDescriptionCallback`将传递一个描述新创建的 offer 的`RTCSessionDescription`对象。

`errorCallback`
已弃用

`RTCPeerConnectionErrorCallback`将会传递给一个`DOMException`对象，该对象说明了创建 offer 的请求失败的原因。

`options` 可选

可选的`RTCOfferOptions`词典，提供 offer 所要求的选项。

### 返回值

`Promise`的履行处理程序将接收符合`RTCSessionDescriptionInit`字典的对象，该字典包含描述所生成 offer 的 SDP。收到的 offer 应通过信令服务器传递到。

### 异常

通过拒绝返回的承诺返回这些异常。你的拒绝处理程序应检查收到的异常，以确定发生了哪些异常。

`InvalidStateError`

`RTCPeerConnection` 被关闭。

`NotReadableError`

没有提供用于保护连接的证书或一组证书，并且`createOffer()`无法创建新证书。由于需要保护所有 WebRTC 连接，因此会导致错误。

`OperationError`

由于某些原因，检查系统状态以确定资源可用性以生成报价失败。

举例
--

在这里，我们看到了 `negotiationneeded` (en-US) 事件的处理程序，该处理程序创建了要约，并通过信令通道将其发送到远程系统。

**备注：** 请记住，这是信令过程的一部分，传输层的实现细节完全由你决定。在这种情况下，WebSocket (en-US)连接用于向其他端点发送带有值为“video-offer”的类型字段的JSON消息。传递给`sendToServer()`函数的对象的内容，以及承诺履行处理程序中的所有其他内容，完全取决于你的设计。

```js
myPeerConnection
  .createOffer()
  .then(function (offer) {
    return myPeerConnection.setLocalDescription(offer);
  })
  .then(function () {
    sendToServer({
      name: myUsername,
      target: targetUsername,
      type: "video-offer",
      sdp: myPeerConnection.localDescription,
    });
  })
  .catch(function (reason) {
    // An error occurred, so handle the failure to connect
  });
```

在此代码中，创建了 offer，一旦成功，就将`RTCPeerConnection`的本地端配置为通过传递要约进行匹配（使用符合`RTCSessionDescriptionInit`）放入`setLocalDescription()` (en-US)。完成后，要约将通过信令通道发送到远程系统。在这种情况下，使用名为`sendToServer()`的自定义函数。信令服务器的实现独立于 WebRTC 规范，因此只要主叫方和潜在接收方都使用相同的 offer，如何发送 offer 都无关紧要。

用 `Promise.catch()` 来捕获和处理错误。

请参阅 Signaling and video calling，以获取此摘录的完整示例。这将帮助你了解此处的信令代码如何工作。

规范
--

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

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

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


RTCPeerConnection.addTrack() - Web API 接口参考

RTCPeerConnection.addTrack()
============================

`RTCPeerConnection` 对象的 **`addTrack()`** 方法将一个新的媒体音轨添加到一组音轨中，这些音轨将被传输给另一个对等点。

**备注：** 通过触发一个 `negotiationneeded` (en-US) 事件，向连接添加一个跟踪将触发重新协商。详情请参见开始协商。

语法
--
```

rtpSender = rtcPeerConnection.addTrack(track, stream...);
```

### 参数

`track`

一个`MediaStreamTrack`对象，表示要添加到对等连接的媒体轨道。

`stream...` 可选

一个或多个本地的`MediaStream`对象，该轨迹应添加到其中。

指定的 **`track`** 不一定已经是任何指定 **`streams`** 的一部分。相反，**`streams`** 只是在连接的接收端将轨迹分组在一起的一种方式，以确保它们是同步的。在连接的本地端添加到相同流的任何轨道都将位于远程端相同的流上。

### 返回值

将用于传输媒体数据的`RTCRtpSender` (en-US)对象。

**备注：** 每个 **`RTCRtpSender`** 都与`RTCRtpReceiver` (en-US)配对，组成`RTCRtpTransceiver` (en-US)。关联的接收方处于静默状态 (指示它不能发送数据包)，直到或除非远程对等方向接收方添加一个或多个流。

### 异常

`InvalidAccessError`

指定的轨道 (或它的所有底层流) 已经是`RTCPeerConnection`的一部分。

`InvalidStateError`

`RTCPeerConnection`被关闭。

使用笔记
----

### 向多个流添加轨道

在 **`track`** 参数之后，你可以选择指定一个或多个`MediaStream`对象来添加\*\*`track`\*\*。只有轨道从一个点发送到另一个点，而不是一个媒体流。由于流是特定于每个对等点的，因此指定一个或多个流意味着另一个对等点将在连接的另一端自动创建一个相应的流 (或多个流)，然后自动将接收到的轨道添加到这些流中。

#### 无流承载的轨道

如果没有指定媒体流，则轨道是无流的。这是完全可以接受的，尽管要由远程对等点决定将轨道插入到哪个流 (如果有的话)。当构建一个多类型的简单应用只有一个媒体流时，使用 **`addTrack()`** 是一个非常常用的办法。例如，如果你与远程对等点共享的只是带有音频轨道和视频轨道的单个流，那么你不需要管理流中的哪个轨道，所以你不妨让**transceriver**为你处理它。

下面是一个使用`getUserMedia()`从用户的摄像机和麦克风获取一个流，然后将流中的每条轨迹添加到对等连接，而不为每条轨迹指定一个流：

```js
async openCall(pc) {
  const gumStream = await navigator.mediaDevices.getUserMedia(
                          {video: true, audio: true});
  for (const track of gumStream.getTracks()) {
    pc.addTrack(track);
  }
}
```

结果是一组没有流关联的跟踪被发送到远程对等点。远程对等点上的 `track` 事件的处理程序将负责决定将每个跟踪添加到哪个流中，即使这意味着只是将它们全部添加到同一个流中。`ontrack` 方法如下：

```js
let inboundStream = null;

pc.ontrack = (ev) => {
  if (ev.streams && ev.streams[0]) {
    videoElem.srcObject = ev.streams[0];
  } else {
    if (!inboundStream) {
      inboundStream = new MediaStream();
      videoElem.srcObject = inboundStream;
    }
    inboundStream.addTrack(ev.track);
  }
};
```

在这里，如果指定了流，则 **`track`** 事件处理程序将跟踪添加到事件指定的第一个流。否则，在第一次调用 **`ontrack`** 时，将创建一个新流并附加到视频元素，然后将音轨添加到新流中。从那时起，新的堆**track**被添加到这个流中。

你也可以为每个接收到的**track**创建一个新的流：

```js
pc.ontrack = (ev) => {
  if (ev.streams && ev.streams[0]) {
    videoElem.srcObject = ev.streams[0];
  } else {
    let inboundStream = new MediaStream(ev.track);
    videoElem.srcObject = inboundStream;
  }
};
```

#### 将**track**与特定的 stream 相关联

通过指定一个流并允许`RTCPeerConnection`为你创建流，流的跟踪关联将由 WebRTC 基础设施自动为你管理。这包括对收发器的`direction` 的更改和被停止使用`removeTrack()` (en-US)。

例如，考虑应用程序可能使用的这个函数，通过`RTCPeerConnection`将设备的摄像头和麦克风输入流化为远程对等点：

```js
async openCall(pc) {
  const gumStream = await navigator.mediaDevices.getUserMedia(
                          {video: true, audio: true});
  for (const track of gumStream.getTracks()) {
    pc.addTrack(track, gumStream);
  }
}
```

远程对等点然后可以使用一个看起来像这样的 `track` 事件处理程序：

```js
pc.ontrack = ({streams: [stream]} => videoElem.srcObject = stream);
```

这将把视频元素的当前流设置为包含已添加到连接中的音轨的流。

### 重用发送方

这种方法可以返回一个新的 **`RTCRtpSender`**，或者在非常特殊的情况下，返回一个尚未用于传输数据的现有的兼容发送方。兼容的可重用 **`RTCRtpSender`** 实例满足以下条件：

* 没有与发送方关联的跟踪。
* 与发送方关联的{domxref("RTCRtpTransceiver")}}有一个{domxref("RTCRtpReceiver")}}，它的`track` (en-US)属性指定了一个`MediaStreamTrack`它的`kind` (en-US)与调用 **`RTCPeerConnection.addTrack()`** 时指定的 track 参数的 kind 相同。这确保了收发器只能处理音频或视频，而不能同时处理二者。
* **`RTCRtpTransceiver`** 的`stopped` (en-US)属性为\*\*`false`\*\*。
* 正在考虑的 **`RTCRtpSender`** 从未被用于发送数据。如果收发器的`currentDirection` (en-US) 曾经是“**`sendrecv`**”或“**`sendonly`**”，发送方不能被重用。

如果所有这些条件都满足，发送方会被重用，这将导致现有 **`RTCRtpSender`** 和它的 **`RTCRtpTransceiver`** 发生这些变化：

* **`RTCRtpSender`** 的`track` (en-US)被设置为指定的 track。
* 发送方的相关流集被设置为传递到这个方法的流列表，**`stream…`**
* 关联的`RTCRtpTransceiver` (en-US)更新了它的当前方向，包括发送;如果它的当前值是“**`recvonly`**”，它就变成“**`sendrecv`**”，如果它的当前值是“**`inactive`**”，它就变成“**`sendonly`**”。
### 新发送方

如果现有的发送方不存在可重用，则创建一个新的发送方。这也会导致必须存在的关联对象的创建。创建新发送方的过程会导致以下更改：

* 使用指定的 **`track`** 和 **`streams`** 集创建新的\*\*`RTCRtpSender`\*\*。
* 新`RTCRtpReceiver` (en-US)被创建，新`MediaStreamTrack`作为它的`track` (en-US) 属性 (不是调用 **`addTrack()`** 时指定作为参数的 track)。这跟踪的`kind` (en-US)设置为与作为输入参数提供的音轨类型匹配。
* 将创建一个新的`RTCRtpTransceiver` (en-US)，并与新的发送方和接收方关联。
* 新的 **`transceiver`** 的 `direction` 设置为"**`sendrecv`**"。
* 新的 **`transceiver`** 被添加到 RTCPeerConnection 的收发器集合中。
实例
--

这个例子是从文章中给出的Signaling and video calling及其相应的示例代码中提取的。它来自那里的 **`handleVideoOfferMsg()`** 方法，该方法在从远程对等方接收到报价消息时被调用。

```js
var mediaConstraints = {
  audio: true, // We want an audio track
  video: true, // ...and we want a video track
};

var desc = new RTCSessionDescription(sdp);

pc.setRemoteDescription(desc)
  .then(function () {
    return navigator.mediaDevices.getUserMedia(mediaConstraints);
  })
  .then(function (stream) {
    previewElement.srcObject = stream;

    stream.getTracks().forEach((track) => pc.addTrack(track, stream));
  });
```

这段代码获取从远程对等方接收到的 SDP，并构造一个新的 `RTCSessionDescription` 传递到 `setRemoteDescription()`。成功之后，它使用 `MediaDevices.getUserMedia` 获得对本地摄像头和麦克风的访问。

如果成功，结果流将被分配为变量 **`previewElement`** 引用的`<video>`元素的源。

最后一步是开始通过对等连接向调用者发送本地视频。通过遍历`MediaStream.getTracks()`返回的列表，并将它们与作为其组件的流一起传递给\*\*`addTrack()`\*\*，从而在流中添加每条跟踪。

规范
--

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

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

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

参见
--

* WebRTC
* 实时传输协议（RTP）简介 (en-US)
* `track`


RTCPeerConnection.ondatachannel - Web API 接口参考

RTCPeerConnection.ondatachannel
===============================

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

**`RTCPeerConnection.ondatachannel`** 属性是一个事件处理器，当 `datachannel` 事件在 `RTCPeerConnection` 发生时，它指定的那个事件处理函数就会被调用。这个事件继承于 `RTCDataChannelEvent` (en-US)，当远方伙伴调用 `createDataChannel()` 时这个事件被加到这个连接（RTCPeerConnection）中。

在这个事件被收到的同时，这个 `RTCDataChannel` 实际上并没有打开，确保在 open 这个事件在`RTCDataChannel`触发以后才去使用它。

语法
--
```

RTCPeerConnection.ondatachannel = function;
```

### 值

将这个属性设置为接受一个参数的函数：这个参数是一个`RTCDataChannelEvent` (en-US)，它的 channel 属性是一个已经创建了的`RTCDataChannel`对象

示例
--

```js
pc.ondatachannel = function (ev) {
  console.log("Data channel is created!");
  ev.channel.onopen = function () {
    console.log("Data channel is open and ready to be used.");
  };
};
```

规范
--

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

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

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

参见
--

* WebRTC API
* 使用 WebRTC data channel (en-US)
* RTCDataChannel 简单示例
* `RTCDataChannelEvent` (en-US)
* `RTCPeerConnection.createDataChannel()`


RTCPeerConnection.iceGatheringState - Web API 接口参考

RTCPeerConnection.iceGatheringState
===================================

只读属性 **`RTCPeerConnection.iceGatheringState`** 返回一个描述连接的 ICE 收集状态的字符串。比如当 ICE 候选收集完成的时候，你可以通过该属性的变化侦测到。

通过监听 `icegatheringstatechange` (en-US) 类型的事件，你可以侦测到该属性的变化。

值
-

可能的值是：

`new`

对等连接刚刚创建，尚未进行任何网络连接。

`gathering`

ICE 代理正在收集候选的连接。

`complete`

ICE 代理完成了候选的收集。如果发生了需要收集的新候选，例如一个新接口的增加或者一个新的 ICE 服务器的增加，状态将恢复到 `gathering`，并去收集这些候选。

示例
--

```js
const pc = new RTCPeerConnection();
const state = pc.iceGatheringState;
```

规范
--

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

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

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

参见
--

* `icegatheringstatechange` (en-US)
* WebRTC


RTCPeerConnection.createDataChannel() - Web API 接口参考

RTCPeerConnection.createDataChannel()
=====================================

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

`RTCPeerConnection` 的 `createDataChannel()` 方法创建一个可以发送任意数据的数据通道 (data channel)。常用于后台传输内容，例如：图像，文件传输，聊天文字，游戏数据更新包，等等。

基于某个连接创建第一个 data channel 时，会通过发送一个 `negotiationneeded` (en-US) 事件来开始重新谈判（renegotiation）。

语法
--
```

dataChannel = RTCPeerConnection.createDataChannel(label[, options]);
```

### 参数

`label`

一个便于理解的通道名。该字符串不能长于 65,535 *字节*.

`options` 可选

提供 data channel 设置的一个 `RTCDataChannelInit` dictionary

### RTCDataChannelInit dictionary

`RTCDataChannelInit` 字典提供以下字段，用以构造可选的 options 参数来设置 data channel 以满足你的需求：

`ordered` 可选

表示通过 `RTCDataChannel` 的信息的到达顺序需要和发送顺序一致 (`true`), 或者到达顺序不需要和发送顺序一致 (`false`). **默认：`true`.**

**`maxPacketLifeTime` 可选**

The maximum number of milliseconds that attempts to transfer a message may take in unreliable mode. While this value is a 16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. **Default: `null`.**

`maxRetransmits` 可选

The maximum number of times the user agent should attempt to retransmit a message which fails the first time in unreliable mode. While this value is a16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. **Default: `null`.**

`protocol` 可选

The name of the sub-protocol being used on the `RTCDataChannel`, if any; otherwise, the empty string (""). **Default: empty string, `""`.** This string may not be longer than 65,535 *bytes*.

`negotiated` 可选

By default (`false`), data channels are negotiated in-band, where one side calls `createDataChannel`, and the other side listens to the `RTCDataChannelEvent` (en-US) event using the `ondatachannel` `EventHandler` . Alternatively (`true`), they can be negotiated out of-band, where both sides call `createDataChannel` with an agreed-upon id. **Default: `false`.**

`id` 可选

An 16-bit numeric ID for the channel; permitted values are 0-65534. If you don't include this option, the user agent will select an ID for you.

**备注：** The options which can be configured using the `RTCDataChannelInit` dictionary represent the script-settable subset of the properties on the `RTCDataChannel` interface.

### Return value

A new `RTCDataChannel` object with the specified `label`, configured using the options specified by `options` if that parameter is included; otherwise, the defaults listed above are established.

### Exceptions

`InvalidStateError`

The `RTCPeerConnection` is closed.

`TypeError`

This can happen in a couple of situations:

* The label and/or protocol string is too long; these cannot be longer than 65,535 bytes (bytes, rather than characters).
* The `id` is 65535. While this is a valid unsigned 16-bit value, it's not a permitted value for `id`.

`SyntaxError`

Values were specified for both the `maxPacketLifeTime` and `maxRetransmits` options. You may only specify a non-`null` value for one of these.

`ResourceInUse`

An `id` was specified, but another `RTCDataChannel` is already using the same value.

`OperationError`

Either the specified `id` is already in use or, if no `id` was specified, the WebRTC layer was unable to automatically generate an ID because all IDs are in use.

Examples
--------

This example shows how to create a data channel and set up handlers for the `open` (en-US) and `message` events to send and receive messages on it (For brievity, the example assumes onnegotiationneeded is set up).

```js
// Offerer side

var pc = new RTCPeerConnection(options);
var channel = pc.createDataChannel("chat");
channel.onopen = function (event) {
  channel.send("Hi you!");
};
channel.onmessage = function (event) {
  console.log(event.data);
};
```

```js
// Answerer side

var pc = new RTCPeerConnection(options);
pc.ondatachannel = function (event) {
  var channel = event.channel;
  channel.onopen = function (event) {
    channel.send("Hi back!");
  };
  channel.onmessage = function (event) {
    console.log(event.data);
  };
};
```

Alternatively, more symmetrical out-of-band negotiation can be used, using an agreed-upon id (0 here):

```js
// Both sides

var pc = new RTCPeerConnection(options);
var channel = pc.createDataChannel("chat", { negotiated: true, id: 0 });
channel.onopen = function (event) {
  channel.send("Hi!");
};
channel.onmessage = function (event) {
  console.log(event.data);
};
```

For a more thorough example showing how the connection and channel are established, see A simple RTCDataChannel sample.

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

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

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

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

See also
--------

* `RTCDataChannel`
* A simple RTCDataChannel sample
* `RTCPeerConnection`


RTCPeerConnection.currentLocalDescription - Web API 接口参考

RTCPeerConnection.currentLocalDescription
=========================================

只读属性 **`RTCPeerConnection.currentLocalDescription`** 返回一个 `RTCSessionDescription` 对象，该对象描述了 自上次 `RTCPeerConnection` 完成协商与连接到远程端后，最近一次成功协商的连接的本地端。原文（describing the local end of the connection as it was most recently successfully negotiated since the last time the RTCPeerConnection finished negotiating and connecting to a remote peer）。也包括自 RTCSessionDescription 所代表的 offer 或 anwser 首次实例化以来，ICE 代理可能已经生成的任何 ICE 候选人的列表。

若想改变 `currentLocalDescription` ，则调用 `RTCPeerConnection.setLocalDescription()` (en-US) 。这将会触发引发该值被设置的一系列事件。如果希望详细了解策略与机制，查阅待定的和当前描述。

**备注：** 与 `RTCPeerConnection.localDescription` (en-US) 不同，这个值代表了当前连接的本地端的事实当前状态； `localDescription` 也许指明了一个当前正在切换中的连接的 description。

语法
--
```

sessionDescription = RTCPeerConnection.currentLocalDescription;
```

### 返回值

连接本地端的当前 description 描述，如果成功设置了一个。否则返回 null。

示例
--

本例子查看 `currentLocalDescription` 并且显示了包含 `RTCSessionDescription` 对象的 `type` 与 `sdp` 字段的 alert。

```js
var pc = new RTCPeerConnection();
…
var sd = pc.currentLocalDescription;
if (sd) {
  alert("Local session: type='" +
        sd.type + "'; sdp description='" +
        sd.sdp + "'");
}
else {
  alert("No local session yet.");
}
```

规范
--

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

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

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

**备注：** The addition of `currentLocalDescription` and `pendingLocalDescription` (en-US) to the WebRTC spec is relatively recent. In browsers which don't support them, just use `localDescription` (en-US).

参见
--

* `RTCPeerConnection.setLocalDescription()` (en-US)、`RTCPeerConnection.pendingLocalDescription` (en-US)、`RTCPeerConnection.localDescription` (en-US)
* `RTCPeerConnection.setRemoteDescription()`、`RTCPeerConnection.remoteDescription`、`RTCPeerConnection.pendingRemoteDescription` (en-US)、`RTCPeerConnection.currentRemoteDescription` (en-US)
* WebRTC


RTCPeerConnection.remoteDescription - Web API 接口参考

RTCPeerConnection.remoteDescription
===================================

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

只读属性 **`RTCPeerConnection.remoteDescription`** 返回一个 `RTCSessionDescription` ，它描述了和远程对端之间的会话 (包括配置和媒体信息) ，如果还没有被设置过的话，它会是 `null`.

这个值通常是通过信令服务器接收的对端的会话描述（作为提议或应答），调用`RTCPeerConnection.setRemoteDescription()`之后生效。

语法
--
```

 var sessionDescription = peerConnection.remoteDescription;
```

从更基础的层面上看，如果该属性不为`null`，则返回值为`RTCPeerConnection.pendingRemoteDescription` (en-US)的值，否则，返回`RTCPeerConnection.currentRemoteDescription` (en-US)的值。有关此算法的详细信息及其使用原因，请参阅待定的和当前描述。

示例
--

此示例查看`remoteDescription`并显示包含`RTCSessionDescription`对象的 type 和`sdp`字段的警告。

```js
var pc = new RTCPeerConnection();
…
var sd = pc.remoteDescription;
if (sd) {
  alert("Remote session: type='" +
        sd.type + "'; sdp description='" +
        sd.sdp + "'");
}
else {
  alert("No remote session yet.");
}
```

规范
--

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

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

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

参见
--

* `RTCPeerConnection.setRemoteDescription()`、`RTCPeerConnection.pendingRemoteDescription` (en-US)、`RTCPeerConnection.currentRemoteDescription` (en-US)
* `RTCPeerConnection.setLocalDescription()` (en-US)、`RTCPeerConnection.pendingLocalDescription` (en-US)、`RTCPeerConnection.currentLocalDescription`、`RTCPeerConnection.localDescription` (en-US)
* WebRTC


RTCPeerConnection.canTrickleIceCandidates - Web API 接口参考

RTCPeerConnection.canTrickleIceCandidates
=========================================

只读的 **`RTCPeerConnection`** 属性 `canTrickleIceCandidates` 返回一个`Boolean`，它指示远程对等端是否可以接受 trickled ICE candidates 。

**ICE trickling**是在初始发送或回应已经发送给其他设备之后继续发送候选的过程。

仅在调用`RTCPeerConnection.setRemoteDescription()`之后才设置此属性。理想情况下，你的信令协议提供了一种检测滴流支持的方法，因此你无需依赖此属性。WebRTC 浏览器将始终支持 trickle ICE。如果不支持滴流，或者你无法辨别，则可以检查此属性的伪值，然后等待`iceGatheringState`的值更改在创建和发送之前“完成”。这样，发送信息包含所有候选。

值
-

`Boolean` 如果远程对等体可以接受滴入的 ICE candidate，则为 true；如果不能，则为 false。如果尚未建立远程对等方，则此值为 null。

**备注：** 一旦本地对等方调用`RTCPeerConnection.setRemoteDescription()`，就确定该属性的值; ICE 代理使用所提供的描述来确定远程对等体是否支持滴入的 ICE candidates。

示例
--

```js
var pc = new RTCPeerConnection();
// The following code might be used to handle an offer from a peer when
// it isn't known whether it supports trickle ICE.
pc.setRemoteDescription(remoteOffer)
  .then(\_ => pc.createAnswer())
  .then(answer => pc.setLocalDescription(answer))
  .then(\_ =>
    if (pc.canTrickleIceCandidates) {
      return pc.localDescription;
    }
    return new Promise(r => {
      pc.addEventListener('icegatheringstatechange', e => {
        if (e.target.iceGatheringState === 'complete') {
          r(pc.localDescription);
        }
      });
    });
  })
  .then(answer => sendAnswerToPeer(answer)) // signaling message
  .catch(e => handleError(e));

pc.addEventListener('icecandidate', e => {
  if (pc.canTrickleIceCandidates) {
    sendCandidateToPeer(e.candidate); // signaling message
  }
});
```

规范
--

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

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

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

参见
--

* WebRTC
* `RTCPeerConnection.addIceCandidate()`
* WebRTC 会话的生命周期


RTCPeerConnection: icecandidate 事件 - Web API 接口参考

RTCPeerConnection: icecandidate 事件
==================================

当 `RTCPeerConnection` 通过 `RTCPeerConnection.setLocalDescription()` (en-US) 方法更改本地描述之后，该 `RTCPeerConnection` 会抛出 **`icecandidate`** 事件。该事件的监听器需要将更改后的描述信息传送给远端 `RTCPeerConnection`，以更新远端的备选源。

使用指南
----

`icecandidate` 的类型为 `RTCPeerIceCandidateEvent`, 在以下三种情况下会触发该事件：

### 分享新的候选

触发 `icecandidate` 事件的首要原因：当获得新的源之后，需要将该源的信息发送给远端信号服务器，并分发至其他端的 `RTCPeerConnection`。其他 `RTCPeerConnection` 通过 `addIceCandidate()` 方法将新 `candidate` 中携带的信息，将新的源描述信息添加进它的备选池中；

```js
rtcPeerConnection.onicecandidate = (event) => {
  if (event.candidate) {
    sendCandidateToRemotePeer(event.candidate);
  } else {
    /\* 在此次协商中，没有更多的候选了 \*/
  }
};
```

远程的节点在接受到候选后，将通过调用 `addIceCandidate()` 的方式将候选加入候选池中，并传入通过信令服务器得到的 `candidate` (en-US) 字符串（作为参数）。

### 代表最后一轮候选结束

当一个 ICE 协商会话没有候选来提供给某个给定的 RTCIceTransport，就完成了一轮候选的收集。一个带有空字串（""）的 icecandidate 事件出现，表明了这种情况。

你应当像对待任何普通候选一般向远程节点传递这个候选，正如在上述“共享一个新的候选”里所描述的。这就确保了远程节点也能获得候选终结的通知。正如你在上一个小节的代码里所见，每个候选都被发送到别的节点，包括任何可能含有空候选字串的。只有那些事件的 candidate 属性为 null 的不通过信令连接传递。

候选终结指示在 Trickle ICE draft 规范的 9.3 章有描述（注意，章节号码会根据标准的反复修正而发生改变）

### 代表 ICE 收集完成

一旦所有的 ICE 传输完成收集候选并且 `RTCPeerConnection` 对象的 `iceGatheringState` 的值变化成 `complete`，一个 `icecandidate` 事件携带着值为 `null` 的 `complete` 属性的被发送。

这个信号的存在是为了向后兼容的目的，并且不需要向远程节点分发（这也就是为什么上面的代码片段检查了 event.candidate 是否为 null，优先于沿着候选发送）

如果你需要执行任何特别的动作，当没有更多的期待的候选，你最好通过观察 `icegatheringstatechange` (en-US) 事件来观察 ICE 收集状态。

```js
pc.addEventListener("icegatheringstatechange", (ev) => {
  switch (pc.iceGatheringState) {
    case "new":
      /\* gathering is either just starting or has been reset \*/
      break;
    case "gathering":
      /\* gathering has begun or is ongoing \*/
      break;
    case "complete":
      /\* gathering has ended \*/
      break;
  }
});
```

如你在这个例子中看到的，icegatheringstatechange 事件让你知道 RTCPeerConnection 属性 iceGatheringState 被更新的时机。如果那个值现在是 complete，你就知道 ICE 收集刚刚结束。

对表明一个 ICE 会话已经结束而言，相比观察一个单独的 ICE 消息，这是更为可靠的方法。

### 示例

这个例子建立一个简单的 icecandidate 事件处理器，通过信令服务器使用一个 sendMessenge() 来建立和发送一个回复给远程节点。

首先，一个使用 addEventListener() 的例子：

```js
pc.addEventListener(
  "icecandidate",
  (ev) => {
    if (ev.candidate) {
      sendMessage({ type: "new-ice-candidate", candidate: event.candidate });
    }
  },
  false,
);
```

你也可以直接设定 `onicecandidate` 事件处理器的属性：

```js
pc.onicecandidate = (ev) => {
  if (ev.candidate) {
    sendMessage({ type: "new-ice-candidate", candidate: event.candidate });
  }
};
```

概述
--

接口
`RTCPeerConnectionIceEvent` (en-US)
事件冒泡

否

能否取消默认

否

事件目标
`RTCPeerConnection`
默认行为

无

属性
--

*属性继承自`RTCPeerConnectionIceEvent` (en-US).*

方法
--

*方法继承自 `RTCPeerConnectionIceEvent` (en-US).*

相关事件
----

* *无*
规范
--

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

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

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

参见
--

* WebRTC


RTCPeerConnection() - Web API 接口参考

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() - Web API 接口参考

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 - Web API 接口参考

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 - Web API 接口参考

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 - Web API 接口参考

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 - Web API 接口参考

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 - Web 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.addIceCandidate() - Web API 接口参考

RTCPeerConnection.addIceCandidate()
===================================

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

当本机当前页面的 `RTCPeerConnection` 接收到一个从远端页面通过信号通道发来的新的 ICE 候选地址信息，本机可以通过调用\*\*`RTCPeerConnection.addIceCandidate()`\*\* 来添加一个 ICE 代理。This adds this new remote candidate to the `RTCPeerConnection`'s remote description, which describes the state of the remote end of the connection.

If the value of the specified object'`s` `candidate` (en-US) is an empty string (`""`), it signals that all remote candidates have been delivered.

During negotiation, your app will likely receive many candidates which you'll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods. This is covered in more detail in the articles WebRTC connectivity and Signaling and video calling.

Syntax
------
```

aPromise = pc.addIceCandidate(candidate);

addIceCandidate(candidate, successCallback, failureCallback);
 已弃用
```

### Parameters

`candidate`

An object conforming to the `RTCIceCandidateInit` (en-US) dictionary; the contents of the object should be constructed from a message received over the signaling channel, describing a newly received ICE candidate that's ready to be delivered to the local ICE agent.

### Deprecated parameters

在一些老旧的代码和文档中，你可能会看到一个回调函数 (callback) 版本的函数。这种函数是过期的，强烈建议不要使用。你应该更新你的代码，使用 `Promise`-版本的 `addIceCandidate()` . 这个版本的参数格式附在下面，方便你更新已有的代码。

`successCallback`
已弃用

A function to be called when the ICE candidate has been successfully added. This function receives no input parameters and doesn't return a value.

`failureCallback`
已弃用

A function to be called if attempting to add the ICE candidate fails. Receives as input a `DOMException` object describing why failure occurred.

### Return value

A `Promise` which is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent. The promise does not receive any input parameters.

### Exceptions

When an error occurs while attempting to add the ICE candidate, the `Promise` returned by this method is rejected, returning one of the errors below as the `name` attribute in the specified `DOMException` object passed to the rejection handler.

`TypeError`

The specified candidate doesn't have values for both `sdpMid` (en-US) and `sdpMLineIndex` (en-US).

`InvalidStateError`

The `RTCPeerConnection` currently has no remote peer established (`remoteDescription` is `null`).

`OperationError`

A non-`null` value was specified for `sdpMid` (en-US), but the value doesn't match the mid of any media description in the `remoteDescription`, or `sdpMLineIndex` (en-US) is greater than or equal to the number of media descriptions in `remoteDescription`. This error can also be thrown if a value is given for `ufrag` that doesn't match the value of `ufrag` in any of the remote description being selected.

`OperationError` also occurs if the attempt to add the candidate fails for any other reason.

Example
-------

下段代码会展示如何使用一个 SDP 字符串 (这个字符串包含了候选的描述) 去构建一个候选对象。这个字符串来自于信道 (signaling channel)。

```js
// |receivedSDP| is an SDP string received over the signaling channel
// by our handler for "new ICE candidate" messages.

let candidate = new RTCIceCandidate(receivedSDP);

pc.addIceCandidate(candidate)
  .then((\_) => {
    // Do stuff when the candidate is successfully passed to the ICE agent
  })
  .catch((e) => {
    console.log("Error: Failure during addIceCandidate()");
  });
```

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

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

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

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

See also
--------

* WebRTC API
* Signaling and video calling
* WebRTC architecture overview (en-US)
* WebRTC connectivity
* Lifetime of a WebRTC session


RTCPeerConnection.getReceivers() - Web API 接口参考

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() - Web API 接口参考

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() - Web API 接口参考

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 - Web API 接口参考

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() 方法 - Web 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() 方法 - Web 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() 方法 - Web 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() 方法 - Web 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() 方法 - Web 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() 方法 - Web 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() 方法 - Web 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 - Web 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() - Web API 接口参考

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() 构造方法 - Web API 接口参考

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.


BarcodeDetector：detect() 方法 - Web API 接口参考

BarcodeDetector：detect() 方法
===========================

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

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

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

`BarcodeDetector` 接口的 **`detect()`** 方法返回一个 `Promise`，它兑现一个从图像中检测到的条形码的数组。

语法
--

```js
detect(imageBitmapSource)
```

### 参数

`imageBitmapSource`

接受一个图像源作为参数；它可以是以下对象之一：`HTMLImageElement`、`SVGImageElement` (en-US)、`HTMLVideoElement`、`HTMLCanvasElement`、`ImageBitmap`、`OffscreenCanvas`、`VideoFrame` (en-US)、`Blob` 格式的图像或 `ImageData`。

### 返回值

返回一个 `Promise`，它兑现一个具有以下属性的 `DetectedBarcode` 对象数组：

`boundingBox`

一个 `DOMRectReadOnly`，返回表示检测到的条形码范围的矩形尺寸，与图像对齐。

`cornerPoints`

检测到的条形码的四个角点相对于图像的 x 和 y 坐标，从左上角开始顺时针旋转。由于图像内的透视变形，这可能不是方形的。

`format`

检测到的条形码格式。（有关格式的完整列表，请参阅受支持的条形码格式类型）

`rawValue`

一个从条形码数据解码的字符串。

### 异常

`TypeError`

如果未指定参数或 `type` 参数不是一个 `ImageBitmapSource` 类型，抛出此异常。

`SecurityError` `DOMException`

如果 `imageBitmapSource` 有源并且与文档的源不同，或者如果 `imageBitmapSource` 是一个 `HTMLCanvasElement` 及其 origin-clean 标志设置为 `false`，抛出此异常。

`InvalidStateError` `DOMException`

如果 `imageBitmapSource` 是一个 `HTMLImageElement` 并且未完全解码或解码失败，或者是一个 `HTMLVideoElement` 并且其 `readyState` 属性是 `HAVE_NOTHING` 或 `HAVE_METADATA`，抛出此异常。

示例
--

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

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

规范
--

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

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

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


BarcodeDetector：getSupportedFormats() 静态方法 - Web API 接口参考

BarcodeDetector：getSupportedFormats() 静态方法
==========================================

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

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

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

`BarcodeDetector` 接口的 **`getSupportedFormats()`** 静态方法返回一个 `Promise`，它兑现一个包含受支持的条形码格式类型的数组。

语法
--

```js
BarcodeDetector.getSupportedFormats()
```

### 参数

该方法不接收任何参数。

### 返回值

一个 `Promise`，它兑现一个包含受支持的条形码格式类型的数组。

### 异常

不会抛出任何异常。

示例
--

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

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

规范
--

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

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

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


DataTransferItemList.length - Web API 接口参考

DataTransferItemList.length
===========================

`DataTransferItemList` 接口的只读属性\*\*`length`\*\* 返回当前拖动项列表中项目的数量。

语法
--
```

length = DataTransferItemList.length;
```

### 值

列表中拖动项的数量，如果列表为空或禁用则为 0。如果列表的`DataTransfer`对象未与拖动数据存储关联，则认为拖动列表被禁用。

示例
--

这个例子演示了 `length` 属性的用法。

### JavaScript

```js
function dragstart\_handler(ev) {
  console.log("dragStart");
  // Add this element's id to the drag payload so the drop handler will
  // know which element to add to its tree
  var dataList = ev.dataTransfer.items;
  dataList.add(ev.target.id, "text/plain");
  // Add some other items to the drag payload
  dataList.add("<p>... paragraph ...</p>", "text/html");
  dataList.add("http://www.example.org", "text/uri-list");
}

function drop\_handler(ev) {
  console.log("Drop");
  ev.preventDefault();
  var data = ev.dataTransfer.items;
  // Loop through the dropped items and log their data
  for (var i = 0; i < data.length; i++) {
    if (data[i].kind == "string" && data[i].type.match("^text/plain")) {
      // This item is the target node
      data[i].getAsString(function (s) {
        ev.target.appendChild(document.getElementById(s));
      });
    } else if (data[i].kind == "string" && data[i].type.match("^text/html")) {
      // Drag data item is HTML
      data[i].getAsString(function (s) {
        console.log("... Drop: HTML = " + s);
      });
    } else if (
      data[i].kind == "string" &&
      data[i].type.match("^text/uri-list")
    ) {
      // Drag data item is URI
      data[i].getAsString(function (s) {
        console.log("... Drop: URI = " + s);
      });
    }
  }
}

function dragover\_handler(ev) {
  console.log("dragOver");
  ev.preventDefault();
  // Set the dropEffect to move
  ev.dataTransfer.dropEffect = "move";
}

function dragend\_handler(ev) {
  console.log("dragEnd");
  var dataList = ev.dataTransfer.items;
  // Clear any remaining drag data
  dataList.clear();
}
```

### HTML

```html
<div>
  <p
 id="source"
 ondragstart="dragstart\_handler(event);"
 ondragend="dragend\_handler(event);"
 draggable="true">
    Select this element, drag it to the Drop Zone and then release the selection
    to move the element.
  </p>
</div>
<div
 id="target"
 ondrop="drop\_handler(event);"
 ondragover="dragover\_handler(event);">
  Drop Zone
</div>
```

### CSS

```css
div {
  margin: 0em;
  padding: 2em;
}

#source {
  color: blue;
  border: 1px solid black;
}

#target {
  border: 1px solid black;
}
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransferitemlist-length-dev |

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

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


结构化克隆算法 - Web API 接口参考

结构化克隆算法
=======

**结构化克隆算法**用于复制复杂 JavaScript 对象的算法。通过来自 Worker 的 `postMessage()` 或使用 IndexedDB 存储对象时在内部使用。它通过递归输入对象来构建克隆，同时保持先前访问过的引用的映射，以避免无限遍历循环。

结构化克隆所不能做到的
-----------

* `Function` 对象是不能被结构化克隆算法复制的；如果你尝试这样子去做，这会导致抛出 `DATA_CLONE_ERR` 的异常。
* 企图去克隆 DOM 节点同样会抛出 `DATA_CLONE_ERR` 异常。
* 对象的某些特定参数也不会被保留
    + `RegExp` 对象的 `lastIndex` 字段不会被保留
    + 属性描述符，setters 以及 getters（以及其他类似元数据的功能）同样不会被复制。例如，如果一个对象用属性描述符标记为 read-only，它将会被复制为 read-write，因为这是默认的情况下。
    + 原形链上的属性也不会被追踪以及复制。
支持的类型
-----

### JavaScript 类型

* `Array`
* `ArrayBuffer`
* `Boolean`
* `DataView`
* `Date`
* `Error` 类型（仅限部分 Error 类型）。
* `Map`
* `Object` 对象：仅限简单对象（如使用对象字面量创建的）。
* 除 `symbol` 以外的基本类型。
* `RegExp`：`lastIndex` 字段不会被保留。
* `Set`
* `String`
* `TypedArray`

#### Error 类型

仅支持以下 `Error` 类型：Error、EvalError、RangeError、ReferenceError、SyntaxError、TypeError、URIError（或其他会被设置为 `Error` 的）。

浏览器必须序列化 `name` 和 `message` 字段，其他有意义的字段则可能会序列化，如 `stack`、`cause` 等。

AggregateError 预计会在 whatwg/html#5749 被添加到标准中（并且已被部分浏览器所支持）。

参见
--

* HTML 规范：安全地传递结构化数据
* 可转移对象
* `structuredClone()`
* `window.history`
* `window.postMessage()`
* Web Worker
* IndexedDB