Node.nodeType - Web API 接口参考

Node.nodeType
=============

只读属性 **`Node.nodeType`** 表示的是该节点的类型。

描述
--

**`nodeType`** 属性可用来区分不同类型的节点，比如 `元素`, `文本` (en-US) 和 `注释`。

语法
--
```

var type = node.nodeType;
```

返回一个整数，其代表的是节点类型。其所有可能的值请参考 节点类型常量.

常量
--

### 节点类型常量

| 常量 | 值 | 描述 |
| --- | --- | --- |
| `Node.ELEMENT_NODE` | `1` | 一个 `元素` 节点，例如 `<p>` 和 `<div>`。 |
| `Node.ATTRIBUTE_NODE` | 2 | `元素` 的耦合 `属性`。 |
| `Node.TEXT_NODE` | `3` | `Element` 或者 `Attr` 中实际的 `文字` (en-US) |
| `Node.CDATA_SECTION_NODE` | `4` | 一个 `CDATASection`，例如 `<!CDATA[[ … ]]>`。 |
| `Node.PROCESSING_INSTRUCTION_NODE` | `7` | 一个用于 XML 文档的 `ProcessingInstruction` (en-US) ，例如 `<?xml-stylesheet ... ?>` 声明。 |
| `Node.COMMENT_NODE` | `8` | 一个 `Comment` 节点。 |
| `Node.DOCUMENT_NODE` | `9` | 一个 `Document` 节点。 |
| `Node.DOCUMENT_TYPE_NODE` | `10` | 描述文档类型的 `DocumentType` 节点。例如 `<!DOCTYPE html>` 就是用于 HTML5 的。 |
| `Node.DOCUMENT_FRAGMENT_NODE` | `11` | 一个 `DocumentFragment` 节点 |
|  |  |  |

以下的常量已被弃用且不再使用：`Node.ENTITY_REFERENCE_NODE`（`5`）、`Node.ENTITY_NODE`（`6`）和 `Node.NOTATION_NODE`（`12`）。

示例
--

### 不同的节点类型

```js
document.nodeType === Node.DOCUMENT\_NODE; // true
document.doctype.nodeType === Node.DOCUMENT\_TYPE\_NODE; // true

var fragment = document.createDocumentFragment();
fragment.nodeType === Node.DOCUMENT\_FRAGMENT\_NODE; // true

var p = document.createElement("p");
p.textContent = "很久很久以前...";

p.nodeType === Node.ELEMENT\_NODE; // true
p.firstChild.nodeType === Node.TEXT\_NODE; // true
```

### 注释

该示例会检查 document 下第一个节点是不是注释，如果不是，则会提醒。

```js
var node = document.documentElement.firstChild;
if (node.nodeType != Node.COMMENT\_NODE) console.log("你应该认真编写代码注释！");
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-nodetype① |


Node.isSameNode - Web API 接口参考

Node.isSameNode
===============

概述
--

判断两个节点是否是相同的节点，即指向同一个对象。

**警告：** 该方法已在 DOM level 4 中被废弃，最近的浏览器版本 (Gecko 10.0) 已经删除了这个方法。也就是说，不要再使用 `node1.isSameNode(node2)` 而使用 `node1 === node2` 或者 `node1 == node2` 来代替。

语法
--

```js
var isSameNode = node.isSameNode(other);
```

* `other` 是要和 `node` 判断相同性的另一个节点。
规范
--

* DOM Level 3 Core: isSameNode
* This has been removed from DOM Core Level 4


Node.baseURI - Web API 接口参考

Node.baseURI
============

**`Node.baseURI`** 是只读属性，返回一个节点的绝对基址 URL。

当浏览器要获取绝对 URL 时，就需要用基 URL 去解析相对 URL。例如，解析 HTML `<img>` 元素的 `src` 属性时，或者 处理 XML `xlink:href` 属性时—。

一般情况下，基 URL 是 document 的 location，但是它受诸多方面因素的影响，例如 HTML 的 `<base>` 元素和 XML `xml:base` (en-US) 属性。

语法
--
```

var baseURI = node.baseURI;
```

* `baseURI` 是一个 `DOMString` 代表当前 `节点` 所在文档的基 URI。如果无法获取则可能返回 `null` 。
* `node.baseURI` 是只读的。
* `node.baseURI` 可能会随时间发生变化。
概述
--

### 文档的基 URL

*document* 的默认基 URL 是文档的地址（浏览器显示的地址，可以通过`window.location` 获取），但是可以通过如下方法修改：

* 当在文档中找到一个 `<base>` 标签时；
* 当一个文档被动态创建时。

详细信息请参阅 HTML Living standard 中关于基 URL 的章节 。

可以通过 ``document`.baseURI` 获取文档的基 URL。注意检查文档的基 URL 可能会每次请求返回不同的结果，因为 `<base>` 标签或文档的 location 可能被改变了。

### 元素的基 URL

元素的基 URL 一般和其所在的文档相同。

如果文档中有 `xml:base` (en-US) 属性（不要在 HTML 文档中这样做），在 `node.baseURI` 计算基 URL 时，会把 `xml:base` 属性考虑进去。参考 xml:base (en-US) 来了解更多。

可以通过 ``element`.baseURI` 获取某个元素的基 URL。

规范
--

DOM Level 3 Core: baseURI

参考
--

* `<base>` 元素（HTML）
* `xml:base` (en-US) 属性（XML 文档）
* `Node.baseURIObject` (en-US) - a variant of this API for Mozilla add-ons and internal code. Returns the base URL as an `nsIURI`.


Node.insertBefore() - Web API 接口参考

Node.insertBefore()
===================

**`Node.insertBefore()`** 方法在参考节点之前插入一个拥有指定父节点的子节点。如果给定的子节点是对文档中现有节点的引用，`insertBefore()` 会将其从当前位置移动到新位置（在将节点附加到其他节点之前，不需要从其父节点删除该节点）。

这意味着一个节点不能同时位于文档的两个点中。因此，如果被插入节点已经有父节点，则首先删除该节点，然后将其插入到新位置。若要保留已在文档中的被插入节点，在将该节点追加到新父节点之前，可以使用 `Node.cloneNode()` 复制节点。注意，使用 `cloneNode()` 创建的节点副本不会自动与原始节点保持同步。

如果引用节点为 `null`，则将指定的节点添加到指定父节点的子节点列表的末尾。

如果给定的子节点是 `DocumentFragment`，那么 `DocumentFragment` 的全部内容将被移动到指定父节点的子节点列表中。

语法
--

```js
var insertedNode = parentNode.insertBefore(newNode, referenceNode);
```

* `insertedNode` 被插入节点 (newNode)
* `parentNode` 新插入节点的父节点
* `newNode` 用于插入的节点
* `referenceNode` `newNode` 将要插在这个节点之前

如果 `referenceNode` 为 `null` 则 `newNode` 将被插入到子节点的末尾\*。\*

**备注：** `referenceNode` 引用节点**不是**可选参数——你必须显式传入一个 `Node` 或者 `null`。如果不提供节点或者传入无效值，在不同的浏览器中会有不同的表现。

返回值
---

函数返回被插入过的子节点；当 `newNode` 是 `DocumentFragment` 时，返回空 `DocumentFragment`。

例子
--

### 示例 1

```js
<div id="parentElement">
   <span id="childElement">foo bar</span>
</div>

<script>
// 创建要插入的节点
var newNode = document.createElement("span");

// 获得父节点的引用
var parentDiv = document.getElementById("childElement").parentNode;

//实验一：referenceNode 存在 --> 正确返回
var sp2 = document.getElementById("childElement");
parentDiv.insertBefore(newNode, sp2);
//实验一结束

//实验二：referenceNode 为 undefined
var sp2 = undefined; // Not exist a node of id "childElement"
parentDiv.insertBefore(newNode, sp2); //隐式转换到节点类型
//实验二结束

//实验三：referenceNode 为字符类型的 "undefined"
var sp2 = "undefined"; //不存在 id 为"childElement"的 referenceNode
parentDiv.insertBefore(newNode, sp2); // Generate "Type Error: Invalid Argument"
//实验三结束
</script>
```

### 示例 2

```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 //创建一个新的、普通的<span>元素
 var sp1 = document.createElement("span");

 //插入节点之前，要获得节点的引用
 var sp2 = document.getElementById("childElement");
 //获得父节点的引用
 var parentDiv = sp2.parentNode;

 //在 DOM 中在 sp2 之前插入一个新元素
 parentDiv.insertBefore(sp1, sp2);
</script>
```

没有 `insertAfter()`。不过，可以使用 `insertBefore` 和 `Node.nextSibling` 来模拟它。

在前一个例子中，可使用下面代码将 `sp1` 插入到 `sp2` 之后：

```js
parentDiv.insertBefore(sp1, sp2.nextSibling);
```

如果 `sp2` 没有下一个节点，则它肯定是最后一个节点，则 `sp2.nextSibling` 返回 `null`，且 `sp1` 被插入到子节点列表的最后面（即 `sp2` 后面）。

### 示例 3

在第一个子元素的前面插入一个元素，可使用 firstChild 属性。

```js
//插入节点之前，要获得节点的引用
var parentElement = document.getElementById("parentElement");
//获得第一个子节点的引用
var theFirstChild = parentElement.firstChild;

//创建新元素
var newElement = document.createElement("div");

//在第一个子节点之前插入新元素
parentElement.insertBefore(newElement, theFirstChild);
```

当元素没有首节点时，`firstChild` 返回 `null`。该元素仍然会被插入到父元素中，位于最后一个节点后面。又由于父元素没有第一个子节点，也没有最后一个子节点。最终，新元素成为唯一的子元素。

规范
--

| Specification |
| --- |
| DOM Standard # dom-node-insertbefore |

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

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

参见
--

* `Node.removeChild()`
* `Node.replaceChild()`
* `Node.appendChild()`
* `Node.hasChildNodes()`
* `Element.insertAdjacentElement()`
* `ParentNode.prepend()` (en-US)


Node.nodeName - Web API 接口参考

Node.nodeName
=============

概述
返回当前节点的节点名称

语法
--
```

var str = node.nodeName;
```

* `str` 是一个存储了当前节点的节点名称的字符串。
* `nodeName 是一个只读属性`.
附注
--

下表列出了所有类型的节点的`nodeName`属性的值。

| 接口 | nodeName 属性值 |
| --- | --- |
| Attr (en-US) | 等同于 `Attr.name` 属性的值 |
| CDATASection (en-US) | "#cdata-section" |
| Comment (en-US) | "#comment" |
| Document | "#document" |
| DocumentFragment (en-US) | "#document-fragment" |
| DocumentType (en-US) | 等同于 `DocumentType.name` 属性的值 |
| Element | 等同于 `Element.tagName` 属性的值 |
| Entity | 实体名称 |
| EntityReference | 实体引用名称 |
| Notation | Notation 名称 |
| ProcessingInstruction (en-US) | 等同于 `ProcessingInstruction.target` 属性的值 |
| text (en-US) | "#text" |

示例
--

假设已经存在下面的 HTML:

```html
<div id="d1">hello world</div>
<input type="text" id="t" />
```

以及下面的 JavaScript:

```js
var div1 = document.getElementById("d1");
var text_field = document.getElementById("t");

text_field.value = div1.nodeName;
```

在 XHTML(以及属于 XML 类型的文档) 中，变量 `text_field` 包含的值会是小写的"div".还在 HTML 中，变量 `text_field`包含的值会是大写的"DIV", `nodeName` 和 `tagName` 属性都有这种表现。查看details on nodeName case sensitivity in different browsers一文深入了解。

如果是元素节点，`nodeName` 属性和 `tagName` 属性返回相同的值，但如果是文本节点，`nodeName` 属性会返回 `"#text"`，而 `tagName` 属性会返回 `undefined`。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-nodename① |


Node.lookupPrefix - Web API 接口参考

Node.lookupPrefix
=================

返回一个和指定命名空间 URI 绑定的命名空间前缀。如果没有，返回 `null`。如果有多个绑定的前缀，返回的结果根据浏览器实现而定。

根据 bug 312019, 该方法对动态指定的命名空间不起作用.(也就是通过Node.prefix指定的).

### 相关链接

* http://www.w3.org/TR/DOM-Level-3-Cor...amespacePrefix
* Code snippets: lookupPrefix


Node：selectstart 事件 - Web API 接口参考

Node：selectstart 事件
===================

Selection API 的 **`selectstart`** 事件在用户进行一个新的选择时触发。

如果事件被取消，所选取内容将不会改变。

语法
--

在类似于 `addEventListener()` 这样的方法中使用事件名称，或设置事件处理器属性。

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

onselectstart = (event) => {};
```

事件类型
----

通用的 `Event`。

示例
--

```js
// addEventListener 版本
document.addEventListener("selectstart", () => {
  console.log("已开始选择");
});

// onselectstart 版本
document.onselectstart = () => {
  console.log("已开始选择");
};
```

规范
--

| Specification |
| --- |
| Selection API # selectstart-event |
| Selection API # dom-globaleventhandlers-onselectstart |

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

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

参见
--

* `selectionchange`


Node.compareDocumentPosition - Web API 接口参考

Node.compareDocumentPosition
============================

**`Node.compareDocumentPosition()`** 可以比较当前节点与任意文档中的另一个节点的位置关系。

返回值是一个具有以下值的位掩码：

| 常量名 | 十进制值 | 含义 |
| --- | --- | --- |
| `DOCUMENT_POSITION_DISCONNECTED` | 1 | 不在同一文档中 |
| `DOCUMENT_POSITION_PRECEDING` | 2 | otherNode 在 node 之前 |
| `DOCUMENT_POSITION_FOLLOWING` | 4 | otherNode 在 node 之后 |
| `DOCUMENT_POSITION_CONTAINS` | 8 | otherNode 包含 node |
| `DOCUMENT_POSITION_CONTAINED_BY` | 16 | otherNode 被 node 包含 |
| `DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC` | 32 | 待定 |

语法
--
```

compareMask = node.compareDocumentPosition( otherNode )
```

### 参数

`otherNode`

用于比较位置的 `Node` 。

### 返回值

一个表示 `Node` 和 `otherNode` 在 `Document` 中关系的整数值。在一些场景下，可能设置了不止一位比特值。比如 `otherNode` 在文档中是靠前的且包含了 `Node`, 那么`DOCUMENT_POSITION_CONTAINS` 和 `DOCUMENT_POSITION_PRECEDING` 位都会设置，所以结果会是 0x0A 即十进制下的 10。

例子
--

```js
var head = document.getElementsByTagName("head").item(0);
if (
  head.compareDocumentPosition(document.body) & Node.DOCUMENT\_POSITION\_FOLLOWING
) {
  console.log("well-formed document");
} else {
  console.log("<head> is not before <body>");
}
```

**备注：** 因为`compareDocumentPosition`返回的是一个位掩码，所以必须再使用按位与运算符 (en-US)才能得到有意义的值。

注意第一条语句使用了带有参数 0 的 `NodeList.item()` 方法，它和 getElementsByTagName('head')[0] 是一样的。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-comparedocumentposition① |

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

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

相关链接
----

* `Node.contains`
* John Resig - Comparing Document Position


Node.lastChild - Web API 接口参考

Node.lastChild
==============

概述
--

**`Node.lastChild`** 是一个只读属性，返回当前节点的最后一个子节点。如果父节点为一个元素节点，则子节点通常为一个元素节点，或一个文本节点，或一个注释节点。如果没有子节点，则返回 `null`。

语法
--
```

var last_child = element.lastChild
```

示例
--

```js
var tr = document.getElementById("row1");
var corner_td = tr.lastChild;
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-lastchild① |


Node.textContent - Web API 接口参考

Node.textContent
================

`Node` 接口的 **`textContent`** 属性表示一个节点及其后代的文本内容。

**备注：** `textContent` 和 `HTMLElement.innerText` 容易混淆，但这两个属性在重要方面有不同之处 。

语法
--
```

let text = someNode.textContent;
someOtherNode.textContent = string;
```

### 返回值

一个字符串或 `null`.

描述
--

`textContent` 的值取决于具体情况：

* 如果节点是一个 `document`，或者一个 DOCTYPE ，则 `textContent` 返回 `null`。

**备注：** 如果你要获取整个文档的文本以及 CDATA data ，可以使用 `document.documentElement.textContent`。
* 如果节点是个 CDATA section、注释、processing instruction (en-US) 或者 text node，`textContent` 返回节点内部的文本内容，例如 `Node.nodeValue`。
* 对于其他节点类型，`textContent` 将所有子节点的 `textContent` 合并后返回，除了注释和 processing instructions。（如果该节点没有子节点的话，返回一个空字符串。）

在节点上设置 `textContent` 属性的话，会删除它的所有子节点，并替换为一个具有给定值的文本节点。

### 与 **innerText** 的区别

不要对 `Node.textContent` 和 `HTMLElement.innerText` 之间的差异感到困惑。虽然名字看起来很相似，但有重要的不同之处：

* `textContent` 会获取*所有*元素的内容，包括 `<script>` 和 `<style>` 元素，然而 `innerText` 只展示给人看的元素。
* `textContent` 会返回节点中的每一个元素。相反，`innerText` 受 CSS 样式的影响，并且不会返回隐藏元素的文本，
    + 此外，由于 `innerText` 受 CSS 样式的影响，它会触发回流（ reflow ）去确保是最新的计算样式。（回流在计算上可能会非常昂贵，因此应尽可能避免。）
* 与 `textContent` 不同的是，在 Internet Explorer (小于和等于 11 的版本) 中对 `innerText` 进行修改，不仅会移除当前元素的子节点，而且还会*永久性地破坏*所有后代文本节点。在之后不可能再次将节点再次插入到任何其他元素或同一元素中。
### 与 **innerHTML** 的区别

正如其名称，`Element.innerHTML` 返回 HTML。通常，为了在元素中检索或写入文本，人们使用 `innerHTML`。但是，`textContent` 通常具有更好的性能，因为文本不会被解析为 HTML。

此外，使用 `textContent` 可以防止 XSS 攻击。

示例
--

给出这个 HTML 片段：

```html
<div id="divA">This is <span>some</span> text!</div>
```

你可以使用 `textContent` 去获取该元素的文本内容：

```js
let text = document.getElementById("divA").textContent;
// The text variable is now: 'This is some text!'
```

或者设置元素的文字内容：

```js
document.getElementById("divA").textContent = "This text is different!";
// The HTML for divA is now:
// <div id="divA">This text is different!</div>
```

IE8 的替代方法
---------

```js
// Source: Eli Grey @ https://eligrey.com/blog/post/textcontent-in-ie8
if (
  Object.defineProperty &&
  Object.getOwnPropertyDescriptor &&
  Object.getOwnPropertyDescriptor(Element.prototype, "textContent") &&
  !Object.getOwnPropertyDescriptor(Element.prototype, "textContent").get
) {
  (function () {
    var innerText = Object.getOwnPropertyDescriptor(
      Element.prototype,
      "innerText",
    );
    Object.defineProperty(
      Element.prototype,
      "textContent",
      // Passing innerText or innerText.get directly does not work,
      // wrapper function is required.
      {
        get: function () {
          return innerText.get.call(this);
        },
        set: function (s) {
          return innerText.set.call(this, s);
        },
      },
    );
  })();
}
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-node-textcontent |

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

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

参见
--

* `HTMLElement.innerText`
* `Element.innerHTML`
* More on differences between `innerText` and `textContent` (blog post)


TransformStreamDefaultController.terminate() - Web API 接口参考

TransformStreamDefaultController.terminate()
============================================

`TransformStreamDefaultController` 接口的 **`terminate()`** 方法用于关闭流的可读端并且会使流的可写端出错。

语法
--

```js
terminate()
```

### 参数

无。

### 返回值

无（`undefined`）。

示例
--

在以下示例中，调用了 `TransformStreamDefaultController` 的 `terminate()` 方法。

```js
controller.terminate();
```

规范
--

| Specification |
| --- |
| Streams Standard # ts-default-controller-terminate |

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

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


TransformStreamDefaultController.enqueue() - Web API 接口参考

TransformStreamDefaultController.enqueue()
==========================================

`TransformStreamDefaultController` 接口的 **`enqueue()`** 方法将给定的分块排入流的可读端。

有关可读流和分块的更多信息，请参见使用可读流。

语法
--

```js
enqueue(chunk)
```

### 参数

`chunk`

正在排入的分块。一个分块是一个数据片段。它可以是任何数据类型，并且一个流可以包含不同类型的分块。

### 返回值

无（`undefined`）。

### 异常

`TypeError`

流不可读。如果流通过 `controller.error()` 发生错误，或者在没有调用它的控制器的 `controller.close()` 方法的情况下下关闭流，则可能发生这种情况。

示例
--

在此示例中，使用 `enqueue()` 方法将编码的分块传递给队列。

```js
const textEncoderStream = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(new TextEncoder().encode(chunk));
  },
  flush(controller) {
    controller.terminate();
  },
});
```

规范
--

| Specification |
| --- |
| Streams Standard # ts-default-controller-enqueue |

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

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


TransformStreamDefaultController.desiredSize - Web API 接口参考

TransformStreamDefaultController.desiredSize
============================================

`TransformStreamDefaultController` 接口的只读属性 **`desiredSize`** 返回填充满关联的 `ReadableStream` 的内部队列所需要的大小。

`ReadableStream` 的内部队列包含已入队但尚未读取的分块。浏览器确定填满流**所需要的大小**，并且这个值由 `desiredSize` 属性返回。

如果这个 `desiredSize` 是 `0`，则队列已满。因此你可以使用这个信息去手动管理背压去管理队列。

值
-

所需的大小。

示例
--

在下面的示例中，`desiredSize` 被打印到控制台。

```js
console.log(controller.desiredSize);
```

规范
--

| Specification |
| --- |
| Streams Standard # ts-default-controller-desired-size |

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

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


TransformStreamDefaultController.error() - Web API 接口参考

TransformStreamDefaultController.error()
========================================

`TransformStreamDefaultController` 接口的 **`error()`** 方法会使流的两端出错。与它的进一步交互都会失败并携带给定的错误信息，并且队列中的任何分块都将被丢弃。

语法
--

```js
error(reason)
```

### 参数

`reason`

一个字符串，包含在与流进一步交互时返回的错误信息。

### 返回值

无（`undefined`）。

示例
--

在这个示例中，当一个分块中包含 symbol 时，`error()` 方法被使用。

```js
case 'symbol':
  controller.error("Cannot send a symbol as a chunk part")
  break
```

规范
--

| Specification |
| --- |
| Streams Standard # ts-default-controller-error |

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

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


MessageChannel.port1 - Web API 接口参考

MessageChannel.port1
====================

`MessageChannel` 的只读属性 **`port1`** 返回消息通道的第一个端口，此端口连接到源上下文通道。

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

语法
--
```

channel.port1;
```

### Value

一个 `MessagePort` 对象，通道的第一个端口，此端口连接到源上下文通道。

示例
--

在以下代码块中，你可以看到使用 `MessageChannel()` 构造函数创建的新通道。当 `<iframe>` 加载完毕，我们使用 `MessagePort.postMessage` (en-US) 方法把一条消息和 `MessageChannel.port2` 传递给 `<iframe>`。handleMessage 处理程序将会从 <iframe> 中（使用 `MessagePort.onmessage` 监听事件）接收到信息，将数据其放入一个段落。handleMessage 方法关联到 port1 用于监听收到的消息。

```js
var channel = new MessageChannel();
var para = document.querySelector("p");

var ifr = document.querySelector("iframe");
var otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Hello from the main page!", "\*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}
```

一个完整的运行示例，可以在 GitHub 上查看 channel messaging basic demo (run it live too).

规范
--

| Specification |
| --- |
| HTML Standard # dom-messagechannel-port1-dev |

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

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

参考
--

* Using channel messaging


MessageChannel.port2 - Web API 接口参考

MessageChannel.port2
====================

`MessageChannel`接口的 **`port2`** 是一个只读属性，返回消息通道的第二个端口，该端口连接到通道另一端的上下文，也就是发送消息时的目的地。

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

语法
--
```

channel.port2;
```

### 值

表示通道第二个端口的一个`MessagePort`对象，该端口附加到通道另一端的上下文。

示例
--

如下代码所示，通过`MessageChannel.MessageChannel`构造函数创建了一个新的通道。当 IFrame 加载完毕，我们使用`MessagePort.postMessage` (en-US)将一条消息以及 port2 传递给 IFrame。handleMessage 处理程序响应从 IFrame 发回的消息（使用 `MessagePort.onmessage`），将其放入段落中。`MessageChannel.port1`已经监听，以检测消息何时到达。

```js
var channel = new MessageChannel();
var para = document.querySelector("p");

var ifr = document.querySelector("iframe");
var otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Hello from the main page!", "\*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}
```

有关完整的运行示例，请参阅我们在 GitHub 的 channel messaging basic demo (run it live too).

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

| Specification |
| --- |
| HTML Standard # dom-messagechannel-port2-dev |

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

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

See also
--------

* Using channel messaging


MessageChannel() - Web API 接口参考

MessageChannel()
================

`MessageChannel` 接口的 `MessageChannel()` 构造函数返回一个新的 `MessageChannel` 对象，返回的对象中包含两个 `MessagePort` 对象。

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

语法
--

```js
new MessageChannel();
```

### 返回值

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

例子
--

在下面的代码块中，你会看到一个由 `MessageChannel.MessageChannel` 构造函数创建的新 Channel. 当 IFrame 被加载后，我们使用 `MessagePort.postMessage` (en-US) 把 `port2` 和一条消息一起发送给 IFrame. 然后 `handleMessage` 回调响应 IFrame 发回的消息（使用 `MessagePort.onmessage`），并把它渲染到页面段落中。`MessageChannel.port1` 用来监听，当消息到达时，会进行处理。

```js
var channel = new MessageChannel();
var para = document.querySelector("p");

var ifr = document.querySelector("iframe");
var otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Hello from the main page!", "\*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}
```

有关更完整的运行示例，可以在 GitHub 上查看 channel messaging 基本示例（也可以在线运行示例）。

规范
--

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

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

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

参见
--

* 使用 channel messaging


load() - Web API 接口参考

load()
======

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

该`MediaKeySession.load()`方法返回一个`Promise`，它在加载指定的会话对象的数据后解析为一个布尔值。

句法
--
```

mediaKeySession .load(sessionId).then(function(booleanValue){...});
```

### 参数

sessionId

由当前媒体对象及其相关键或许可证的内容解析模块生成的唯一字符串。

### 返回值

一个`Promise`解析为一个布尔值，指示加载是成功还是失败。

规范
--

| Specification |
| --- |
| Encrypted Media Extensions # dom-mediakeysession-load |

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

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


AudioBufferSourceNode.start() - Web API 接口参考

AudioBufferSourceNode.start()
=============================

`AudioBufferSourceNode` 接口的`start()`方法用于计划对缓冲区中包含的音频数据的回放，或者立即开始回放。

语法
--
```

AudioBufferSourceNode.start([when][, offset][, duration]);
```

### 参数

`when` 可选

The time 声音开始播放的时间，单位是秒，与 `AudioContext`使用相同的时间坐标系统。如果 `when` 小于 (`AudioContext.currentTime`, 或者是 0，声音立即被播放。 **默认值是 0。**

`offset` 可选

An offset, specified as the number of seconds in the same time coordinate system as the `AudioContext`, to the time within the audio buffer that playback should begin. For example, to start playback halfway through a 10-second audio clip, `offset` should be 5. The default value, 0, will begin playback at the beginning of the audio buffer, and offsets past the end of the audio which will be played (based on the audio buffer's `duration` and/or the `loopEnd` (en-US) property) are silently clamped to the maximum value allowed. The computation of the offset into the sound is performed using the sound buffer's natural sample rate, rather than the current playback rate, so even if the sound is playing at twice its normal speed, the midway point through a 10-second audio buffer is still 5.

`duration` 可选

将要播放的声音的持续时间，指定单位为秒。如果这个参数没有被指定，声音播放到自然结束或者使用`stop()` 方法结束。使用这个参数的功能与调用 `start(when, offset)` 和调用 `stop(when+duration)`完全相同。

### 返回值

`undefined`.

### 异常

`TypeError`

A negative value was specified for one or more of the three time parameters. Please don't attempt to tamper with the laws of temporal physics.

`InvalidStateError`

`start()` 已经被调用。在一个`AudioBufferSourceNode`的生命周期内只能调用一次这个函数。

例子
--

The most simple example just starts the audio buffer playing from the beginning — you don't need to specify any parameters in this case:

```js
source.start();
```

The following more complex example will, 1 second from now, start playing 10 seconds worth of sound starting 3 seconds into the audio buffer.

```js
source.start(audioCtx.currentTime + 1, 3, 10);
```

**备注：** For a more complete example showing `start()` in use, check out our `AudioContext.decodeAudioData()` example, You can also run the code example live, or view the source.

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

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-start |

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

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

See also
--------

* Using the Web Audio API


AudioBufferSourceNode.buffer - Web API 接口参考

AudioBufferSourceNode.buffer
============================

`AudioBufferSourceNode` 接口的 **`buffer`** 属性提供了重复播放音频的能力，该音频使用 `AudioBuffer` 作为声音文件的来源。

如果 `buffer` 属性的值为 `null`，节点会自动生成一个单声道的无声文件（所有采样均为 0）。

值
-

一个 `AudioBuffer`，包含了节点将要播放的声音数据。

示例
--

**备注：** 完整的示例请查看演示示例，或查看源代码。

```js
const myArrayBuffer = audioCtx.createBuffer(2, frameCount, audioCtx.sampleRate);

button.onclick = function() {
  // Fill the buffer with white noise;
  //just random values between -1.0 and 1.0
  for (let channel = 0; channel < channels; channel++) {
   // This gives us the actual ArrayBuffer that contains the data
   const nowBuffering = myArrayBuffer.getChannelData(channel);
   for (let i = 0; i < frameCount; i++) {
     // Math.random() is in [0; 1.0]
     // audio needs to be in [-1.0; 1.0]
     nowBuffering[i] = Math.random() \* 2 - 1;
   }
  }

  // Get an AudioBufferSourceNode.
  // This is the AudioNode to use when we want to play an AudioBuffer
  const source = audioCtx.createBufferSource();
  // set the buffer in the AudioBufferSourceNode
  source.buffer = myArrayBuffer;
```

规范
--

| Specification |
| --- |
| Web Audio API # dom-audiobuffersourcenode-buffer |

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

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

参见
--

* 使用 Web Audio API
* Web Audio API


GainNode.gain - Web API 接口参考

GainNode.gain
=============

`GainNode` 接口的 `gain` 属性是一个 a-rate `AudioParam`，表示要应用的增益量。

值
-

一个 `AudioParam`。

**备注：** 虽然 `AudioParam` 属性是只读的，但其返回的值不是。

示例
--

参见 `BaseAudioContext.createGain()` (en-US) 以获取示例代码，示例代码展示了如何使用 `AudioContext` 来创建 `GainNode`，并通过修改其 gain 属性值以静音或取消静音。

规范
--

| Specification |
| --- |
| Web Audio API # dom-gainnode-gain |

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

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

参见
--

* 使用 Web Audio API


FontData：style 属性 - Web API 接口参考

FontData：style 属性
=================

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

`FontData` 接口的 **`style`** 只读属性返回字体的样式。

这是用于选择要使用的字体样式的值，例如在 `font-style` 属性内。

示例包括：

* UltraLight
* Regular
* Heavy
* Medium Italic
* Extrabold
值
-

一个字符串。

示例
--

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

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

规范
--

| Specification |
| --- |
| Local Font Access # ref-for-dom-fontdata-style |

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

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

参见
--

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


FontData：family 属性 - Web API 接口参考

FontData：family 属性
==================

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

`FontData` 接口的 **`family`** 只读属性返回字体的字体族。

这是在代码中引用字体族时使用的名称，例如在 `font-family` 属性中或在 `@font-face` at-规则中，如 `local()` 函数。

示例包括：

* Apple SD Gothic Neo
* Arial Black
* Avenir Next
* Katari
* YuMincho +36p Kana
值
-

一个字符串。

示例
--

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

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

规范
--

| Specification |
| --- |
| Local Font Access # ref-for-dom-fontdata-family |

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

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

参见
--

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


FontData：fullName 属性 - Web API 接口参考

FontData：fullName 属性
====================

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

`FontData` 接口的 **`fullName`** 只读属性返回字体的全名。这通常是一个用于识别字体的人类可读的名称，例如：“Optima Bold”。

示例包括：

* Apple SD Gothic Neo UltraLight
* Arial Black
* Avenir Next Heavy
* Katari Medium Italic
* YuMincho +36p Kana Extrabold
值
-

一个字符串。

示例
--

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

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

规范
--

| Specification |
| --- |
| Local Font Access # ref-for-dom-fontdata-fullname |

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

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

参见
--

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


FontData：blob() 方法 - Web API 接口参考

FontData：blob() 方法
==================

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

`FontData` 接口的 **`blob()`** 方法返回一个会兑现包含底层字体文件的原始字节的 `Blob` 的 `Promise`。

语法
--

```js
blob()
```

### 参数

无。

### 返回值

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

示例
--

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

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

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

规范
--

| Specification |
| --- |
| Local Font Access # ref-for-dom-fontdata-blob① |

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

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

参见
--

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


FontData：postscriptName 属性 - Web API 接口参考

FontData：postscriptName 属性
==========================

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

`FontData` 接口的 **`postscriptName`** 只读属性返回字体的 PostScript 名称。

这是用于唯一标识字体的 PostScript 名称，通常是包含字体名称和样式的完整字符序列。

示例包括：

* AppleSDGothicNeo-UltraLight
* Arial-Black
* AvenirNext-Heavy
* Katari-MediumItalic
* YuMin\_36pKn-Extrabold
值
-

一个字符串。

示例
--

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

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

规范
--

| Specification |
| --- |
| Local Font Access # ref-for-dom-fontdata-postscriptname |

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

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

参见
--

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


HTMLHtmlElement.version - Web API 接口参考

HTMLHtmlElement.version
=======================

概述
--

它返回有关文档的\*\*文档类型定义（DTD）\*\*的版本信息。尽管此属性能够被*Mozilla*识别，但此属性的返回值始终是空字符串。

**备注：** 此属性已被 W3C 的**HTML 4.01 技术建议**声明弃用，赞成使用 DTD 来获取文档的版本信息。


IntersectionObserver.unobserve() - Web API 接口参考

IntersectionObserver.unobserve()
================================

`IntersectionObserver`的`unobserve()`
 方法命令`IntersectionObserver`停止对一个元素的观察。

语法
--

```js
IntersectionObserver.unobserve(target);
```

### 参数

`target`

要取消观察的目标，如果没有提供，方法不做任何事情，也不会抛出异常。

### 返回值

`undefined`.

例子
--

下面代码段展示了一个观察器被创建，一个元素被观察，以及取消观察的过程。

```js
var observer = new IntersectionObserver(callback);
observer.observe(document.getElementById("elementToObserve"));

/\* ... \*/

observer.unobserve(document.getElementById("elementToObserve"));
```

说明
--

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-unobserve |

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

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

参见
--

* Intersection Observer API
* `IntersectionObserver.observe()`


IntersectionObserver.rootMargin - Web API 接口参考

IntersectionObserver.rootMargin
===============================

`IntersectionObserver` 接口的只读属性 **`rootMargin`** 是与 CSS 属性`margin`语法相似的字符串 (string) 对象。在交叉检测开始之前，由`rootMargin 规定的矩形的每一边都会被添加至``root`元素的边框盒 (bounding box (en-US)) 的相应边。例如，这可以让你向外调整边界，使得目标元素被认为是 100% 可见的，即使此元素得一部分长或宽被裁剪，或者在边缘过于靠近根边框盒边界的情况下，将目标视为部分隐藏。

可参考交集的计算来深入了解 root margin 的工作原理或如何使其与根的边框盒进行协同工作。

语法
--
```

var marginString = IntersectionObserver.rootMargin;
```

### 值

一个字符串，形式与 CSS `margin`属性相似，包含了一条或一组根边框盒边的偏移量。这些偏移量会被添加至根边界盒与目标元素边界的交叉区域之前。

这个属性返回的字符串也许会与`IntersectionObserver`被配置时所指定的值有所差别。浏览器可以改变这些值。

如果 rootMargin 在对象初始化的时候未被指定，它将被设置成默认值 `"0px 0px 0px 0px"`，这将意味着在原根节点边界框与目标边界之间计算交叉值。交集的计算描述了 rootMargin 的更加深入的使用方法。

规范
--

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-rootmargin |

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

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


IntersectionObserver.disconnect() - Web API 接口参考

IntersectionObserver.disconnect()
=================================

`IntersectionObserver` 的`disconnect()`方法终止对所有目标元素可见性变化的观察。语法
--

```js
intersectionObserver.disconnect();
```

### 参数

None.

### 返回值

`undefined`.

说明
--

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-disconnect |

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

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

参考
--

* `observe()`
* `unobserve()`


IntersectionObserver.takeRecords() - Web API 接口参考

IntersectionObserver.takeRecords()
==================================

`IntersectionObserver` 的方法\*\*`takeRecords()`\*\* 返回一个 `IntersectionObserverEntry` 对象数组，每个对象的目标元素都包含每次相交的信息，可以显式通过调用此方法或隐式地通过观察者的回调自动调用。

**备注：** 如果使用回调来监视这些更改，则无需调用此方法。调用此方法会清除挂起的相交状态列表，因此不会运行回调。

语法
--
```

intersectionObserverEntries = intersectionObserver.takeRecords();
```

### 参数

None.

### 返回值

`IntersectionObserverEntry` 对象数组，每个对象包含目标元素与根每次的相交信息。

Examples
--------

<<<...>>>

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

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-takerecords |

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

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

See also
--------

* Intersection Observer API


IntersectionObserver.root - Web API 接口参考

IntersectionObserver.root
=========================

`root` 属性用来获取当前 `intersectionObserver` 实例的根元素。

语法
--
```

intersectionObserver.root;
```

规范
--

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-root |

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

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


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

IntersectionObserver.IntersectionObserver()
===========================================

\*\*`IntersectionObserver()`\*\*构造器创建并返回一个`IntersectionObserver`对象。如果指定`rootMargin`则会检查其是否符合语法规定，检查阈值以确保全部在 0.0 到 1.0 之间，并且阈值列表会按升序排列。如果阈值列表为空，则默认为一个 [0.0] 的数组。

语法
--
```

var observer = new IntersectionObserver(callback[, options]);
```

### 参数

`callback`

当元素可见比例超过指定阈值后，会调用一个回调函数，此回调函数接受两个参数：

`entries`

一个`IntersectionObserverEntry`对象的数组，每个被触发的阈值，都或多或少与指定阈值有偏差。

`observer`

被调用的`IntersectionObserver`实例。

`options` 可选

一个可以用来配置 observer 实例的对象。如果`options`未指定，observer 实例默认使用文档视口作为 root，并且没有 margin，阈值为 0%（意味着即使一像素的改变都会触发回调函数）。你可以指定以下配置：

`root`

监听元素的祖先元素`Element`对象，其边界盒将被视作视口。目标在根的可见区域的的任何不可见部分都会被视为不可见。

`rootMargin`

一个在计算交叉值时添加至根的边界盒 (bounding\_box (en-US)) 中的一组偏移量，类型为字符串 (string) ，可以有效的缩小或扩大根的判定范围从而满足计算需要。语法大致和 CSS 中的`margin` 属性等同; 可以参考 intersection root 和 root margin 来深入了解 margin 的工作原理及其语法。默认值是"0px 0px 0px 0px"。

`threshold`

规定了一个监听目标与边界盒交叉区域的比例值，可以是一个具体的数值或是一组 0.0 到 1.0 之间的数组。若指定值为 0.0，则意味着监听元素即使与根有 1 像素交叉，此元素也会被视为可见。若指定值为 1.0，则意味着整个元素都在可见范围内时才算可见。可以参考阈值来深入了解阈值是如何使用的。阈值的默认值为 0.0。

### 返回值

一个可以使用规定阈值监听目标元素可见部分与`root`交叉状况的新的`IntersectionObserver` 实例。调用自身的`observe()` 方法开始使用规定的阈值监听指定目标。

### 异常

`SyntaxError`

指定的`rootMargin`不存在。

RangeError

一个或多个阈值超出了 0.0 到 1.0 的范围。

规范
--

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-intersectionobserver |

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

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


IntersectionObserver.observe() - Web API 接口参考

IntersectionObserver.observe()
==============================

`IntersectionObserver` 对象的\*\*`observe()`\*\* 方法向 IntersectionObserver 对象监听的目标集合添加一个元素。一个监听者有一组阈值和一个根，但是可以监视多个目标元素，以查看这些目标元素可见区域的变化。调用`IntersectionObserver.unobserve()`方法可以停止观察元素。

当指定元素的可见区域超过监听者的可见区域阈值之一时（阈值列表`IntersectionObserver.thresholds` (en-US)），监听者的回调会被传入代表当前发生的交叉变化`IntersectionObserverEntry`并执行。请注意，这种设计允许通过调用一次回调，给回调传入 IntersectionObserverEntry 对象数组，来实现同时处理多个被监听元素的交叉变化。

语法
--

```js
IntersectionObserver.observe(targetElement);
```

### 参数

`targetElement`

 可见性区域被监控的元素`element`。
 此元素必须是根元素的后代 (如果根元素为视窗，则该元素必须被当前文档包含)。

### 返回值

`undefined`.

示例
--

```js
// Register IntersectionObserver
const io = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    // Add 'active' class if observation target is inside viewport
    if (entry.intersectionRatio > 0) {
      entry.target.classList.add("active");
    }
    // Remove 'active' class otherwise
    else {
      entry.target.classList.remove("active");
    }
  });
});

// Declares what to observe, and observes its properties.
const boxElList = document.querySelectorAll(".box");
boxElList.forEach((el) => {
  io.observe(el);
});
```

规范
--

| Specification |
| --- |
| Intersection Observer # dom-intersectionobserver-observe |

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

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

参考
--

* `IntersectionObserver.unobserve()`


PushManager.supportedContentEncodings - Web API 接口参考

PushManager.supportedContentEncodings
=====================================

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

`PushManager` 的只读静态方法 **`supportedContentEncodings`** 返回一组支持内容编码，可以用在加密信息中发送的消息。

值
-

一个字符串数组。

规范
--

| Specification |
| --- |
| Push API # dom-pushmanager-supportedcontentencodings |

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

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


PushManager.subscribe() - Web API 接口参考

PushManager.subscribe()
=======================

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

`PushManager` 的 **`subscribe()`** 接口订阅了一个推送服务。

返回一个 `Promise` 形式的 `PushSubscription` (en-US) 对象，该对象包含了推送订阅详情。如果当前 service worker 没有已存在的订阅，则会创建一个新的推送订阅。

语法
--
```

PushManager.subscribe(options).then(function(pushSubscription) { ... } );
```

### 参数

`options 可选`

`一个包含可选配置参数的对象。包含以下属性：`

* `userVisibleOnly`: 布尔值，表示返回的推送订阅将只能被用于对用户可见的消息。
* applicationServerKey：推送服务器用来向客户端应用发送消息的公钥。该值是应用程序服务器生成的签名密钥对的一部分，可使用在 P-256 曲线上实现的椭圆曲线数字签名（ECDSA）。可以是`DOMString` 或 `ArrayBuffer`。

### 返回值

返回 `PushSubscription` (en-US) 对象的 `Promise`。

示例
--
```

this.onpush = function(event) {
  console.log(event.data);
  // 这里可以向 IndexDB 写入数据，向任何打开的窗口发送数据以及显示通知等
}

navigator.serviceWorker.register('serviceworker.js').then(
  function(serviceWorkerRegistration) {
    var options = {
      userVisibleOnly: true,
      applicationServerKey: applicationServerKey
    };
    serviceWorkerRegistration.pushManager.subscribe(options).then(
      function(pushSubscription) {
        console.log(pushSubscription.endpoint);
        // 应用服务器所需的推送订阅详情现在可用，并且可以通过如 XMLHttpRequest 的方式发送
      }, function(error) {
        // 开发过程中将错误打印到控制台通常很有帮助。同样，生产环境下将错误信息发送至应用服务器后台也一样。
        console.log(error);
      }
    );
  });
```

规范
--

| Specification |
| --- |
| Push API # dom-pushmanager-subscribe |

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

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

另见
--

* 使用 Push API (en-US)


PushManager.getSubscription() - Web API 接口参考

PushManager.getSubscription()
=============================

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

`PushManager` 接口的方法\*\*`PushManager.getSubscription()`\*\* 尝试获取已有的推送订阅。

它返回一个 `Promise` 用来 resolve 出一个包含现有订阅的详细信息的`PushSubscription` (en-US) 对象。如果不存在已有的推送订阅，返回 null。

语法
--

```js
PushManager.getSubscription().then(function(pushSubscription) { ... } );
```

### 参数

无。

### 返回值

A `Promise` that resolves to a `PushSubscription` (en-US) object or `null`.

例子
--

这个代码片段来自 push messaging and notification sample. (没有能直接运行的例子.)

```js
// We need the service worker registration to check for a subscription
navigator.serviceWorker.ready.then(function (serviceWorkerRegistration) {
  // Do we already have a push message subscription?
  serviceWorkerRegistration.pushManager
    .getSubscription()
    .then(function (subscription) {
      // Enable any UI which subscribes / unsubscribes from
      // push messages.
      var pushButton = document.querySelector(".js-push-button");
      pushButton.disabled = false;

      if (!subscription) {
        // We aren’t subscribed to push, so set UI
        // to allow the user to enable push
        return;
      }

      // Keep your server in sync with the latest subscriptionId
      sendSubscriptionToServer(subscription);

      showCurlCommand(subscription);

      // Set your UI to show they have subscribed for
      // push messages
      pushButton.textContent = "Disable Push Messages";
      isPushEnabled = true;
    })
    .catch(function (err) {
      window.Demo.debug.log("Error during getSubscription()", err);
    });
});
```

规范
--

| Specification |
| --- |
| Push API # dom-pushmanager-getsubscription |

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

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


Range.deleteContents() - Web API 接口参考

Range.deleteContents()
======================

**`Range.deleteContents()`** 移除来自 `Document`的`Range` 内容。

不像`Range.extractContents`一样，本方法不会返回一个包含删除内容的文本片段`DocumentFragment` 。

语法
--
```

range.deleteContents()
```

例子
--

```js
range = document.createRange();
range.selectNode(document.getElementsByTagName("div").item(0));
range.deleteContents();
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-deletecontents |

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

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

参考
--

* The DOM interfaces index (en-US)


Range.startContainer - Web API 接口参考

Range.startContainer
====================

Range.startContainer 是只读属性，返回 Range 开始的节点。要更改节点的起始位置，请使用 Range.setStart() 方法。

Syntax
------
```

startRangeNode = range.startContainer;
```

Example
-------

```js
range = document.createRange();
range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
startRangeNode = range.startContainer;
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-startcontainer① |

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

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

See also
--------

* The DOM interfaces index (en-US)


Range.endContainer - Web API 接口参考

Range.endContainer
==================

**`Range.endContainer`** 是一个只读属性。它会返回`Range`对象结束的`Node`。如果要改变一个节点结束的位置，使用方法`Range.setEnd()`或者相似的方法。

语法
--
```

endRangeNode = range.endContainer;
```

示例
--

```js
var range = document.createRange();

range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
endRangeNode = range.endContainer;
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-endcontainer① |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.endOffset - Web API 接口参考

Range.endOffset
===============

只读属性 **`Range.endOffset`** 返回代表 `Range` 结束位置在 `Range.endContainer` 中的偏移值的数字。

如果 `endContainer` 的 `Node` 类型为 `Text` (en-US), `Comment`，或 `CDATASection`，偏移值是 `endContainer` 节点开头到 `Range` 末尾的总字符个数。对其他类型的 `Node` ， `endOffset` 指 `endContainer` 开头到 `Range` 末尾的总 `Node` 个数。如需修改 `endOffset` 的值，使用 `Range.setEnd` 方法。

语法
--
```

endRangeOffset = range.endOffset;
```

示例
--

```js
var range = document.createRange();

range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
endRangeOffset = range.endOffset;
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-endoffset① |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.cloneContents() - Web API 接口参考

Range.cloneContents()
=====================

**`Range.cloneContents()`** 返回一个 `DocumentFragment`，它是 `Range` 中所有的 `Node` 对象的副本。

使用" DOM 事件"添加的“事件侦听器”在克隆过程中不会被复制。HTML 属性事件与“DOM Core cloneNode”方法一样被复制。“HTML id 属性”也将被克隆，这可能导致通过克隆导致无效的文档。

Partially selected nodes include the parent tags necessary to make the document fragment valid.

语法
--
```

documentFragment = range.cloneContents();
```

例子
--

```js
range = document.createRange();
range.selectNode(document.getElementsByTagName("div").item(0));
documentFragment = range.cloneContents();
document.body.appendChild(documentFragment);
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-clonecontents |

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

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

参考
--

* The DOM interfaces index (en-US)


Range.setStartBefore() - Web API 接口参考

Range.setStartBefore()
======================

**`Range.setStartBefore()`** 方法相对另一个 `Node`来设置一个`Range` 的开始位置。`Range`的开始节点（focusNode）的父节点，和 `referenceNode`的父节点是同一个。

Syntax
------
```

range.setStartBefore(referenceNode);
```

### Parameters

*referenceNode*

一个`Range`新的开始位置上的`Node`.

Example
-------

```js
var range = document.createRange();
var referenceNode = document.getElementsByTagName("div").item(0);

range.setStartBefore(referenceNode);
```

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

| Specification |
| --- |
| DOM Standard # dom-range-setstartbefore |

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

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

See also
--------

* The DOM interfaces index (en-US)


Range.collapse() - Web API 接口参考

Range.collapse()
================

**`Range.collapse()`** 方法向边界点折叠该 `Range` 。

折叠后的 `Range` 为空，不包含任何内容。

要确定 `Range` 是否已折叠，使用`Range.collapsed` 属性。

语法
--
```

range.collapse(toStart);
```

### 参数

*toStart* 可选

一个布尔值： `true` 折叠到 `Range` 的 start 节点，`false` 折叠到 end 节点。如果省略，则默认为 false
实验性
`.`

例子
--

```js
var range = document.createRange();

referenceNode = document.getElementsByTagName("div").item(0);
range.selectNode(referenceNode);
range.collapse(true);
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-collapse |

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

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

参阅
--

* The DOM interfaces index (en-US)


Range.setStart() - Web API 接口参考

Range.setStart()
================

**`Range.setStart()`** 方法用于设置 `Range`的开始位置。

如果起始节点类型是 `Text`、`Comment` 或 `CDATASection`之一，那么 `startOffset` 指的是从起始节点算起字符的偏移量。对于其他 `Node` 类型节点，`startOffset` 是指从起始结点开始算起子节点的偏移量。

如果设置的起始位点在结束点之下（在文档中的位置），将会导致选区折叠，起始点和结束点都会被设置为指定的起始位置。

语法
--
```

range.setStart(startNode, startOffset);
```

### 参数

*startNode*

`startNode` 用于设定 `Range`的起始位置。

*startOffset*``

必须为不小于 0 的整数。表示从`startNode`的开始位置算起的偏移量。

例子
--

```js
var range = document.createRange();
var startNode = document.getElementsByTagName("p").item(2);
var startOffset = 0;
range.setStart(startNode, startOffset);
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-setstart |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.getBoundingClientRect() - Web API 接口参考

Range.getBoundingClientRect()
=============================

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

**`Range.getBoundingClientRect()`** 返回一个 `DOMRect` 对象，该对象将范围中的内容包围起来；即该对象是一个将范围内所有元素的边界矩形包围起来的矩形（译者注：关于边界矩形，可以参考 Minimum Bouding Rectangles）。

此方法可用于确定文本区域中选中的部分或光标的视窗坐标。关于返回值的详细信息，参见 `Element.getBoundingClientRect()`。

语法
--
```

boundingRect = range.getBoundingClientRect()
```

示例
--

### HTML

```html
<div id="highlight"></div>
<p>
  This example positions a "highlight" rectangle behind the contents of a range.
  The range's content <b>starts here</b> and continues on until it
  <b>ends here</b>. The bounding client rectangle contains everything selected
  in the range.
</p>
```

### CSS

```css
#highlight {
  background: yellow;
  position: absolute;
  z-index: -1;
}

p {
  width: 200px;
}
```

### JavaScript

```js
const range = document.createRange();
range.setStartBefore(document.getElementsByTagName("b").item(0), 0);
range.setEndAfter(document.getElementsByTagName("b").item(1), 0);

const clientRect = range.getBoundingClientRect();
const highlight = document.getElementById("highlight");
highlight.style.left = `${clientRect.x}px`;
highlight.style.top = `${clientRect.y}px`;
highlight.style.width = `${clientRect.width}px`;
highlight.style.height = `${clientRect.height}px`;
```

### 结果

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-range-getboundingclientrect |

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

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

参见
--

* `Range.getClientRects()` - 对于非矩形的范围（如选择部分换行了）会返回更细致的结果。
* `Element.getBoundingClientRect()`
* `Document.caretPositionFromPoint()` - 使用视窗坐标获取节点范围。


Range.createContextualFragment() - Web API 接口参考

Range.createContextualFragment()
================================

**`Range.createContextualFragment()`** 方法通过以 range 的开头（选定节点的父级）作为上下文节点来调用 HTML 片段解析算法 或者 XML 片段解析算法来返回 `DocumentFragment`。如果 range 属于一个其 HTMLness bit 被设置了的 `Document` 则会应用 HTML 片段解析算法。在 HTML 的情况下，如果上下文节点为 html，由于历史原因，将使用 body 作为上下文来调用片段解析算法。

语法
--
```

documentFragment = range.createContextualFragment(tagString)
```

### 参数

`tagString`

包含要转换为文档片段的文本和标签的文本。

示例
--

```js
var tagString = "<div>I am a div node</div>";
var range = document.createRange();

// 使文档中第一个 div 的父级成为上下文节点
range.selectNode(document.getElementsByTagName("div").item(0));
var documentFragment = range.createContextualFragment(tagString);
document.body.appendChild(documentFragment);
```

规范
--

| Specification |
| --- |
| DOM Parsing and Serialization # ref-for-dom-range-createcontextualfragment-2 |

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

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

See also
--------

* The DOM interfaces index (en-US)


Range.selectNode() - Web API 接口参考

Range.selectNode()
==================

**`Range.selectNode()`** 方法将 `Range` 设置为包含整个 `Node` 及其内容。`Range` 的起始和结束节点的父节点与 *referenceNode* 的父节点相同。

语法
--
```

range.selectNode(referenceNode);
```

### 参数

*referenceNode*

`Range` 要包含的 `Node`。

示例
--

```js
var range = document.createRange();
var referenceNode = document.getElementsByTagName("div").item(0);

range.selectNode(referenceNode);
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-selectnode |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.commonAncestorContainer - Web API 接口参考

Range.commonAncestorContainer
=============================

**`Range.commonAncestorContainer`** 只读属性，返回目标节点的共有祖先节点。因而需要注意：selectNode 方法中的该值为目标节点的父节点，selectNodeContents 方法中的该值为其本身。

在某些跨节点的选取操作时，取得最大"公约数"的节点为`commonAncestorContainer。`即`Range.startContainer` 和 `Range.endContainer` 相同的节点是目标节点的 共有祖先节点。

更改 `Node`, 请使用 setStart setEnd 及这两种方法的延伸方法 `Range`.

语法
--
```

rangeAncestor = range.commonAncestorContainer;
```

示例
--

```js
var range = document.createRange();

range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
rangeAncestor = range.commonAncestorContainer;
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-commonancestorcontainer② |

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

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

更多
--

* DOM 接口相关内容 (en-US)


Range.collapsed - Web API 接口参考

Range.collapsed
===============

**`Range.collapsed`** 是只读属性。它返回一个 `Boolean` (en-US) 值表示是否起始点和结束点是同一个位置。如果返回 `true` 表示`Range` 的起始位置和结束位置重合，`false` 表示不重合。

一个折叠的`Range` 是空的，不包含内容，表示 Dom 树中的一个点。collapsed 属性是只读的。可以调用 `Range.collapse()` 方法来折叠选区。

语法
--
```

isCollapsed = range.collapsed;
```

例子
--

```js
var range = document.createRange();

range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
isCollapsed = range.collapsed;
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-collapsed① |

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

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

参阅
--

* The DOM interfaces index (en-US)


Range.startOffset - Web API 接口参考

Range.startOffset
=================

**`Range.startOffset`** 是一个只读属性，用于返回一个表示 `Range` 在 `startContainer` 中的起始位置的数字。

如果 `startContainer` 是一个文本（`Text` (en-US)）、注释（`Comment`）或者 CDATA 区块（`CDATASection`）节点，那么返回的偏移量是从 `startContainer` 开始到 `Range` 的边界点的字符数量。对于其他的节点类型， `startOffset` 返回 `startContainer` 到边界点的子节点数量。

可使用`Range.setStart` 方法改变 `Range` 的 `startOffset` 位置。

语法
--
```

startRangeOffset = range.startOffset;
```

示例
--

```js
range = document.createRange();
range.setStart(startNode, startOffset);
range.setEnd(endNode, endOffset);
startRangeOffset = range.startOffset;
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-startoffset① |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.cloneRange() - Web API 接口参考

Range.cloneRange()
==================

\*\*`Range.cloneRange()`\*\*方法返回一个 range 对象，并且该对象的范围边界点与被克隆的 range 对象相同。

克隆的对象是复制过来的，而非引用，所以这两个对象双方各自做出的改变，都不会影响另一方。

语法
--
```

clone = range.cloneRange();
```

Example
-------

```js
range = document.createRange();
range.selectNode(document.getElementsByTagName("div").item(0));
clone = range.cloneRange();
```

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

| Specification |
| --- |
| DOM Standard # dom-range-clonerange |

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

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

See also
--------

* The DOM interfaces index (en-US)


Range() - Web API 接口参考

Range()
=======

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

构造函数 **`Range()`** 返回一个新创建的 `Range` 对象，新创建的对象属于全局 `Document` 对象。

语法
--
```

range = new Range()
```

示例
--

在下面的例子中，我们通过构造函数`Range()`创建了一个新的 range，并且使用`Range.setStartBefore()` 和`Range.setEndAfter()` (en-US) 分别设置了起始位置。然后，通过方法`window.getSelection()`和`Selection.addRange()`选中了选区 range。

### HTML

```html
<p>First paragraph.</p>
<p>Second paragraph.</p>
<p>Third paragraph.</p>
<p>Fourth paragraph.</p>
```

### JavaScript

```js
const paragraphs = document.querySelectorAll("p");

// 创建 Range 对象
const range = new Range();

// Range 起始位置在段落 2
range.setStartBefore(paragraphs[1]);

// Range 结束位置在段落 3
range.setEndAfter(paragraphs[2]);

// 获取 selection 对象
const selection = window.getSelection();

// 添加光标选择的范围
selection.addRange(range);
```

### 结果

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-range② |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.intersectsNode() - Web API 接口参考

Range.intersectsNode()
======================

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

**`Range.intersectsNode()`** 方法返回一个布尔值，表明其给定的 `Node` 节点是否与`Range`的范围相交

Syntax
------
```

bool = range.intersectsNode( referenceNode )
```

### Parameters

*referenceNode*

与`Range`做比较的`Node`节点

Example
-------

```js
var range = document.createRange();

range.selectNode(document.getElementsByTagName("div").item(0));
var bool = range.intersectsNode(document.getElementsByTagName("p").item(0));
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-range-intersectsnode① |

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

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

See also
--------

* The DOM interfaces index (en-US)


Range.surroundContents - Web API 接口参考

Range.surroundContents
======================

**`Range.surroundContents()`** 方法将 `Range` 对象的内容移动到一个新的节点，并将新节点放到这个范围的起始处。

这个方法与 `newNode.appendChild(range.extractContents()); range.insertNode(newNode)` 等价。应用以后， `newNode` 包含在 `range` 的边界点中。

然而，如果 `Range` 断开了一个非 `Text` (en-US) 节点，只包含了节点的其中一个边界点，就会抛出异常。也就是说，不像上述的等价方法，如果节点仅有一部分被选中，则不会被克隆，整个操作会失败。

语法
--
```

range.surroundContents(newParent);
```

### 参数

`newParent`

一个包含内容的 `Node`。

示例
--

### HTML
```

<span class="header-text">Put this in a headline</span>
```

### JavaScript
```

const range = document.createRange();
const newParent = document.createElement('h1');

range.selectNode(document.querySelector('.header-text'));
range.surroundContents(newParent);
```

### 结果

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-surroundcontents |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.selectNodeContents() - Web API 接口参考

Range.selectNodeContents()
==========================

**`Range.selectNodeContents()`** 方法用于设置 `Range`，使其包含一个 `Node` 的内容。

`Range` 的起始和结束节点的父节点即为引用节点。 `startOffset` 为 0, `endOffset` 则是引用节点包含的字符数或子节点个数。

语法
--
```

range.selectNodeContents(referenceNode);
```

### 参数

*referenceNode*

此 `Node` 中的内容被包含在 `Range` 中。

示例
--

```js
range = document.createRange();
referenceNode = document.getElementsByTagName("div")[0];
range.selectNodeContents(referenceNode);
```

### 实时样例

这个例子让用户使用按钮选择或取消选择一个段落。`Document.createRange()`、 `Range.selectNodeContents()` 和 `Selection.addRange()` 用于选择内容。`Window.getSelection()` 和 `Selection.removeAllRanges()` 用于取消选择。

#### HTML
```

<p id="p"><b>Use the buttons below</b> to select or deselect the contents of this paragraph.</p>
<button id="select-button">Select paragraph</button>
<button id="deselect-button">Deselect paragraph</button>
```

#### JavaScript
```

const p = document.getElementById('p');
const selectButton = document.getElementById('select-button');
const deselectButton = document.getElementById('deselect-button');

selectButton.addEventListener('click', e => {
  // Clear any current selection
  const selection = window.getSelection();
  selection.removeAllRanges();

  // Select paragraph
  const range = document.createRange();
  range.selectNodeContents(p);
  selection.addRange(range);
});

deselectButton.addEventListener('click', e => {
  const selection = window.getSelection();
  selection.removeAllRanges();
});
```

#### 结果

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-selectnodecontents |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.extractContents() - Web API 接口参考

Range.extractContents()
=======================

**`Range.extractContents()`** 方法移动了`Range` 中的内容从文档树到`DocumentFragment`（文档片段对象）。

使用 DOM 事件添加的事件侦听器在提取期间不会保留。HTML 属性事件将按`Node.cloneNode()`方法的原样保留或复制。HTML id 属性也会被克隆，如果提取了部分选定的节点并将其附加到文档中，则可能导致无效的文档。

克隆了部分选定的节点，以包括使文档片段有效所需的父标记。

Syntax
------
```

documentFragment = range.extractContents();
```

Example
-------

```js
var range = document.createRange();
range.selectNode(document.getElementsByTagName("div").item(0));
var documentFragment = range.extractContents();
document.body.appendChild(documentFragment);
```

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

| Specification |
| --- |
| DOM Standard # dom-range-extractcontents |

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

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

See also
--------

* The DOM interfaces index (en-US)


Range.getClientRects() - Web API 接口参考

Range.getClientRects()
======================

**`Range.getClientRects()`** 方法返回一个 `DOMRect` 对象列表，表示 range 在屏幕上所占的区域。这个列表相当于汇集了范围中所有元素调用 `Element.getClientRects()` 方法所得的结果。

语法
--
```

rectList = range.getClientRects()
```

示例
--

```js
range = document.createRange();
range.selectNode(document.getElementsByTagName("div").item(0));
rectList = range.getClientRects();
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-range-getclientrects |

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

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

参见
--

* `Range`


Range.setEnd() - Web API 接口参考

Range.setEnd()
==============

\*\*`Range.setEnd()`\*\*方法用于设置 `Range`的结束位置。

如果结束节点类型是 `Text`、`Comment` 或 `CDATASection`之一，那么 `endOffset` 指的是从结束节点算起字符的偏移量。对于其他 `Node` 类型节点，`endOffset` 是指从结束结点开始算起子节点的偏移量。

如果设置的结束点在起始点之上（在文档中的位置），将会导致选区折叠，起始点和结束点都会被设置为指定的结束位置。

语法
--
```

range.setEnd(endNode, endOffset);
```

### 参数

*endNode*

*endNode*用于设定 `Range`的结束位置。

*endOffset*

必须为不小于 0 的整数。表示从*endNode*的结束位置算起的偏移量。

例子
--

```js
var range = document.createRange();
var endNode = document.getElementsByTagName("p").item(3);
var endOffset = endNode.childNodes.length;
range.setEnd(endNode, endOffset);
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-range-setend |

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

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

参见
--

* The DOM interfaces index (en-US)


Range.insertNode() - Web API 接口参考

Range.insertNode()
==================

**`Range.insertNode()`** 是在`Range`的起始位置插入节点的方法。

新节点是插入在 `Range` 起始位置。如果将新节点添加到一个文本`节点`，则该节点在插入点处被拆分，插入发生在两个文本节点之间

如果新节点是一个文档片段，则插入文档片段的子节点。

Syntax
------
```

range.insertNode(newNode);
```

### Parameters

*newNode*

The `Node` to insert at the start of the `range`.

Example
-------

```js
range = document.createRange();
newNode = document.createElement("p");
newNode.appendChild(document.createTextNode("New Node Inserted Here"));
range.selectNode(document.getElementsByTagName("div").item(0));
range.insertNode(newNode);
```

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

| Specification |
| --- |
| DOM Standard # dom-range-insertnode |

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

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

See also
--------

* The DOM interfaces index


DragEvent.dataTransfer - Web API 接口参考

DragEvent.dataTransfer
======================

**`DataEvent.dataTransfer`** 属性保存着拖拽操作中的数据（作为一个 DataTransfer 对象）

This property is 只读 .

语法
--
```

var data = dragEvent.dataTransfer;
```

### 返回值

`data`

`DataTransfer` 对象包含着 `drag event's data`.

示例
--

这个例子展示了在`dragend` 事件处理程序中获取拖拽中数据的方式。

```js
function process\_data(d) {
  // Process the data ...
}

dragTarget.addEventListener(
  "dragend",
  function (ev) {
    // Call the drag and drop data processor
    if (ev.dataTransfer != null) process\_data(ev.dataTransfer);
  },
  false,
);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-dragevent-datatransfer-dev |

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

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


DragEvent() - Web API 接口参考

DragEvent()
===========

This constructor is used to create a synthetic `DragEvent` object.

Although this interface has a constructor, it is not possible to create a useful `DataTransfer` object from script, since `DataTransfer` objects have a processing and security model that is coordinated by the browser during drag-and-drops.

该接口继承了 `MouseEvent` 和 `Event` 的属性。

语法
--
```

 event = new DragEvent(type, DragEventInit);
```

### 参数

*type*

Is a `DOMString` representing the name of the event (see DragEvent event types).

*DragEventInit*可选

Is a `DragEventInit` dictionary, having the following fields:

* `"dataTransfer"`, optional and defaults to `"null"`. The type is `DataTransfer`.

The `DragEventInit` dictionary inherits from the `MouseEventInit dictionary`.

标准
--

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

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

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


DOMException.code - Web API 接口参考

DOMException.code
=================

`DOMException` 接口中的 **`code`** 是一个只读属性，他返回了一个包含了 错误常量 的`简短`数字，或者在没有匹配到时返回 `0` 。这个字段产生于历史原因，在新的 DOM 异常中已停止使用，改为在 `DOMException.name` 属性中推送此信息。

语法
--
```

var domExceptionCode = domExceptionInstance.code;
```

### 值

一个数字

规范
--

| Specification |
| --- |
| Web IDL Standard # dom-domexception-code |

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

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


DOMException()：DOMException() 构造函数 - Web API 接口参考

DOMException()：DOMException() 构造函数
==================================

**`DOMException()`** 构造函数返回一个包含指定消息和名称的 `DOMException` 对象。

语法
--

```js
new DOMException()
new DOMException(message)
new DOMException(message, name)
```

### 参数

`message` 可选

对异常的描述。如果不存在，使用空字符串 `''`。

`name` 可选

一个字符串。如果指定的名称是标准的错误名称之一，那么获取 `DOMException` 对象的 `code` 属性将返回与指定名称对应的代码编号。

### 返回值

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

示例
--

在本例中，按下按钮会导致抛出自定义的 `DOMException` 异常，然后会捕获该异常并在警报中显示自定义的错误信息。

### HTML

```html
<button>触发 DOM 异常</button>

<p id="output"></p>
```

### JavaScript

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

button.onclick = () => {
  try {
    throw new DOMException("已触发自定义 DOM 异常。");
  } catch (error) {
    document.querySelector("#output").textContent =
      `错误信息：${error.message}`;
  }
};
```

### 结果

规范
--

| Specification |
| --- |
| Web IDL Standard # dom-domexception-domexception |

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

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

参见
--

* `core-js` 中一个可用的 `DOMException` 构造函数的 polyfill


DOMException.name - Web API 接口参考

DOMException.name
=================

`DOMException` 接口的 **`name`** 只读属性返回一个字符串，其中包含与错误名称关联的字符串之一。

值
-

一个字符串。

规范
--

| Specification |
| --- |
| Web IDL Standard # dom-domexception-name |

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

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


DOMException.message - Web API 接口参考

DOMException.message
====================

`DOMException` 接口的 **`message`** 只读属性返回一个字符串来表示与给定错误名称关联的消息或描述。

值
-

一个字符串。

规范
--

| Specification |
| --- |
| Web IDL Standard # dom-domexception-message |

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

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


OffscreenCanvas() - Web API 接口参考

OffscreenCanvas()
=================

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

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

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

\*\*`OffscreenCanvas()`\*\*构造函数，返回一个新的 `OffscreenCanvas` 对象

语法
--
```

new OffscreenCanvas(width, height);
```

### 参数

`width`

离屏 canvas 的高度

`height`

离屏 canvas 的宽度

示例
--

创建一个离屏 Canvas 并且初始一个 WebGL 上下文：

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

规范
--

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

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

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

查看更多
----

* `OffscreenCanvas`, the interface this constructor belongs to.


OffscreenCanvas.height - Web API 接口参考

OffscreenCanvas.height
======================

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

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

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

设置或者获取`OffscreenCanvas` 对象的高度。

语法
--
```

var pxl = offscreen.height;
offscreen.height = pxl;
```

例子
--

创建一个新的离屏 canvas，获取或者设置离屏 canvas 的高度：

```js
var offscreen = new OffscreenCanvas(256, 256);
offscreen.height; // 256
offscreen.height = 512;
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-offscreencanvas-height-dev |

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

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

另外参阅
----

* `OffscreenCanvas`, 此属性所属的接口。


OffscreenCanvas.transferToImageBitmap() - Web API 接口参考

OffscreenCanvas.transferToImageBitmap()
=======================================

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

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

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

**`OffscreenCanvas.transferToImageBitmap()`** 方法使用`offscreenCanvas`最近渲染得到的图片创建一个`ImageBitmap` 对象。

语法
--
```

ImageBitmap OffscreenCanvas.transferToImageBitmap()
```

### 返回值

一个`ImageBitmap`对象。

例子
--

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

//一些绘制要使用 gl 前后文

offscreen.transferToImageBitmap();
// ImageBitmap { width: 256, height: 256 }
```

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

| Specification |
| --- |
| HTML Standard # dom-offscreencanvas-transfertoimagebitmap-dev |

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

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

浏览相关
----

* The interface defining this method, `OffscreenCanvas`
* `ImageBitmapRenderingContext.transferImageBitmap()` (en-US)


CSSStyleRule.selectorText - Web API 接口参考

CSSStyleRule.selectorText
=========================

概述
--

**`CSSRule.selectorText`** 属性返回 CSS 规则的选择符文本，只读。动态设置 CSS 规则，请看 Using dynamic styling information (en-US).

语法
--
```

string = cssRule.selectorText
```

例子
--

```js
// for cssrule: body { background-color: darkblue; }
var stylesheet = document.styleSheets[0];

alert(stylesheet.cssRules[0].selectorText); // body
```

说明
--

浏览器解析选择符的时候可能会剔除不必要的空白字符

标准
--

* Document Object Model CSS - #CSS-CSSRuleCSS


style - Web API 接口参考

style
=====

返回 一个 `CSSStyleDeclaration`接口对象，它代表了`CSSRule`的 declaration block。

语法
--
```

styleObj = cssRule.style
```

示例
--

```js
function stilo() {
  alert(document.styleSheets[0].cssRules[0].style.cssText);
}
// 弹出 "background-color: gray;"
```

备注
--

declaration block 是样式规则中花括号内的部分（选择器就在花括号的外部）

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylerule-style |

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

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


MediaSession.setActionHandler() - Web API 接口参考

MediaSession.setActionHandler()
===============================

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

`MediaSession` 接口的属性 **`setActionHandler()`** 为 media session 动作设置一个监听器。这些动作让网页程序在用户操作设备的内置物理或屏上媒体控制项时收到消息，例如播放、停止或搜寻按钮。

语法
--
```

navigator.mediaSession.setActionHandler(type, callback)
```

### 参数

`type`

一个提供要监听的动作类型的 `DOMString` 。它可以是 `play`、`pause`、`seekbackward`、`seekforward`、`previoustrack` 或 `nexttrack`。

`callback`

一个在指定动作被调用时要调用的方法。回调方法不会收到参数，并且不应该返回值。

### 返回值

`undefined`。

使用说明
----

要移除一个已经存在的监听器，再调用一次 `setActionHandler()` ，将 `null` 作为回调方法。

示例
--

下面的示例创建一个新的 media session 并且为它添加监听器（不做任何事情）。

```js
if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "播客音乐名字",
    artist: "播客主持人",
    album: "播客名字",
    artwork: [{ src: "podcast.jpg" }],
  });
  navigator.mediaSession.setActionHandler("play", function () {});
  navigator.mediaSession.setActionHandler("pause", function () {});
  navigator.mediaSession.setActionHandler("seekbackward", function () {});
  navigator.mediaSession.setActionHandler("seekforward", function () {});
  navigator.mediaSession.setActionHandler("previoustrack", function () {});
  navigator.mediaSession.setActionHandler("nexttrack", function () {});
}
```

这个示例使用了适当的监听器来允许在不同的方向搜寻正在播放的媒体。

```js
let skipTime = 10; // 要跳过的秒数

navigator.mediaSession.setActionHandler("seekbackward", (evt) => {
  // 用户点击了“向后搜寻”的媒体按钮
  audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

navigator.mediaSession.setActionHandler("seekforward", (evt) => {
  // 用户点击了“向前搜寻”的媒体按钮
  audio.currentTime = Math.min(audio.currentTime + skipTime, audio.duration);
});
```

要移除一个监听器，将它设为 null。

```js
navigator.mediaSession.setActionHandler("nexttrack", null);
```

规范
--

| Specification |
| --- |
| Media Session # dom-mediasession-setactionhandler |

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

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


IDBKeyRange.lowerBound() - Web API 接口参考

IDBKeyRange.lowerBound()
========================

`IDBKeyRange` 接口的 **`lowerBound()`** 方法创建一个只有下限的新的键范围。默认情况下，它包含较低的端点值。

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

Syntax
------
```

var myIDBKeyRange = IDBKeyRange.lowerBound(lower);
var myIDBKeyRange = IDBKeyRange.lowerBound(lower, open);
```

### Parameters

lower

指定新键范围的下限。

open 可选

指示下限是否排除端点值。默认值为 false。

### Return value

`IDBKeyRange`: 新创建的键范围。

### Exceptions

此方法可能引发以下类型的 `DOMException` :

| Exception | Description |
| --- | --- |
| DataError | The value parameter passed was not a valid key. |

Example
-------

下面的示例演示如何使用下限键范围。在这里，我们声明`keyRangeValue = IDBKeyRange.lowerBound("F", false);`— 一个包含值“F”及其后所有内容的范围。我们打开一个事务（使用 `IDBTransaction`）和一个对象存储，并使用 `IDBObjectStore.openCursor`打开一个游标，声明`keyRangeValue` 为其可选的键范围值。这意味着光标将只检索键值为“F”及其后面的所有记录。如果使用`IDBKeyRange.lowerBound("F", true);`，则该范围将不包括端点“F”，仅包括其后面的值。

**备注：** 要获得一个更完整的示例，使你能够使用键范围进行实验，请查看我们的 IDBKeyRange-example（实时查看该示例）。

```js
function displayData() {
  var keyRangeValue = IDBKeyRange.lowerBound("F");

  var transaction = db.transaction(["fThings"], "readonly");
  var objectStore = transaction.objectStore("fThings");

  objectStore.openCursor(keyRangeValue).onsuccess = function (event) {
    var cursor = event.target.result;
    if (cursor) {
      var listItem = document.createElement("li");
      listItem.innerHTML =
        "<strong>" + cursor.value.fThing + "</strong>, " + cursor.value.fRating;
      list.appendChild(listItem);

      cursor.continue();
    } else {
      console.log("Entries all displayed.");
    }
  };
}
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbkeyrange-lowerbound① |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (view example live.)


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

ReadableStream.cancel()
=======================

`ReadableStream` 接口的 **`cancel()`** 方法返回一个 `Promise`，这个 promise 会在流被取消的时候兑现。

cancel 用于在不再需要来自它的任何数据的情况下（即使仍有排队等待的数据块）完全结束一个流。调用 cancel 后该数据丢失，并且流不再可读。为了仍然可以读这些数据块而不完全结束这个流，你应该使用 `ReadableStreamDefaultController.close()`。

语法
--

```js
cancel()
cancel(reason)
```

### 参数

`reason` 可选

人类可读的取消原因。底层源代码可能会使用它。

### 返回值

一个 `Promise`，会在结束时使用给定的 `reason` 参数兑现。

### 异常

`TypeError`

它尝试取消的流不是 `ReadableStream`，或者它已被锁定。

示例
--

在 Jake Archibald 的取消一个 fetch 示例中，流用于逐块获取 WHATWG HTML 规范；并在每个块中搜索“service workers”字符串。当找到搜索词时，使用 `cancel()` 取消流——作业已被完成，因此不再需要它。

```js
var searchTerm = "service workers";
// Chars to show either side of the result in the match
var contextBefore = 30;
var contextAfter = 30;
var caseInsensitive = true;
var url = "https://html.spec.whatwg.org/";
console.log(`Searching '${url}' for '${searchTerm}'`);
fetch(url)
  .then((response) => {
    console.log("Received headers");
    var decoder = new TextDecoder();
    var reader = response.body.getReader();
    var toMatch = caseInsensitive ? searchTerm.toLowerCase() : searchTerm;
    var bufferSize = Math.max(toMatch.length - 1, contextBefore);
    var bytesReceived = 0;
    var buffer = "";
    var matchFoundAt = -1;
    return reader.read().then(function process(result) {
      if (result.done) {
        console.log("Failed to find match");
        return;
      }
      bytesReceived += result.value.length;
      console.log(`Received ${bytesReceived} bytes of data so far`);
      buffer += decoder.decode(result.value, { stream: true });
      // already found match & just context-gathering?
      if (matchFoundAt === -1) {
        matchFoundAt = (
          caseInsensitive ? buffer.toLowerCase() : buffer
        ).indexOf(toMatch);
      }
      if (matchFoundAt === -1) {
        buffer = buffer.slice(-bufferSize);
      } else if (
        buffer.slice(matchFoundAt + toMatch.length).length >= contextAfter
      ) {
        console.log("Here's the match:");
        console.log(
          buffer.slice(
            Math.max(0, matchFoundAt - contextBefore),
            matchFoundAt + toMatch.length + contextAfter,
          ),
        );
        console.log("Cancelling fetch");
        reader.cancel();
        return;
      } else {
        console.log("Found match, but need more context…");
      }
      // 保持读取
      return reader.read().then(process);
    });
  })
  .catch((err) => {
    console.log(
      "Something went wrong. See devtools for details. Does the response lack CORS headers?",
    );
    throw err;
  });
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-cancel③ |

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

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

参见
--

* `ReadableStream()` 构造函数
* 使用可读流


ReadableStream.pipeThrough() - Web API 接口参考

ReadableStream.pipeThrough()
============================

`ReadableStream` 接口的 **`pipeThrough()`** 方法提供了一种链式的方式，将当前流通过转换流或者其他任何一对可写/可读的流进行管道传输。

传输一个流通常在管道传输的时间内锁定这个流，以阻止其他 reader 锁定它。

语法
--

```js
pipeThrough(transformStream)
pipeThrough(transformStream, options)
```

### 参数

`transformStream`

由一对可读流和可写流组成的 `TransformStream`（或者结构为 `{writable, readable}` 的对象），它们共同工作以对数据进行转换。`writable` 流写入的数据在某些状态下可以被 `readable` 流读取。例如，向 `TextDecoder` 写入字节并从中读取字符串，而视频解码器则是写入编码的字节数据，并从中读取解压后的视频帧。

`options` 可选

传输至 `writable` 流应该被使用的选项。可用选项是：

`preventClose`

如果设置为 `true`，源 `ReadableStream` 的关闭将不再导致目标 `WritableStream` 关闭。一旦此过程完成，该方法返回的 promise 将被兑现；除非在关闭目标流时遇到错误，在这种情况下，它将因为该错误被拒绝。

`preventAbort`

如果设置为 `true`，源 `ReadableStream` 中的错误将不再中止目标 `WritableStream`。该方法返回的 promise 将因源流的错误或者任何在中止目地流期间的错误而被拒绝。

`preventCancel`

如果设置为 `true`，目标 `WritableStream` 的错误将不再取消源 `ReadableStream`。在这种情况下，该方法返回的 promise 将因源流的错误或者在取消源流期间发生的任何错误而被拒绝。此外，如果目标可写流开始关闭或者正在关闭，则源可读流将不再被取消。在这种情况下，方法返回的 promise 也将被拒绝，其错误为连接到一个已关闭的流或者在取消源流期间发生的任何错误。

`signal`

用于设置一个 `AbortSignal` 对象，然后可以通过相应的 `AbortController` 中止正在进行的传输操作。

### 返回值

`transformStream` 的 `readable` 端。

### 异常

`TypeError`

如果 `transformStream` 的 `writable` 和/或 `readable` 属性未定义，则抛出异常。

示例
--

在下面的例子中（有关运行实例的完整代码，参见解压 PNG，有关源代码，参见 png-transform-stream），使用 `fetch` 获取图像并将响应的 body 作为 `ReadableStream`。

接下来，我们记录可读流的内容，并且使用 `pipeThrough()` 将它发送到一个转换灰度图的转换流，然后记录新的流中的内容。

```js
// 通过 fetch 获取原始图像
fetch("png-logo.png")
  // 将响应的 body 作为 ReadableStream
  .then((response) => response.body)
  .then((rs) => logReadableStream("Fetch Response Stream", rs))
  // 从原始图像创造一个 PNG 的灰度图像
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => logReadableStream("PNG Chunk Stream", rs));
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-pipe-through② |

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

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

参见
--

* `ReadableStream()` 构造函数
* 链式管道传输


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

ReadableStream.ReadableStream()
===============================

**`ReadableStream()`** 构造函数创建并从给定的处理程序返回一个可读的流对象。

语法
--

```js
new ReadableStream()
new ReadableStream(underlyingSource)
new ReadableStream(underlyingSource, queuingStrategy)
```

### 参数

`underlyingSource` 可选

一个包含定义了构造流行为方法和属性的对象。`underlyingSource` 包括：

`start` (controller) 可选

 这是一个当对象被构造时立刻调用的方法。此方法的内容由开发人员定义，并应着眼于访问流，并执行其他任何必需的设置流功能。如果这个过程是异步完成的，它可以返回一个
 promise，表明成功或失败。传递给这个方法的 `controller` 是一个 `ReadableStreamDefaultController` 或 `ReadableByteStreamController` (en-US)，具体取决于 `type` 属性的值。开发人员可以使用此方法在设立期间控制流。

`pull` (controller) 可选

这个方法，也是由开发人员定义的，当流的内部队列不满时，会重复调用这个方法，直到队列补满。如果 `pull()` 返回一个 promise，那么它将不会再被调用，直到 promise 完成;如果 promise 失败，该流将会出现错误。传递给此方法的 `controller` 参数是 `ReadableStreamDefaultController` 或 `ReadableByteStreamController` (en-US)，具体取决于 `type` 属性的值。由于更多的块被获取，这个方法可以被开发人员用来控制流。

`cancel` (reason) 可选

 如果应用程序表示该流将被取消（例如，调用了 `ReadableStream.cancel()`，则将调用此方法，该方法也由开发人员定义。该方法应该做任何必要的事情来释放对流的访问。
 如果这个过程是异步的，它可以返回一个 promise，表明成功或失败。原因参数包含一个 `DOMString`，它描述了流被取消的原因。

`type` 可选

该属性控制正在处理的可读类型的流。如果它包含一个设置为 `bytes` 的值，则传递的控制器对象将是一个 `ReadableByteStreamController` (en-US)，能够处理 BYOB（带你自己的缓冲区）/字节流。如果未包含，则传递的控制器将为 `ReadableStreamDefaultController`。

`autoAllocateChunkSize` 可选

对于字节流，开发人员可以使用正整数值设置 `autoAllocateChunkSize` 以打开流的自动分配功能。启用此功能后，流实现将自动分配一个具有给定整数大小的 `ArrayBuffer`，并调用底层源代码，就好像消费者正在使用 BYOB reader 一样。

`queuingStrategy` 可选

一个可选择定义流的队列策略的对象。这需要两个参数：

`highWaterMark`

非负整数 - 这定义了在应用背压之前可以包含在内部队列中的块的总数。

`size(chunk)`

包含参数 `chunk` 的方法——这表示每个分块使用的大小（以字节为单位）。

**备注：** 你可以自定义 `queuingStrategy`，或者使用 `ByteLengthQueueingStrategy` (en-US) 或 `CountQueueingStrategy` (en-US) 的示例作为对象的值。如果 没有提供 `queuingStrategy`，则默认值与 highWaterMark 为 1 的 `CountQueuingStrategy` 相同。

### 返回值

`ReadableStream` 对象的实例。

### 异常

RangeError

提供的值既不是 `"bytes"` 也不是 `undefined`。

示例
--

在下面的简单示例中，使用构造函数创建了一个自定义的 `ReadableStream`（完整代码请参见我们的简单随机流示例）。`start()` 函数每秒生成一个随机的文本字符串并将它排入流中。如果因为任何原因调用 `ReadableStream.cancel()`，该 `cancel()` 函数也可以停止生成字符串。

按下按钮，将停止生成字符串，使用 `ReadableStreamDefaultController.close()` 关闭流，并且将运行另一个函数，从流中读取数据。

```js
const stream = new ReadableStream({
  start(controller) {
    interval = setInterval(() => {
      let string = randomChars();

      // Add the string to the stream
      controller.enqueue(string);

      // show it on the screen
      let listItem = document.createElement("li");
      listItem.textContent = string;
      list1.appendChild(listItem);
    }, 1000);

    button.addEventListener("click", function () {
      clearInterval(interval);
      fetchStream();
      controller.close();
    });
  },
  pull(controller) {
    // We don't really need a pull in this example
  },
  cancel() {
    // This is called if the reader cancels,
    // so we should stop generating strings
    clearInterval(interval);
  },
});
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-constructor⑤ |

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

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

参见
--

* `ReadableStream`
* `ReadableByteStreamController` (en-US)
* `ReadableStreamDefaultController`
* 使用可读流


ReadableStream.pipeTo() - Web API 接口参考

ReadableStream.pipeTo()
=======================

`ReadableStream` 接口的 **`pipeTo()`** 方法通过管道将当前的 `ReadableStream` 中的数据传递给给定的 `WritableStream` 并且返回一个 `Promise`，promise 在传输成功完成时兑现，在遇到任何错误时则会被拒绝。

传输一个流时通常会在传输的持续时间内锁定这个流，以阻止其他 reader 锁定它。

语法
--

```js
pipeTo(destination)
pipeTo(destination, options)
```

### 参数

`destination`

充当 `ReadableStream` 最终目标的 `WritableStream`。

`options` 可选

传输至 `writable` 流应该被使用的选项。可用选项是：

`preventClose`

如果设置为 `true`，源 `ReadableStream` 的关闭将不再导致目标 `WritableStream` 关闭。一旦此过程完成，该方法将返回的 promise 将被兑现；除非在关闭目标时遇到错误，在这种情况下，它将因为该错误被拒绝。

`preventAbort`

如果设置为 `true`，源 `ReadableStream` 中的错误将不再中止目标 `WritableStream`。该方法返回的 promise 将因源流的错误或者任何在中止目地流期间的错误而被拒绝。

`preventCancel`

如果设置为 `true`，目标 `WritableStream` 的错误将不再取消源 `ReadableStream`。在这种情况下，该方法返回的 promise 将因源流的错误或者在取消源流期间发生的任何错误而被拒绝。此外，如果目标可写流开始关闭或者正在关闭，则源可读流将不再被取消。在这种情况下，方法返回的 promise 也将被拒绝，其错误为连接到一个已关闭的流或者在取消源流期间发生的任何错误。

`signal`

如果设置一个 `AbortSignal` 对象，然后可以通过相应的 `AbortController` 中止正在进行的传输操作。

### 返回值

返回一个 `Promise`，其在传输完成时兑现。

### 异常

`TypeError`

`writableStream` 且/或 `readableStream` 对象不是一个可写/可读流，或者其中一个或者两个流被锁定。

示例
--

```js
// 获取原始图像
fetch("png-logo.png")
  // 取回响应的 body 属性，该属性继承 ReadableStream
  .then((response) => response.body)
  .then((body) => body.pipeThrough(new PNGTransformStream()))
  .then((rs) => rs.pipeTo(new FinalDestinationStream()));
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-pipe-to④ |

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

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

参见
--

* `ReadableStream()` 构造函数
* 链式管道传输


ReadableStream：from() 静态方法 - Web API 接口参考

ReadableStream：from() 静态方法
==========================

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

**`ReadableStream.from()`** 静态方法从提供的可迭代或异步可迭代对象返回一个 `ReadableStream`。

该方法可以用于将可迭代或异步可迭代对象包装为可读流，包括数组、集合、promise 数组、异步生成器、`ReadableStream`、Node.js 可读流，等等。

语法
--

```js
ReadableStream.from(anyIterable)
```

### 参数

`anyIterable`

一个可迭代或异步可迭代对象。

### 返回值

一个 `ReadableStream`。

### 异常

`TypeError`

如果传入的参数不是可迭代对象或者异步可迭代对象（未定义 `@@iterator` 或 `@@asyncIterator` 方法），则抛出。如果在迭代期间，下一步的结果不是对象或者 promise 不能兑现对象，则也会抛出。

示例
--

### 将异步迭代器转换为可读流

这个在线示例演示了你如何将一个异步可迭代对象转换为 `ReadableStream`，然后如何消费这个流。

#### HTML

这个 HTML 由 `<pre>` 元素组成，用于日志记录。

```html
<pre id="log"></pre>
```

#### JavaScript

该示例代码创建了一个 `log()` 函数，用于将日志写入日志 HTML 元素。

```js
const logElement = document.getElementById("log");
function log(text) {
  logElement.innerText += `${text}\n`;
}
```

然后，检查是否支持静态方法，如果不支持，则记录不支持的结果。

```js
if (!ReadableStream.from) {
  log("不支持 ReadableStream.from()");
}
```

异步可迭代对象是一个匿名生成器函数，当它被调用三次时，它会产生值 1、2 和 3。该函数被传递给 `ReadableStream.from()`，以创建 `ReadableStream`。

```js
// 定义异步的迭代器
const asyncIterator = (async function\* () {
  yield 1;
  yield 2;
  yield 3;
})();

// 从迭代器创建 ReadableStream
const myReadableStream = ReadableStream.from(asyncIterator);
```

使用可读流示范了几种方式去消费流。以下使用 `for ...await` 循环的代码，因为这个方法是最简单的。循环的每次迭代都会记录来自流的当前分块。

```js
consumeStream(myReadableStream);

// 异步迭代 ReadableStream
async function consumeStream(readableStream) {
  for await (const chunk of myReadableStream) {
    // 使用每个分块做一些事情
    // 这里我们仅记录分块的值
    log(`chunk: ${chunk}`);
  }
}
```

#### 结果

消费流的输出如下所示（如果支持 `ReadableStream.from()`）。

### 将数组转换为 ReadableStream

该示例演示了如何将 `Array` 转换为 `ReadableStream`。
```

<pre id="log"></pre>
```

```
const logElement = document.getElementById("log");
function log(text) {
  logElement.innerText += `${text}\n`;
}

if (!ReadableStream.from) {
  log("不支持 ReadableStream.from()");
}
```

#### JavaScript

可迭代对象仅是一个字符串数组，它被传递给 `ReadableStream.from()` 以创建 `ReadableStream`。

```js
// 一个蔬菜名称的数组
const vegetables = ["Carrot", "Broccoli", "Tomato", "Spinach"];

// 从数组创建 ReadableStream
const myReadableStream = ReadableStream.from(vegetables);
```

```
consumeStream(myReadableStream);

// 异步迭代 ReadableStream
async function consumeStream(readableStream) {
  for await (const chunk of myReadableStream) {
    // 使用每个分块做一些事情
    // 这里我们仅记录分块的值
    log(`chunk: ${chunk}`);
  }
}
```

我们使用与之前示例相同的方式记录和消费流，因此这里不再展示。

#### 结果

输出如下所示。

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-from |

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

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

参见
--

* `ReadableStream`
* 使用可读流


ReadableStream.locked - Web API 接口参考

ReadableStream.locked
=====================

`ReadableStream` 接口的只读属性 **`locked`** 返回可读流是否锁定到 reader。

一个可读流最多可以有一个激活的 reader，并且直到被释放之前都是锁定到该 reader。可以使用 `ReadableStream.getReader()` 方法获取 reader 然后使用 reader 的 `releaseLock()` 方法释放可读流。

值
-

一个布尔值，表示可读流是否已锁定。

示例
--

```js
const stream = new ReadableStream({
  ...
});
const reader = stream.getReader();
stream.locked
// 应返回 true，表示流已经锁定到了一个 reader
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-locked② |

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

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

参见
--

* `ReadableStream()` 构造函数
* 使用可读流


ReadableStream.getReader() - Web API 接口参考

ReadableStream.getReader()
==========================

`ReadableStream` 接口的 **`getReader()`** 方法会创建一个 `reader`，并将流锁定。只有当前 `reader` 将流释放后，其他 `reader` 才能使用。

语法
--

```js
getReader()
getReader(mode)
```

### 参数

`mode` 可选

具有 `mode` 参数的对象，值为 `DOMString` 类型，用来指定要创建的 reader 的类型。其值可以是：

* `"byob"`，结果为 `ReadableStreamBYOBReader` (en-US) 类型，可读取可读字节流。
* `undefined`（或不指定——缺省值），返回 `ReadableStreamDefaultReader`，可以从流中返回单个分块。

### 返回值

`ReadableStreamDefaultReader` 类型或 `ReadableStreamBYOBReader` (en-US) 类型的实例，取决于 `mode` 值。

### 异常

`RangeError`

提供的 mode 值既不是 `"byob"` 也不是 `undefined`。

`TypeError`

尝试创建 reader 的流不是 `ReadableStream` 类型。

示例
--

下面是个简单的例子，在读取 `ReadableStream` 前，使用 `getReader()` 创建一个 `ReadableStreamDefaultReader`。（查看全部代码：Simple random stream example）。按顺序读取每个分块，并传递给 UI，当整个流被读取完毕后，从递归方法中退出，并在 UI 的另一部分输出整个流。

```js
function fetchStream() {
  const reader = stream.getReader();
  let charsReceived = 0;

  // read() 返回了一个 promise
  // 当数据被接收时 resolve
  reader.read().then(function processText({ done, value }) {
    // Result 对象包含了两个属性：
    // done - 当 stream 传完所有数据时则变成 true
    // value - 数据片段。当 done 为 true 时始终为 undefined
    if (done) {
      console.log("Stream complete");
      para.textContent = value;
      return;
    }

    // value for fetch streams is a Uint8Array
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent =
      "Received " +
      charsReceived +
      " characters so far. Current chunk = " +
      chunk;
    list2.appendChild(listItem);

    result += chunk;

    // 再次调用这个函数以读取更多数据
    return reader.read().then(processText);
  });
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-get-reader⑤ |

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

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

参见
--

* `ReadableStream()` 构造函数
* `ReadableStreamDefaultReader`
* `ReadableStreamBYOBReader` (en-US)
* 使用可读流
* 使用可读字节流 (en-US)


ReadableStream.tee() - Web API 接口参考

ReadableStream.tee()
====================

`ReadableStream` 接口的 **`tee()`** 方法对当前的可读流进行拷贝（tee），返回包含两个 `ReadableStream` 实例分支的数组。

这对于两个 reader 顺序的读取或者同时读取流有很大用处（可能以不同的速度）。例如，如果你想要从服务器获取一个响应，然后流式的传输到浏览器，并且也将它流式的传输到 ServiceWorker 缓存中，你可以在 ServiceWorker 执行此操作。由于响应体不能多次使用，你需要两个副本才能这么做。

一个被拷贝的（teed）流将发出两个 `ReadableStream` 分支中其中较*快*速率的消费者控制背压，并且内部队列中未读的数据在 `ReadableStream` 上被较慢的消费，没有任何限制或者背压。因此，当两个内部分支*都*有一个未读的元素时，原来的 `ReadableStream` 的控制器的内部队列将开始填充满，并且当它的 `desiredSize` ≤ 0 或字节流控制器 `desiredSize` (en-US) ≤ 0，然后控制器将停止在底层源上调用 `pull(controller)`，并且传递给 `new ReadableStream()`。如果仅有一个分支被消费，那么主体将会在内存中排队。因此，你不应该使用内置的 `tee()` 去以不同的速度并行读取非常大的流。相反，搜寻一个完全背压到以较*慢*速度消耗分支的实现。

要取消流，需要去取消两个生成的分支。正在被拷贝的流通常会在持续时间内被锁定，阻止其他的 reader 锁定它。

语法
--

```js
tee()
```

### 参数

无。

### 返回值

一个包含两个 `ReadableStream` 实例的 `Array`。

### 异常

`TypeError`

如果源流不是一个 `ReadableStream` 则抛出。

示例
--

在下面的简单示例中，一个先前生成的流被拷贝（tee），然后将两个生成的流（包含在生成的数组的两个成员中）传递给一个函数，该函数将从两个流中读取数据并且将每个流的分块按顺序打印到不同的 UI 部分。完整代码参见简单 tee 示例。

```js
function teeStream() {
  const teedOff = stream.tee();
  fetchStream(teedOff[0], list2);
  fetchStream(teedOff[1], list3);
}

function fetchStream(stream, list) {
  const reader = stream.getReader();
  let charsReceived = 0;

  // read() returns a promise that resolves
  // when a value has been received
  reader.read().then(function processText({ done, value }) {
    // Result objects contain two properties:
    // done - true if the stream has already given you all its data.
    // value - some data. Always undefined when done is true.
    if (done) {
      console.log("Stream complete");
      return;
    }

    // value for fetch streams is a Uint8Array
    charsReceived += value.length;
    const chunk = value;
    let listItem = document.createElement("li");
    listItem.textContent =
      "Read " + charsReceived + " characters so far. Current chunk = " + chunk;
    list.appendChild(listItem);

    // Read some more, and call this function again
    return reader.read().then(processText);
  });
}
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-rs-tee② |

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

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

参见
--

* `ReadableStream()` 构造函数
* 拷贝流