FileSystemSyncAccessHandle：flush() 方法 - Web API 接口参考

FileSystemSyncAccessHandle：flush() 方法
=====================================

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

`FileSystemSyncAccessHandle` 接口的 **`flush()`** 方法用于将通过 `write()` 方法对句柄相关联的文件所做的所有更改持久化保存到磁盘上。

请记住：只当你需要在指定的时间将更改提交到磁盘的时候才需要调用这个方法，不然你可以让底层操作系统在其认为合适的时间点处理这项任务，这大多数情况下都不会有问题。

**备注：** 在规范早期版本中，`close()`、`flush()`、`getSize()` 和 `truncate()` 被错误地规定为异步方法。某些浏览器的旧版本是依照异步方式来实现这些方法的，不过，现今所有支持这些方法的浏览器都将它们实现为同步方法。

语法
--

```js
flush()
```

### 参数

无。

### 返回值

无（`undefined`）。

### 异常

`InvalidStateError` `DOMException`

如果相关的访问句柄已经被关闭，抛出此异常。

示例
--

下面的异步事件处理函数包含在一个 Web Worker 中。当收到来自主线程的消息时，它将执行：

* 创建一个同步文件访问句柄。
* 获取文件的大小然后创建一个 `ArrayBuffer` 来容纳其内容。
* 将文件内容读取到缓冲区。
* 将收到的消息编码然后写入到文件的末尾。
* 将更改保存到磁盘然后关闭访问句柄。

```js
onmessage = async (e) => {
  // 接收从主线程发来的消息
  const message = e.data;

  // 获取草稿文件的句柄
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // 获取同步访问句柄
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // 获取文件的大小
  const fileSize = accessHandle.getSize();
  // 读取文件内容到缓冲区
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // 将消息写入文件末尾
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // 将更改持久化至磁盘
  accessHandle.flush();

  // 用完 FileSystemSyncAccessHandle 后记得把它关闭
  accessHandle.close();
};
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemsyncaccesshandle-flush |

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

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

参见
--

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


FileSystemSyncAccessHandle：write() 方法 - Web API 接口参考

FileSystemSyncAccessHandle：write() 方法
=====================================

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

`FileSystemSyncAccessHandle` 接口的 **`write()`** 方法用于将指定缓冲区中的内容写入到与句柄相关联的文件，可选择在给定的偏移处开始写入。

源私有文件系统中的文件对末端用户来说不可见，因而 `FileSystemSyncAccessHandle` 中的方法不受与运行在用户可见文件系统中的文件上的方法相同的安全性检查。因此，使用 `FileSystemSyncAccessHandle.write()` 进行写入的性能要更为优秀。这使得它适用于重要的、大规模的文件更新，例如对 SQLite 数据库进行更改。

语法
--

```js
write(buffer, options)
```

### 参数

`buffer`

一个表示要写入到文件的缓冲区的 `ArrayBuffer` 或者 `ArrayBufferView` 对象（例如一个 `DataView`）。

`options` 可选

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

`at`

一个表示应当从文件何处开始写入缓冲区的字节偏移量数字。

**备注：** 你无法直接操作 `ArrayBuffer` 中的内容，应该先创建一个像 `Int8Array` 或者 `DataView` 这样的类型化数组对象，用来把缓冲区表示成特定的格式，然后再用类型化数组对象来读写缓冲区的内容。

### 返回值

一个表示写入到文件的字节数的数字。

### 异常

`InvalidStateError` `DOMException`

如果相关的访问句柄已经被关闭，或者对文件二进制数据的修改彻底失败，抛出此异常。

`QuotaExceededError` `DOMException`

如果增长后的数据量超出了浏览器的存储配额，抛出此异常。

`TypeError`

如果底层文件系统不支持从指定的文件偏移处开始写入，抛出此错误。

示例
--

下面的异步事件处理函数包含在一个 Web Worker 中。当收到来自主线程的消息时，它将执行：

* 创建一个同步文件访问句柄。
* 获取文件的大小然后创建一个 `ArrayBuffer` 来容纳其内容。
* 将文件内容读取到缓冲区。
* 将收到的消息编码然后写入到文件的末尾。
* 将更改保存到磁盘然后关闭访问句柄。

```js
onmessage = async (e) => {
  // 接收从主线程发来的消息
  const message = e.data;

  // 获取草稿文件的句柄
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // 获取同步访问句柄
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // 获取文件的大小
  const fileSize = accessHandle.getSize();
  // 读取文件内容到缓冲区
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // 将消息写入文件末尾
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // 将更改持久化至磁盘
  accessHandle.flush();

  // 用完 FileSystemSyncAccessHandle 后记得把它关闭
  accessHandle.close();
};
```

**备注：** 在规范早期版本中，`close()`、`flush()`、`getSize()` 和 `truncate()` 被错误地规定为异步方法。某些浏览器的旧版本是依照异步方式来实现这些方法的，不过，现今所有支持这些方法的浏览器都将它们实现为同步方法。

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemsyncaccesshandle-write |

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

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

参见
--

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


getBBox - Web API 接口参考

getBBox
=======

\*\*`SVGGraphicsElement.getBBox()`\*\*允许我们确定对象适合的最小矩形的坐标。返回的坐标是相对于当前 svg 空间的，即在将所有几何属性应用于目标元素中包含的所有元素之后。

Note: `getBBox` must return the actual bounding box at the time the method was called, even in case the element has not yet been rendered. It also neglects any transformation applied on the element or its parents.

**备注：** `getBBox` returns different values than getBoundingClientRect, as the latter returns value relative to the viewport

Syntax
------
```

let bboxRect = object.getBBox();
```

### Return value

The returned value is a SVGRect (en-US) object, which defines the bounding box. This value is irrespective of any transformation attribute applied to it or the parent elements.

Example
-------

### HTML

```html
<svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
  <g id="group\_text\_1">
    <text x="5" y="16" transform="scale(2, 2)">Hello World!</text>
    <text x="8" y="32" transform="translate(0 20) scale(1.25 1)">
      Hello World Again!
    </text>
  </g>
  <!-- Shows BBox in green -->
  <rect id="rect\_1" stroke="#00ff00" stroke-width="3" fill="none"></rect>
  <!-- Shows BoundingClientRect in red -->
  <rect id="rect\_2" stroke="#ff0000" stroke-width="3" fill="none"></rect>
</svg>
```

### JavaScript

```js
var rectBBox = document.querySelector("#rect\_1");
var rectBoundingClientRect = document.querySelector("#rect\_2");
var groupElement = document.querySelector("#group\_text\_1");

var bboxGroup = groupElement.getBBox();
rectBBox.setAttribute("x", bboxGroup.x);
rectBBox.setAttribute("y", bboxGroup.y);
rectBBox.setAttribute("width", bboxGroup.width);
rectBBox.setAttribute("height", bboxGroup.height);

var boundingClientRectGroup = groupElement.getBoundingClientRect();
rectBoundingClientRect.setAttribute("x", boundingClientRectGroup.x);
rectBoundingClientRect.setAttribute("y", boundingClientRectGroup.y);
rectBoundingClientRect.setAttribute("width", boundingClientRectGroup.width);
rectBoundingClientRect.setAttribute("height", boundingClientRectGroup.height);
```

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGGraphicsElement\_\_getBBox |

See also
--------

* getBBox in SVG Primer


GamepadButton.pressed - Web API 接口参考

GamepadButton.pressed
=====================

`GamepadButton`接口下的 **`GamepadButton.pressed`** 属性返回一个表示按钮当然是被按下了 (`true`) 还是没有被按下 (`false`) 的布尔值。

语法
--
```

var isPressed = navigator.getGamepads()[0].pressed;
```

示例
--

```js
var gp = navigator.getGamepads()[0]; // 获取第一个控制器对象

if (gp.buttons[0].pressed == true) {
  // 响应按钮按下
}
```

值
-

一个 `boolean` (en-US) (布尔值)。

规范
--

| Specification |
| --- |
| Gamepad # dom-gamepadbutton-pressed |

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

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

参见
--

* 使用 Gamepad API


GamepadButton.value - Web API 接口参考

GamepadButton.value
===================

`GamepadButton`接口下的 **`GamepadButton.value`** 属性返回一个双精浮点值来表示许多现代控制器上的模拟按钮的状态，比如说扳机键。

其值被规范于范围 `0.0` — `1.0` 内， `0.0` 表示按钮没有被按下，`1.0` 则表示按钮被完全按下。

语法
--

```js
var pressState = navigator.getGamepads()[0].value;
// 只读属性、双精浮点值
```

示例
--

```js
var gp = navigator.getGamepads()[0];

if (gp.buttons[0].value > 0) {
  // 响应模拟按钮被按下
}
```

值
-

一个 `double` (双精浮点值)。

规范
--

| Specification |
| --- |
| Gamepad # dom-gamepadbutton-value |

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

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

参见
--

使用 Gamepad API


Response.arrayBuffer() - Web API 接口参考

Response.arrayBuffer()
======================

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

`Response`上的方法 **`arrayBuffer()`** 接受一个 `Response` 流，并等待其读取完成。它返回一个 promise 实例，并 resolve 一个 `ArrayBuffer` 对象。

语法
--

```js
response.arrayBuffer().then(function(buffer) {
  // do something with buffer
)};
```

### 参数

无。

### 返回值

A promise that resolves with an `ArrayBuffer`.

例子
--

In our fetch array buffer example (run fetch array buffer live), we have a Play button. When pressed, the `getData()` function is run.

In `getData()` we create a new request using the `Request.Request` constructor, then use it to fetch an OGG music track. We also use `AudioContext.createBufferSource` to create an audio buffer source. When the fetch is successful, we read an `ArrayBuffer` out of the response using `arrayBuffer()`, decode the audio data using `AudioContext.decodeAudioData`, set the decoded data as the audio buffer source's buffer (`source.buffer`), then connect the source up to the `AudioContext.destination`.

Once `getData()` has finished running, we start the audio source playing with `start(0)`, then disable the play button so it can't be clicked again when it is already playing (this would cause an error.)

```js
function getData() {
  source = audioCtx.createBufferSource();

  var myRequest = new Request("viper.ogg");

  fetch(myRequest).then(function (response) {
    response.arrayBuffer().then(function (buffer) {
      audioCtx.decodeAudioData(buffer, function (decodedData) {
        source.buffer = decodedData;
        source.connect(audioCtx.destination);
      });
    });
  });
}

// wire up buttons to stop and play audio

play.onclick = function () {
  getData();
  source.start(0);
  play.setAttribute("disabled", "disabled");
};
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-arraybuffer① |

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

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

参考
--

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.formData() - Web API 接口参考

Response.formData()
===================

`Response` 对象中的\*\*`formData()`\*\* 方法将 `Response` 对象中的所承载的数据流读取并封装成为一个对象，该方法将返回一个 **`Promise`** 对象，该对象将产生一个`FormData` 对象。

**备注：** 该方法主要与 service worker 有关。如果客户端提交的一个表单请求被 Service Worker 所截取，你可以像下述的样例一样，调用 `formData()` 方法来获取一个 key-value 字典，对该字典可以进行修饰，然后将修饰后的表填提交给远端服务器 (或在本地应用)。

语法
--
```

response.formData()
.then(function(formdata) {
  // do something with your formdata
});
```

### 参数

无。

### 返回值

生成 `FormData`对象的`Promise` (en-US) 对象。

样例
--

待定。

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-formdata① |

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

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

See also
--------

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.blob() - Web API 接口参考

Response.blob()
===============

`Response` mixin 的 \*\*`blob()`\*\*方法使用一个 `Response` 流，并将其读取完成。它返回一个使用`Blob`解决的 promise。

句法
--

```js
response.blob().then(function (myBlob) {
  // do something with myBlob
});
```

### 参数

None.

### 返回值

A promise that resolves with a `Blob`.

例子
--

在我们 fetch request example (run fetch request live) 中，我们使用Request.Request构造方法创建了一个新的 request 对象，然后使用它来获取一个 JPG 文件。当 fetch 成功的时候，我们使用 blob() 从 response 中读取一个Blob对象，并使用URL.createObjectURL 将它放入一个 object URL，然后把 URL 设置为img元素的 src 属性以显示这张图片。

```js
var myImage = document.querySelector("img");

var myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then(function (response) {
    return response.blob();
  })
  .then(function (myBlob) {
    var objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-blob① |

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

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

另见
--

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.text() - Web API 接口参考

Response.text()
===============

`Response` mixin 的 **`text()`** 方法提供了一个可供读取的“返回流”（`Response` stream），并将它读取完。它返回一个包含 `USVString` 对象（也就是文本）的 Promise 对象，返回结果的编码*永远是* UTF-8。

语法
--

```js
response.text().then(function (text) {
  // do something with the text response
});
```

### 参数

无。

### 返回值

A promise that resolves with a `USVString`.

示例
--

在我们 fetch text example (运行 fetch text live) 的案例中，我们有一个 `<article>` 元素和三个链接（储存在 `myLinks` 数组中），首先，遍历 `myLinks` 数组，并且给数组中的所有元素添加 `onclick` 事件监听器，当按钮被点击的时候，链接的 `data-page` 标识作为会参数传入 `getData()` 中。

当进入 `getData()` 函数，我们使用 `Request()` 构造函数创建了一个请求（Request）对象，然后，使用它获取指定的`.txt`的文件，当 fetch 函数执行成功，我们使用 `text()` 函数来返回一个`USVString` (text) 对象，将它设置到 `<article>` 对象的`innerHTML`（元素文本）中。

```js
const myArticle = document.querySelector("article");
const myLinks = document.querySelectorAll("ul a");

for (i = 0; i <= myLinks.length - 1; i++) {
  myLinks[i].onclick = function (e) {
    e.preventDefault();
    var linkData = e.target.getAttribute("data-page");
    getData(linkData);
  };
}

function getData(pageId) {
  console.log(pageId);
  const myRequest = new Request(pageId + ".txt");
  fetch(myRequest).then(function (response) {
    return response.text().then(function (text) {
      myArticle.innerHTML = text;
    });
  });
}
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-text① |

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

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

See also
--------

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.status - Web API 接口参考

Response.status
===============

`Response` 接口的\*\*`status`\*\* 只读属性包含响应的状态代码（例如，成功为 200）。

语法
--
```

let myStatus = response.status;
```

### 值

一个数字（确切来讲是一个 unsigned short）

示例
--

In our Fetch Response example (see Fetch Response live) we create a new `Request` object using the `Request()` constructor, passing it a JPG path. We then fetch this request using `fetch()`, extract a blob from the response using `Body.blob` (en-US), create an object URL out of it using `URL.createObjectURL`, and display this in an `<img>`.

Note that at the top of the `fetch()` block we log the response `status` value to the console.

```js
var myImage = document.querySelector("img");

var myRequest = new Request("flowers.jpg");

fetch(myRequest).then(function (response) {
  console.log(response.status); // returns 200
  response.blob().then(function (myBlob) {
    var objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-status① |

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

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

See also
--------

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.bodyUsed - Web API 接口参考

Response.bodyUsed
=================

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

**`bodyUsed`** 是 `Response` mixin 中的一个只读属性。用以表示该 body 是否被使用过。

语法
--

```js
var myBodyUsed = response.bodyUsed;
```

### 可能的值

`Boolean` (en-US).

示例
--

在以下fetch 请求示例（运行 fetch request live）。通过`Request.Request`构造器创建了一个 fetch 请求，来获得一张 JPG 图片。当 fetch 成功后，通过`Blob` 来使用了 fetch 返回的资源--`URL.createObjectURL`创建该资源的 URL，并作为 `<img>`元素的 src 源来显示图片。

注意：在 `response.blob()` 被调用前后，输出 `response.bodyUsed` 的差异。

### HTML Content

```html
<img
 class="my-image"
 src="https://wikipedia.org/static/images/project-logos/frwiki-1.5x.png" />
```

### JS Content

```js
var myImage = document.querySelector(".my-image");
fetch("https://upload.wikimedia.org/wikipedia/commons/7/77/Delete\_key1.jpg")
  .then(function (response) {
    console.log(response.bodyUsed);
    var res = response.blob();
    console.log(response.bodyUsed);
    return res;
  })
  .then(function (response) {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });
```

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

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-bodyused① |

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

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

See also
--------

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.ok - Web API 接口参考

Response.ok
===========

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

`Response` 接口的只读属性 **`ok`** 包含一个布尔值，表明响应是否成功（状态码在 200-299 范围内）.

语法
--
```

var myOK = response.ok;
```

### 值

`Boolean` (en-US).

示例
--

In our Fetch Response example (see Fetch Response live) we create a new `Request` object using the `Request()` constructor, passing it a JPG path. We then fetch this request using `fetch()`, extract a blob from the response using `Body.blob` (en-US), create an object URL out of it using `URL.createObjectURL`, and display this in an `<img>`.

Note that at the top of the `fetch()` block we log the response `ok` value to the console.

```js
var myImage = document.querySelector("img");

var myRequest = new Request("flowers.jpg");

fetch(myRequest).then(function (response) {
  console.log(response.ok); // returns true if the response returned successfully
  response.blob().then(function (myBlob) {
    var objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-ok② |

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

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

参见
--

* ServiceWorker API
* HTTP 访问控制（CORS）
* HTTP


Response.redirected - Web API 接口参考

Response.redirected
===================

`Response` 接口中只读的 **`redirected`** 属性表明该响应是否为一个重定向的请求的结果。

**备注：** 依赖 **`redirected`** 过滤重定向很容易导致虚假的重定向阻止你的内容像预期一样生效。因此，当调用 `fetch()` 时你应该进行过滤操作。详见下面 禁用重定向 的例子。

语法
--
```

var isRedirected = Response.redirected;
```

### 返回值

一个布尔值 (`Boolean` (en-US)), 如果响应来自重定向的请求，那么将返回 `true`.

示例
--

### 检测重定向

检测某个响应是否来自一个重定向的请求就如同检测 `Response` 对象中这个标识一样容易。在下面的代码中，当 fetch 操作引起了重定向，一段文本信息会被插入到元素中。但需要注意的是，这不像下面 禁用重定向 所描述的当重定向不合法时全部阻止的行为一样安全。

```js
fetch("awesome-picture.jpg")
  .then(function (response) {
    let elem = document.getElementById("warning-message-box");
    if (response.redirected) {
      elem.innerHTML = "Unexpected redirect";
    } else {
      elem.innerHTML = "";
    }
    return response.blob();
  })
  .then(function (imageBlob) {
    let imgObjectURL = URL.createObjectURL(imageBlob);
    document.getElementById("img-element-id").src = imgObjectURL;
  });
```

### 禁用重定向

由于使用 **`redirected`** 过滤重定向会允许虚假的重定向，你应该像下面的例子这样，当调用 `fetch()` 时在 `init` 参数中设置重定向模式为 `"error"` :

```js
fetch("awesome-picture.jpg", { redirect: "error" })
  .then(function (response) {
    return response.blob();
  })
  .then(function (imageBlob) {
    let imgObjectURL = URL.createObjectURL(imageBlob);
    document.getElementById("img-element-id").src = imgObjectURL;
  });
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-redirected① |

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

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

参见
--

* Fetch API
* ServiceWorker API
* HTTP 访问控制（CORS）
* HTTP


Response.json() - Web API 接口参考

Response.json()
===============

`Response` mixin 的 **`json()`** 方法接收一个 `Response` 流，并将其读取完成。它返回一个 Promise，Promise 的解析 resolve 结果是将文本体解析为 `JSON`。语法
--

```js
response.json().then((data) => {
  // do something with your data
});
```

### 参数

没有。

### 返回值

返回一个被解析为 `JSON` 格式的 promise 对象，这可以是任何可以由 JSON 表示的东西 - 一个 object，一个 array，一个 string，一个 number...

示例
--

在我们的 fetch json 示例 中 (运行 fetch json live), 我们使用 `Request.Request` 构造函数创建一个新的请求，然后使用它来获取一个 `.json` 文件。当获取成功时，我们使用 `json()` 读取并解析数据，然后像预期的那样从结果对象中读取值，并将其插入到列表项中以显示我们的产品数据。

```js
const myList = document.querySelector("ul");
const myRequest = new Request("products.json");

fetch(myRequest)
  .then((response) => response.json())
  .then((data) => {
    for (const product of data.products) {
      let listItem = document.createElement("li");
      listItem.appendChild(document.createElement("strong")).textContent =
        product.Name;
      listItem.append(` can be found in ${product.Location}. Cost: `);
      listItem.appendChild(document.createElement("strong")).textContent =
        `£${product.Price}`;
      myList.appendChild(listItem);
    }
  });
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-json① |

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

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

参见
--

* ServiceWorker API
* HTTP 访问控制（CORS）
* HTTP


Response.type - Web API 接口参考

Response.type
=============

`Response` 接口的 **`type`** 只读属性包含一种响应的类型。它可以是以下某一种值：

* `basic`：标准值，同源响应，暴露除了“Set-Cookie”之外的所有标头。
* `cors`：从有效的跨源请求接收到响应。某些标头和主体可以被访问。
* `error`：网络错误。没有有用的描述错误的信息。响应的状态为 0，header 为空且不可变。这是从 `Response.error()` 中获得的响应的类型。
* `opaque`：对跨源资源的“no-cors”请求的响应。严格限制。
* `opaqueredirect`：fetch 请求是通过 `redirect: "manual"` 发出的。响应的状态是 0，标头是空的，主体是 null，trailer 是空的。

**备注：** “错误”响应从来没有真正暴露于脚本：这样的响应，`fetch()` 将被 promise 拒绝。

值
-

`ResponseType` 字符串表示响应的类型。

示例
--

 在我们的 Fetch 响应示例中（参见 Fetch 响应在线演示），我们使用 `Request()` 构造函数创建了一个新的 `Request` 对象，并向其传递了一个 JPG 路径。然后，我们使用
 `fetch()` 获取到这个请求，使用 `Response.blob` 从响应中提取到 blob，使用 `URL.createObjectURL` 从中创建一个对象的 URL，并将其显示在 `<img>` 中。

注意，在 `fetch()` 代码块的顶部，我们将响应的 `type` 记录在控制台。

```js
const myImage = document.querySelector("img");
const myRequest = new Request("flowers.jpg");
fetch(myRequest).then((response) => {
  console.log(response.type); // returns basic by default
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-type① |

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

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

参见
--

* ServiceWorker API
* HTTP 访问控制（CORS）
* HTTP


Response.clone() - Web API 接口参考

Response.clone()
================

`Response` 接口的 **`clone()`** 方法创建一个响应对象的克隆，这个对象在所有方面都是相同的，但是储存在不同的变量中。

类似于底层的 `ReadableStream.tee` api，克隆的 `Response` 的 `body` 将以两个 body 的更*快*消费者的速度发出背压信号，并且未读的数据在消费较慢的 `body` 上进行内部排队，没有任何限制或者背压。背压指的是数据流消费者（如这种情况，读取响应正文的代码）让数据生产者减缓速度（如 TCP 服务器）以免在应用程序等待使用的内存中加载大量数据的机制。如果仅消费了一个克隆分支，那么整个 body 都将在内存中缓冲。因此，`clone()` 是按顺序读取两次响应的一种方式，但是你不应该在并行时以不同的速度使用它读取非常大的 body。

如果响应体已经被使用，`clone()` 抛出 `TypeError`。事实上，`clone()` 存在的主要原因是允许 body 对象可以使用多次（当它们是一次性使用时）。

语法
--

```js
clone()
```

### 参数

无。

### 返回值

一个 `Response` 对象。

示例
--

在我们的 Fetch Response 克隆示例（请参阅在线 Fetch Response 克隆示例）我们使用 `Request()` 构造函数创建一个新的 `Request` 来传递一个 JPG 路径。然后我们使用 `fetch()` 获取这个请求。当 fetch 成功兑现时，我们克隆它，使用两个 `Body.blob` (en-US) 调用从两个响应中提取 blob，使用 `URL.createObjectURL` 从 blob 创建对象 URL，并将它们显示在两个单独的 `<img>` 元素中。

```js
const image1 = document.querySelector(".img1");
const image2 = document.querySelector(".img2");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  const response2 = response.clone();

  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    image1.src = objectURL;
  });

  response2.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    image2.src = objectURL;
  });
});
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-clone① |

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

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

参见
--

* ServiceWorker API
* HTTP access control (CORS)
* HTTP


Response.headers - Web API 接口参考

Response.headers
================

`Response` 接口的只读属性 **`headers`** 包含与响应关联的`Headers`对象。

语法
--
```

var myHeaders = response.headers;
```

### 值

一个 `Headers` 对象。

例程
--

在我们的 Fetch Response example 例程中（详见 Fetch Response live），我们使用`Request()`构造函数创建了一个新的`Request`对象，传入了一个 jpg 路径。我们接着使用`fetch()`触发了请求，用`Body.blob` (en-US)从响应中提取了 blob 实例，使用`URL.createObjectURL`创建了一个 URL 对象，然后显示在了`<img>`中。

注意，在`fetch()`的顶级块中我们输出了`headers`到控制台。

```js
var myImage = document.querySelector("img");

var myRequest = new Request("flowers.jpg");

fetch(myRequest).then(function (response) {
  console.log(response.headers); // returns a Headers{} object
  response.blob().then(function (myBlob) {
    var objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-headers① |

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

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

See also
--------

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


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

Response.error()
================

`Response` 接口的 `error()` 方法返回一个包含网络错误相关信息的新 `Response` 对象。

**备注：** 这主要与 Service Workers 有关；如果你愿意，可以使用 error 方法返回错误。错误响应的 `type` 被设置为 `error`。

**备注：** 一个“错误”的 `Response` 不会真正地暴露给脚本：例如 `fetch()` 的“错误”响应将会返回 promise 的 reject 状态。

语法
--
```

error()
```

### 参数

无

### 返回值

一个 `Response` 对象。

示例
--

待定（似乎还没有在任何地方得到支持）。

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-error① |

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

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

参见
--

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response：url 属性 - Web API 接口参考

Response：url 属性
===============

`Response` 接口的只读属性 **`url`** 包含了响应的 URL 地址。`url` 属性值为经过重定向后最终获得的 URL 地址。

值
-

一个字符串。

示例
--

在 Fetch Response 示例 中（请参见 Fetch Response 实时演示），我们使用 `Request()` 构造函数创建了一个新的 `Request` 对象，并向其传递了 JPG 的路径。然后，我们使用 `fetch()` 获取该请求，使用 `Response.blob` 从响应中提取一个 blob，使用 `URL.createObjectURL` 从中创建一个对象 URL，并将其显示在 `<img>` 中。

请注意，在 `fetch()` 块的顶部，我们会将响应 `URL` 记录到控制台。

```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    console.log("response.url =", response.url); // response.url = https://mdn.github.io/dom-examples/fetch/fetch-response/flowers.jpg
    return response.blob();
  })
  .then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-url① |

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

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

参见
--

* ServiceWorker API
* HTTP 访问控制（CORS）
* HTTP


Response.redirect() - Web API 接口参考

Response.redirect()
===================

`Response` 接口的 **`redirect()`** 方法返回一个可以重定向到指定 URL 的 `Response` 。

**备注：** 主要和 ServiceWorker API (en-US) 有关。A controlling service worker could intercept a page's request and redirect it as desired. This will actually lead to a real redirect if a service worker sends it upstream.

语法
--
```

var response = Response.redirect(url, status);
```

### 参数

`url`

The URL that the new response is to originate from.

`status` 可选

用于 response 的可选的状态码 (e.g., `302`.)

### 返回值

一个 `Response` 对象。

### 异常

| 异常类型 | 说明 |
| --- | --- |
| `RangeError` | status 不是一个重定向的状态码。 |
| `TypeError` | url 不可用。 |

示例
--

```js
responseObj.redirect("https://www.example.com", 302);
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response-redirect① |

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

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

参阅
--

* ServiceWorker API (en-US)
* HTTP 访问控制 (CORS)
* HTTP


Response() - Web API 接口参考

Response()
==========

**`Response()`** 构造函数创建了一个新的 `Response` 对象。

语法
--
```

let myResponse = new Response(body, init);
```

### 参数

*body* 可选

一个定义 response 中 body 的对象。可以为 `null` ，或是以下其中一个：

* `Blob`
* `BufferSource`
* `FormData`
* `ReadableStream`
* `URLSearchParams`
* `USVString`

*init* 可选

一个参数 (options) 对象，包含要应用到 response 上的任何自定义设置。可能参数 (options) 是：

* `status`: response 的状态码，例如：`200`.
* `statusText`: 和状态码关联的状态消息，例如：`OK`.
* `headers`: 你想加到 response 上的任何 headers，包含了一个 `Headers` 对象或满足对象语法的 `ByteString` key/value 对 (详见 HTTP headers).

例子
--

在我们的 Fetch Response 示例中 (参见Fetch Response live) 我们使用构造函数创建了一个新的 Response 对象，传递一个新的 `Blob` 作为 body，和一个包含自定义 `status` 和`statusText`的 init 对象：

```js
var myBlob = new Blob();
var init = { status: 200, statusText: "SuperSmashingGreat!" };
var myResponse = new Response(myBlob, init);
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-response① |

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

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

See also
--------

* ServiceWorker API (en-US)
* HTTP access control (CORS)
* HTTP


Response.body - Web API 接口参考

Response.body
=============

`Response` 接口的只读属性 **`body`** 是暴露响应体内容的 `ReadableStream`。

值
-

一个 `ReadableStream`，或者对于使用空的 `body` 属性构建的任意的 `Response` 对象，或没有任何主体的实际 HTTP 响应，则为 `null`。

**备注：** 对于没有主体的响应（例如，对 `HEAD` 请求的响应或 `204 No Content`），当前的浏览器实际上不符合将 `body` 属性设置为 `null` 的规范要求。

示例
--

在我们的简单 pump 流示例中，我们获取一个图片，使用 `response.body` 暴露响应的流，用 `ReadableStream.getReader()` 创建一个 reader，然后将其置入第二个自定义读取流中——有效的创建了一个完全相同的图片副本。

```js
const image = document.getElementById("target");

// 请求原始图片
fetch("./tortoise.png")
  // 取出 body
  .then((response) => response.body)
  .then((body) => {
    const reader = body.getReader();

    return new ReadableStream({
      start(controller) {
        return pump();

        function pump() {
          return reader.read().then(({ done, value }) => {
            // 读不到更多数据就关闭流
            if (done) {
              controller.close();
              return;
            }

            // 将下一个数据块置入流中
            controller.enqueue(value);
            return pump();
          });
        }
      },
    });
  })
  .then((stream) => new Response(stream))
  .then((response) => response.blob())
  .then((blob) => URL.createObjectURL(blob))
  .then((url) => console.log((image.src = url)))
  .catch((err) => console.error(err));
```

规范
--

| Specification |
| --- |
| Fetch Standard # ref-for-dom-body-body① |

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

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

参见
--

* Fetch API
* Stream API
* ServiceWorker API (en-US)


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

WritableStreamDefaultController.error()
=======================================

`WritableStreamDefaultController` 接口的 **`error()`** 方法会导致未来任何与关联的流的交互出错。

这个方法很少被使用，因为通常从底层接收器的一个方法返回一个拒绝的 promise 足矣。但是，在响应与底层接收器交互的正常生命周期之外的事件中，使用 error() 来立即关闭一个流则会很有用。

语法
--

```js
error(message)
```

### 参数

`message`

一个字符串，表示你希望在调用该方法以后的交互所应该抛出的错误。

### 返回值

无（`undefined`）。

### 异常

`TypeError`

你尝试调用 error 方法的流不是一个 `WritableStream`。

示例
--

```js
const writableStream = new WritableStream({
  start(controller) {
    // do stuff with controller
    // error stream if necessary
    controller.error('My error is broken');
  },
  write(chunk, controller) {
    ...
  },
  close(controller) {
    ...
  },
  abort(err) {
    ...
  }
});
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-ws-default-controller-error① |

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

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


CSSStyleDeclaration.getPropertyCSSValue() - Web API 接口参考

CSSStyleDeclaration.getPropertyCSSValue()
=========================================

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

**CSSStyleDeclaration.getPropertyCSSValue()** 方法接口返回一个`CSSValue` 包含一个属性的 CSS 值。请注意，如果属性名称是速记属性，则返回 null。

现在你应该使用 `CSSStyleDeclaration.getPropertyValue()`。

语法
--
```

let value = style.getPropertyCSSValue(property);
```

### 参数

* *`property`* is a `DOMString` representing the property name to be retrieved.
### 返回值

* `value` is a `CSSValue` containing the CSS value for a property. If none exists, returns `null`.
示例
--

The following JavaScript code gets an object containing the computed RGB values of the `color` CSS property:

```js
var style = window.getComputedStyle(elem, null);
var rgbObj = style.getPropertyCSSValue("color").getRGBColorValue();
```

规范
--

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

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

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

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


CSSStyleDeclaration.getPropertyPriority() - Web API 接口参考

CSSStyleDeclaration.getPropertyPriority()
=========================================

**CSSStyleDeclaration.getPropertyPriority()** 方法会根据传入的 CSS 属性，返回一个 `DOMString` 来表示该属性的优先级。

Syntax
------
```

var priority = style.getPropertyPriority(property);
```

### 参数

* *`property`* 是一个`DOMString`，表示要检查的属性名。
### 返回值

* `priority` 是一个`DOMString`，用以表示属性优先级。存在，就返回（例如：`"important"`）；不存在，则返回空字符串。
例子
--

下面的代码检查了`margin`，在 CSS 规则中是否被设置为 important 优先级。

```js
var declaration = document.styleSheets[0].cssRules[0].style;
var isImportant = declaration.getPropertyPriority("margin") === "important";
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-getpropertypriority |

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

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


CSSStyleDeclaration.getPropertyValue() - Web API 接口参考

CSSStyleDeclaration.getPropertyValue()
======================================

**CSSStyleDeclaration.getPropertyValue()** 接口返回一个 `DOMString` ，其中包含请求的 CSS 属性的值。

语法
--
```

var value = style.getPropertyValue(property);
```

### 参数

* *`property`* 是一个 `DOMString`，是需要查询的 CSS 属性名称。
### 返回值

* `value` 是 `DOMString` ，包含查找属性的值。若对应属性没有设置，则返回空字符串。
示例
--

下述示例使用一个 CSS 选择器规则查询对应的`margin` 属性的值：

```js
var declaration = document.styleSheets[0].cssRules[0].style;
var value = declaration.getPropertyValue("margin"); // "1px 2px"
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-getpropertyvalue |

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

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


CSSStyleDeclaration.item() - Web API 接口参考

CSSStyleDeclaration.item()
==========================

`CSSStyleDeclaration.item()` 通过下标从 `CSSStyleDeclaration` 返回一个 CSS 属性值。只要传入参数这个方法就不会抛出异常；当传入的下标越界时会返回空字符串，当未传入参数时会抛出一个 `TypeError` 。

语法
--
```

var propertyName = style.item(index);
```

### 参数

* *`index`* 是需要查找节点的索引，索引下标从零开始。
### Return value

* *`propertyName`* 是一个 `DOMString` ，是在特定索引位置下的属性的名称。

使用以下的 javascript 语法可以通过索引从 style 的节点列表中获取对应值：
```

var propertyName = style[index];
```

范例
--

```js
var style = document.getElementById("div1").style;
var propertyName = style.item(1); // or simply style[1] - returns the second style listed
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-item |

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

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


CSSStyleDeclaration.length - Web API 接口参考

CSSStyleDeclaration.length
==========================

这是一个只读的属性，它返回一个指定元素声明过的样式个数

语法
--
```

var num = styles.length;
```

### 值

指定元素上明确声明过的样式属性个数。

示例
--

获取下面 HTML 元素明确设置过的属性个数：

```html
<div
 id="div1"
 style="margin: 0 10px; background-color: #CA1; font-family: monospace"></div>
```

JavaScript 代码：
```

var myDiv = document.getElementById('div1'); var divStyle = myDiv.style; var len = divStyle.length; // 6
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-length |

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

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


CSSStyleDeclaration.setProperty() - Web API 接口参考

CSSStyleDeclaration.setProperty()
=================================

**`CSSStyleDeclaration.setProperty()`** 方法接口为一个声明了 CSS 样式的对象设置一个新的值。

语法
--
```

style.setProperty(propertyName, value, priority);
```

### 参数

* *`propertyName`* 是一个 `DOMString` ，代表被更改的 CSS 属性。
* *`value`*可选 是一个 `DOMString` ，含有新的属性值。如果没有指定，则当作空字符串。
    + 注意：*`value`* 不能包含 `"!important"` --那个应该使用 *`priority`* 参数。
* *`priority`*可选 是一个 `DOMString` 允许设置 "important" CSS 优先级。如果没有指定，则当作空字符串。
### 返回值

* `undefined`
### 异常

* `DOMException` (NoModificationAllowedError)：如果属性或装饰块为只读的，抛出此异常。

JavaScript 有一个特别的，更简单的在 CSSStyleDeclaration 对象上设置 CSS 属性值的语法：
```

style.cssPropertyName = 'value';
```

示例
--

下面的 Javascript 代码为一个选中元素样式的 `margin` 属性设置一个新的值：

```js
var declaration = document.styleSheets[0].rules[0].style;
declaration.setProperty("margin", "1px 2px");
// Equivalent to:
// declaration.margin = '1px 2px';
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-setproperty |

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

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


CSSStyleDeclaration.removeProperty() - Web API 接口参考

CSSStyleDeclaration.removeProperty()
====================================

`CSSStyleDeclaration.removeProperty()` 方法移除 style 对象的一个属性。

语法
--

```js
var oldValue = style.removeProperty(property);
```

### 参数

* *`property`* 是一个 `DOMString` ，代表要移除的属性名。注意由多个单词组成的属性要用连字符连接各个单词，不接收驼峰命名法的形式。
### 返回值

* `oldValue` 是一个 `DOMString` ，等于被移除的属性在移除前的属性值。
### 异常

* `DOMException` NO\_MODIFICATION\_ALLOWED\_ERR: 如果属性或声明块为只读，抛出此异常。
例子
--

下面的 JavaScript 代码从样式表里移除了 `margin` 属性：

```js
var declaration = document.styleSheets[0].rules[0].style;
var oldValue = declaration.removeProperty("margin");
```

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstyledeclaration-removeproperty |

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

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


Blob：slice() 方法 - Web API 接口参考

Blob：slice() 方法
===============

`Blob` 接口的 **`slice()`** 方法创建并返回一个新的 `Blob` 对象，该对象包含调用它的 blob 的子集中的数据。

语法
--

```js
slice()
slice(start)
slice(start, end)
slice(start, end, contentType)
```

### 参数

`start` 可选

这个参数代表 `Blob` 里的第一个会被拷贝进新的 `Blob` 的字节的索引。如果你传入的是一个负数，那么这个偏移量将会从数据的末尾从后到前开始计算。例如，-10 将会是 `Blob` 的倒数第十个字节。它的默认值是 0。如果你传入的 `start` 的长度大于源 `Blob` 的长度，那么返回的将会是一个长度为 0 并且不包含任何数据的一个 `Blob` 对象。

`end` 可选

这个参数代表 `Blob` 里的第一个*不会*被拷贝进新的 `Blob` 的字节的索引（换句话说，这个索引的字节不会被拷贝）。如果你传入了一个负数，那么这个偏移量将会从数据的末尾从后到前开始计算。举例来说，-10 将会是 `Blob` 的倒数第十个字节。它的默认值就是它的原始长度 `size`。

`contentType` 可选

给新的 `Blob` 赋予一个新的内容类型。这将会把它的 `type` 属性设为被传入的值。它的默认值是一个空字符串。

### 返回值

一个新的 `Blob` 对象，它包含了调用该方法的原始 blob 对象所包含数据的指定子集。原始的 blob 不会被改变。

规范
--

| Specification |
| --- |
| File API # dfn-slice |

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

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

参见
--

* `Blob`
* 在 web 应用程序中使用文件


Blob.type - Web API 接口参考

Blob.type
=========

`Blob` 对象的 **`type`** 属性给出文件的 MIME 类型。

值
-

一个包含文件 MIME 类型的字符串，如果无法确定类型则返回空字符串。

**备注：** 基于当前的实现，浏览器不会读取文件的字节流来确定其媒体类型。其根据文件扩展名进行假设；一个被重命名为 .txt 的 PNG 图像文件会返回“*text/plain*”而不是“*image/png*”。此外，`blob.type` 通常只对常见的文件类型（如图像、HTML 文档、音频和视频）有效。不常见的文件扩展名会返回空字符串。客户端配置（例如 Windows 注册表）可能会导致常见类型出现意外值。**开发者不应该仅依赖此属性作为验证方案。**

示例
--

这个示例要求用户选择一些文件，然后检查每个文件以确保其是指定的图片文件类型之一。

### HTML

```html
<input type="file" id="input" multiple />
<output id="output">选择图片文件……</output>
```

```
output {
  display: block;
  margin-top: 16px;
}
```

### JavaScript

```js
// 我们的程序只允许 GIF、PNG 和 JPEG 类型的图片
const allowedFileTypes = ["image/png", "image/jpeg", "image/gif"];

const input = document.getElementById("input");
const output = document.getElementById("output");

input.addEventListener("change", (event) => {
  const files = event.target.files;

  if (files.length === 0) {
    output.innerText = "选择图片文件…";
    return;
  }

  const allAllowed = Array.from(files).every((file) =>
    allowedFileTypes.includes(file.type),
  );
  output.innerText = allAllowed ? "所有文件都符合！" : "请只选择图片文件。";
});
```

### 结果

规范
--

| Specification |
| --- |
| File API # dfn-type |

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

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

参见
--

* `Blob`
* 在 web 应用程序中使用文件


Blob.stream() - Web API 接口参考

Blob.stream()
=============

`Blob` 接口的 **`stream()`** 方法返回一个 `ReadableStream` 对象，读取它将返回包含在 `Blob` 中的数据。

语法
--

```js
stream()
```

### 参数

无。

### 返回值

一个 `ReadableStream` 对象，读取后返回 `Blob` 的内容。

使用说明
----

使用 `stream()` 函数与其返回的 `ReadableStream` 对象，你将得到一些有趣的能力：

* 调用方法 `getReader()`，在返回的 stream 上获取一个对象，通过 `ReadableStreamDefaultReader` 接口提供的 `read()` 方法读取 blob 对象的方法。
* 调用返回 stream 对象的 `pipeTo()` 方法将 blob 对象的数据传输到可写流。
* 调用返回 stream 对象的 `tee()` 方法以准备可读流。该方法会返回一个数组，该数组包含两个新的 `ReadableStream` 对象，每个对象都会返回 `Blob` 的内容。
* 调用返回 stream 对象的 `pipeThrough()` 方法，通过一个 `TransformStream` 对象或其他任意可读可写对传输流对象。
规范
--

| Specification |
| --- |
| File API # dom-blob-stream |

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

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

参见
--

* `Body.body` (en-US)
* Streams API


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

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

**`Blob()`** 构造函数返回一个新的 `Blob` 对象。blob 的内容由参数 `array` 中给出的值串联而成。

语法
--

```js
new Blob(array)
new Blob(array, options)
```

### 参数

`array`

一个可迭代对象，比如 `Array`，包含 `ArrayBuffer`、`TypedArray`、`DataView`、`Blob`、字符串或者任意这些元素的混合，这些元素将会被放入 `Blob` 中。字符串应该是格式良好的 Unicode，而单独代理项（lone surrogate）会使用和 `String.prototype.toWellFormed()` 相同的算法进行清理。

`options` 可选

一个可以指定以下任意属性的对象：

`type` 可选

将会被存储到 blob 中的数据的 MIME 类型。默认值是空字符（`""`）。

`endings` 可选
非标准

如果数据是文本，那么如何解释其中的换行符（`\n`）。默认值 `transparent` 会将换行符复制到 blob 中而不会改变它们。要将换行符转换为主机系统的本地约定，请指定值 `native`。

### 返回值

一个包含指定数据的新的 `Blob` 对象。

示例
--

```js
const array = ['<q id="a"><span id="b">hey!</span></q>']; // 一个包含单个字符串的数组
const blob = new Blob(array, { type: "text/html" }); // 得到 blob
```

规范
--

| Specification |
| --- |
| File API # constructorBlob |

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

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


Blob：arrayBuffer() 方法 - Web API 接口参考

Blob：arrayBuffer() 方法
=====================

`Blob` 接口的 **`arrayBuffer()`** 方法返回一个 `Promise`，其会兑现一个包含 blob 二进制数据内容的 `ArrayBuffer`。

语法
--

```js
arrayBuffer()
```

### 参数

无。

### 返回值

一个 promise，会兑现为一个包含 blob 数据（以二进制形式）的 `ArrayBuffer`。

### 异常

该方法不会抛出异常，但可能会拒绝返回的 promise。这是可能发生的，例如在用于获取 blob 数据的 reader 抛出异常时。在获取数据时抛出的任何异常都会导致 promise 被拒绝。

使用说明
----

`FileReader.readAsArrayBuffer()` 方法与之类似，但 `arrayBuffer()` 返回一个 promise 对象，而不是像 `FileReader` 接口的方法一样返回一个基于事件的 API。

规范
--

| Specification |
| --- |
| File API # dom-blob-arraybuffer |

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

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

参见
--

* `Response.arrayBuffer()`
* Streams API
* `FileReader.readAsArrayBuffer()`


Blob.size - Web API 接口参考

Blob.size
=========

`Blob` 接口的 **`size`** 属性返回 `Blob` 或 `File` 的字节数。

值
-

`Blob`（或基于 `Blob` 的对象，例如 `File`）所包含数据的字节数。

示例
--

该实例使用 `file` 类型的 `<input>` 元素向用户请求一组文件，然后遍历这些文件，输出它们的名称和大小（以字节为单位）。

### HTML

```html
<input type="file" id="input" multiple />
<output id="output">Choose files…</output>
```

```
output {
  display: block;
  margin-top: 16px;
}
```

### JavaScript

```js
const input = document.getElementById("input");
const output = document.getElementById("output");

input.addEventListener("change", (event) => {
  output.innerText = "";

  for (const file of event.target.files) {
    output.innerText += `${file.name} has a size of ${file.size} bytes.\n`;
  }
});
```

规范
--

| Specification |
| --- |
| File API # dfn-size |

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

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

参见
--

* `Blob`
* 在 web 应用程序中使用文件


Blob：text() 方法 - Web API 接口参考

Blob：text() 方法
==============

`Blob` 接口的 **`text()`** 方法返回一个 `Promise`，其会兑现一个包含 blob 内容的 UTF-8 格式的字符串。

语法
--

```js
text()
```

### 参数

无。

### 返回值

一个 promise，其会兑现一个包含作为文字字符串的 blob 数据的字符串。数据*总是*被假定为 UTF-8 格式。

使用说明
----

`FileReader` 的 `readAsText()` 方法是一个与之类似的更老的方法，它对 `Blob` 和 `File` 对象都适用。下面是两个主要的不同之处：

* `Blob.text()` 返回一个 promise 对象，而 `FileReader.readAsText()` 是一个基于事件的 API。
* `Blob.text()` 总是使用 UTF-8 进行编码，而 `FileReader.readAsText()` 可以使用不同编码方式，取决于 blob 的类型和一个指定的编码名称。
规范
--

| Specification |
| --- |
| File API # dom-blob-text |

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

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

参见
--

* `Response.text()`
* Streams API
* `FileReader.readAsText()`


CanvasGradient.addColorStop() - Web API 接口参考

CanvasGradient.addColorStop()
=============================

**`CanvasGradient.addColorStop()`** 方法添加一个由**偏移值**和**颜色值**指定的断点到渐变。如果偏移值不在`0`到`1`之间，将抛出`INDEX_SIZE_ERR`错误，如果颜色值不能被解析为有效的 CSS 颜色值 `<color>`，将抛出`SYNTAX_ERR`错误。

语法
--

```js
void gradient.addColorStop(offset, color);
```

### 参数

offset

`0`到`1`之间的值，超出范围将抛出`INDEX_SIZE_ERR`错误

color

CSS 颜色值 `<color>`。如果颜色值不能被解析为有效的 CSS 颜色值 `<color>`，将抛出`SYNTAX_ERR`错误。

示例
--

### 使用 `addColorStop` 方法

一个使用`CanvasGradient`对象的`addColorStop` 方法的简单例子

#### HTML

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

#### JavaScript

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

var gradient = ctx.createLinearGradient(0, 0, 200, 0);
gradient.addColorStop(0, "green");
gradient.addColorStop(1, "white");
ctx.fillStyle = gradient;
ctx.fillRect(10, 10, 200, 100);
```

编辑以下代码可看到画布变化：
```

<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas>
<div class="playable-buttons">
  <input id="edit" type="button" value="Edit" />
  <input id="reset" type="button" value="Reset" />
</div>
<textarea id="code" class="playable-code">
var gradient = ctx.createLinearGradient(0,0,200,0);
gradient.addColorStop(0,"green");
gradient.addColorStop(1,"white");
ctx.fillStyle = gradient;
ctx.fillRect(10,10,200,100);</textarea
>
```

```
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
var textarea = document.getElementById("code");
var reset = document.getElementById("reset");
var edit = document.getElementById("edit");
var code = textarea.value;

function drawCanvas() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  eval(textarea.value);
}

reset.addEventListener("click", function () {
  textarea.value = code;
  drawCanvas();
});

edit.addEventListener("click", function () {
  textarea.focus();
});

textarea.addEventListener("input", drawCanvas);
window.addEventListener("load", drawCanvas);
```

标准
--

| Specification |
| --- |
| HTML Standard # dom-canvasgradient-addcolorstop-dev |

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

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

参见
--

* 接口定义 `CanvasGradient`
* `CanvasRenderingContext2D.createLinearGradient()`
* `CanvasRenderingContext2D.createRadialGradient()`


console：groupCollapsed() 静态方法 - Web API 接口参考

console：groupCollapsed() 静态方法
=============================

**`console.groupCollapsed()`** 方法在 Web 控制台上创建一个新的分组。与 `console.group()` 方法的不同点是，新建的分组默认是折叠的。用户必须点击一个按钮才能将折叠的内容打开。

调用 `console.groupEnd()` 以回到父级分组。

参见 `console` 文档中的在控制台中使用分组以获取详情和示例。

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

语法
--

```js
groupCollapsed()
groupCollapsed(label)
```

### 参数

`label`

分组的标签，为可选值。

### 返回值

无（`undefined`）。

规范
--

| Specification |
| --- |
| Console Standard # groupcollapsed |

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

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


console：profile() 静态方法 - Web API 接口参考

console：profile() 静态方法
======================

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

开始记录性能描述信息 (例如， Firefox performance tool)。

你可以选择提供一个参数来命名描述信息，这将允许你在有多个描述信息被记录时来选择只停止那个描述信息（被你命名的那个）。请查阅`Console.profileEnd()`来确认这个参数是如何被解释的。

要停止记录，请调用`Console.profileEnd()`。

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

语法
--

```js
profile(profileName)
```

参数
--

`profileName`

描述信息的名字。可选。

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

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

参见
--

* `Console.profileEnd()`


console：warn() 静态方法 - Web API 接口参考

console：warn() 静态方法
===================

向 Web 控制台输出一条警告信息。

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

**备注：** 在火狐浏览器里，警告会有一个小感叹号图标在 Web 控制台信息前面。

语法
--

```js
warn(obj1)
warn(obj1, /\* …, \*/ objN)
warn(msg)
warn(msg, subst1, /\* …, \*/ substN)
```

参数
--

`obj1` ... `objN`

要输出的 Javascript 对象列表。其中每个对象会以字符串的形式按照顺序依次输出到控制台。

`msg`

一个 JavaScript 字符串，其中包含零个或多个替代字符串。

`subst1` ... `substN`

零个或多个 Javascript 对象 依次替换 msg 中的替代字符串，你可以在替代字符串中指定对象的输出格式。

查看向控制台输出文本来了解更多 `console` 的用法。

规范
--

| Specification |
| --- |
| Console Standard # warn |

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

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

参见
--

* Opera Dragonfly 文档：控制台
* MSDN：使用 F12 工具控制台来查看错误和状态


console：info() 静态方法 - Web API 接口参考

console：info() 静态方法
===================

向 web 控制台输出一个通知信息。仅在 Firefox，web 控制台的日志中的项目旁边会显示一个小的‘I‘图标

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

语法
--

```js
info(obj1)
info(obj1, /\* …, \*/ objN)
info(msg)
info(msg, subst1, /\* …, \*/ substN)
```

参数
--

`obj1` ... `objN`

要输出的 JavaScript 对象列表。对象 obj1,obj2,...列出顺序和输出顺序一致。

`msg`

JavaScript 字符串。可包含零个或多个替换字符串。

`subst1` ... `substN`

用于替换 msg 内的替换字符串的 JavaScript 对象。可以对输出的格式进行额外的控制。

查看更多细节可访问 `console` 文件内的Outputting text to the console

规范
--

| Specification |
| --- |
| Console Standard # info |

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

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

参见
--

* Opera Dragonfly documentation: Console
* MSDN: Using the F12 Tools Console to View Errors and Status


console：timeLog() 静态方法 - Web API 接口参考

console：timeLog() 静态方法
======================

在控制台输出计时器的值，该计时器必须已经通过 `console.time()` 启动。

参阅文档中的 Timers 部分获取详细说明和示例。

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

语法
--

```js
timeLog()
timeLog(label)
timeLog(label, val1)
timeLog(label, val1, /\* …, \*/ valN)
```

### 参数

`label`

计时器索引。

### 返回值

如果没有传入 label 参数，则以 default: 作为引导返回数据：
```

default: 1042ms
```

如果传入了一个已经存在的 `label` ，则会以 `label:` 作为引导返回数据：
```

label: 1242ms
```

### 异常

如果计时器未启动， `timeLog()` 会返回一个警告：
```

Timer "default" doesn't exist.
```

如果传入的 label 索引没有与之对应的计时器，则返回如下警告：
```

Timer "timer name" doesn't exist.
```

示例
--

```js
console.time("answer time");
alert("Click to continue");
console.timeLog("answer time");
alert("Do a bunch of other stuff...");
console.timeEnd("answer time");
```

上例中的输出分别显示了用户从打开页面到关闭第一个 alert 和第二个 alert 框的时间间隔：

![Timer output in Firefox console](/zh-CN/docs/Web/API/console/timelog_static/timer_output.png)

注意：使用 `timelog()` 输出计时器的值会显示计时器名称。使用 `timeEnd()` 停止也会显示计时器名称和输出计时器的值，并且，最后的 " - timer ended" 可以清楚的显示计时器不再计时的信息。

规范
--

| Specification |
| --- |
| Console Standard # timelog |

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

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

参见
--

* Opera Dragonfly documentation: Console


console：time() 静态方法 - Web API 接口参考

console：time() 静态方法
===================

你可以启动一个计时器来跟踪某一个操作的占用时长。每一个计时器必须拥有唯一的名字，页面中最多能同时运行 10,000 个计时器。当以此计时器名字为参数调用 `console.timeEnd()` 时，浏览器将以毫秒为单位，输出对应计时器所经过的时间。

关于 Timers 的细节和例子请参考文档 `console` 。

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

语法
--

```js
time()
time(label)
```

参数
--

`label`

新计时器的名字。用来标记这个计时器，作为参数调用 `console.timeEnd()` 可以停止计时并将经过的时间在终端中打印出来。

规范
--

| Specification |
| --- |
| Console Standard # time |

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

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

参阅
--

* `Console.timeEnd()`
* `Console.timeLog()`
* Opera Dragonfly documentation: Console


console：countReset() 静态方法 - Web API 接口参考

console：countReset() 静态方法
=========================

重置计数器。此函数有一个可选参数 `label`。

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

如果提供了参数`label`，此函数会重置与 label 关联的计数。

如果省略了参数`label`，此函数会重置默认的计数器。

语法
--

```js
countReset()
countReset(label)
```

### 参数

`label`

 一个字符串，若传入此参数 `countReset()` 重置此 label 的 count 为 0。
 若忽略此参数 `countReset()` 重置 `count()` 默认的 default 字段的 count 为 0

### 返回值

若传入 label 参数：
```

 counter-name: 0
```

若不传入 label 参数：
```

default: 0
```

### 异常情况

若传入一个不存在的 `label`，`countReset` 返回下面的警告信息：
```

Counter "counter-name" doesn’t exist.
```

若 `label` 没有被传入 并且 `count()` 也没有被调用过，`countReset` 返回下面的警告信息：
```

Counter "default" doesn’t exist.
```

示例
--

下面给出示例代码：

```js
var user = "";

function greet() {
  console.count();
  return "hi " + user;
}

user = "bob";
greet();
user = "alice";
greet();
greet();
console.count();
console.countReset();
```

控制台打印输出结果：
```

"default: 1"
"default: 2"
"default: 3"
"default: 1"
"default: 0"
```

Note that the call to console.counterReset() resets the value of the default counter to zero.

可以看到 调用 `console.counterReset()` 重置了`default` 的计数为 0

如果我们把 `user` 变量做为 `label` 传入第一次调用的 `count()` 把字符串 `'alice'` 作为第二次调用 `count()` 的参数

```js
var user = "";

function greet() {
  console.count(user);
  return "hi " + user;
}

user = "bob";
greet();
user = "alice";
greet();
greet();
console.countReset("bob");
console.count("alice");
```

我们看到的输出如下：
```

"bob: 1"
"alice: 1"
"alice: 2"
"bob: 0"
"alice: 3"
```

调用 countReset("bod") 只是重置了 "bob" 的计数器值 而 "alice" 的计数器值没有改变。

规范
--

| Specification |
| --- |
| Console Standard # countreset |

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

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


console：groupEnd() 静态方法 - Web API 接口参考

console：groupEnd() 静态方法
=======================

在 Web 控制台中退出一格缩进 (结束分组). 请参阅 `console` 中的Using groups in the console 来获取它的用法和示例。

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

语法
--

```js
groupEnd()
```

参数
--

无。

规范
--

| Specification |
| --- |
| Console Standard # groupend |

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

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

参见
--

* Opera Dragonfly documentation: Console


console：profileEnd() 静态方法 - Web API 接口参考

console：profileEnd() 静态方法
=========================

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

**警告：** 在 console.profile() 之后立刻调用此 API 可能会导致其无法工作。为解决此问题，请在 setTimeOut 中至少延迟 5 毫秒后再调用。请看 bug #1173588。

profileEnd 方法会停止记录之前已经由`console.profile()`开始记录的性能描述信息

你可以选择提供一个参数来命名需要记录的描述信息。这使得你在记录多个描述信息的时候可以停止记录特定的描述信息。

* 如果 `console.profileEnd()` 传了描述信息名字，并且它与正在记录的描述信息的名字相匹配，则此描述信息将会停止。
* 如果 `console.profileEnd()` 传了描述信息名字，并且它与正在记录的描述信息的名字不匹配，则不会进行更改。
* 如果 `console.profileEnd()` 没有传描述信息名字，最近启动记录的描述信息将会停止。

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

语法
--

```js
profileEnd(profileName)
```

参数
--

`profileName`

描述信息的名字。可选。

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

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

参见
--

* `Console.profile()`


console：timeStamp() 静态方法 - Web API 接口参考

console：timeStamp() 静态方法
========================

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

向浏览器的 Performance 或者 Waterfall 工具添加一个标记。这样可以让你将代码中的一个点和其他在时间轴上已记录的事件相关联，例如布局事件和绘制事件等。

你可以选择用一个参数来作为时间戳标签，然后标记旁边就会显示这个标签。

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

语法
--

```js
timeStamp(label)
```

参数
--

`label`

Label for the timestamp. Optional.

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

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

参见
--

* `console.time()`
* `console.timeEnd()`
* Adding timestamps to the Waterfall


console：timeEnd() 静态方法 - Web API 接口参考

console：timeEnd() 静态方法
======================

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

概述
--

停止一个通过 `console.time()` 启动的计时器

**备注：** 该方法在使用时不会将输出的时间返回到 js，它只能用于控制台调试。请勿将该方法作为普通计时器或性能数据收集器的一部分。

有关详细信息和示例，请参阅 Timers

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

语法
--

```js
timeEnd()
timeEnd(label)
```

### 参数

`label`

需要停止的计时器名字。一旦停止，计时器所经过的时间会被自动输出到控制台。

规范
--

| Specification |
| --- |
| Console Standard # timeend |

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

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

参见
--

* Opera Dragonfly documentation: Console


console：log() 静态方法 - Web API 接口参考

console：log() 静态方法
==================

**`console.log()`** 方法向 Web 控制台输出一条信息。这条信息可能是单个字符串（包括可选的替代字符串），也可能是一个或多个对象。

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

语法
--

```js
log(obj1)
log(obj1, /\* …, \*/ objN)
log(msg)
log(msg, subst1, /\* …, \*/ substN)
```

参数
--

`obj1` ... `objN`

一个用于输出的 JavaScript 对象列表。其中每个对象会以字符串的形式按照顺序依次输出到控制台。请注意，如果你在最新版本的 Chrome 和 Firefox 中输出对象，你在控制台中得到的是*对该对象的引用*，这不一定是你调用 `console.log()` 时该对象的“值”，但它一定是该对象在你打开控制台时的值。

`msg`

一个 JavaScript 字符串，其中包含零个或多个替代字符串。

`subst1` ... `substN`

JavaScript 对象，用来依次替换 `msg` 中的替代字符串。你可以在替代字符串中指定对象的输出格式。

查看输出文本到控制台来了解更多 `console` 对象的用法。

返回值
---

无（`undefined`）。

输出对象
----

不要使用 `console.log(obj)`，而应该使用 `console.log(JSON.parse(JSON.stringify(obj)))`。

这样可以确保你所看到的 `obj` 的值是当前输出的值。否则，大多数浏览器会提供一个随着值的变化而不断更新的实时视图。这可能不是你想要的。

规范
--

| Specification |
| --- |
| Console Standard # log |

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

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

参见
--

* MSDN: Using the F12 Tools Console to View Errors and Status
* NodeJS: Console API


console：table() 静态方法 - Web API 接口参考

console：table() 静态方法
====================

将数据以表格的形式显示。

这个方法需要一个必须参数 `data`，`data` 必须是一个数组或者是一个对象；还可以使用一个可选参数 `columns`。

它会把数据 `data` 以表格的形式打印出来。数组中的每一个元素（或对象中可枚举的属性）将会以行的形式显示在表格中。

表格的第一列是 `index`。如果数据 `data` 是一个数组，那么这一列的单元格的值就是数组的索引。如果数据是一个对象，那么它们的值就是各对象的属性名称。注意（在 FireFox 中）`console.table` 被限制为只显示 1000 行（第一行是被标记的索引（原文：labeled index））。

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

### 打印单一参数类型

数据的参数类型可以是数组或是对象。

```js
// 打印一个由字符串组成的数组

console.table(["apples", "oranges", "bananas"]);
```

![](/zh-CN/docs/Web/API/console/table_static/console-table-array.png)

```js
// 打印一个属性值是字符串的对象

function Person(firstName, lastName) {
  this.firstName = firstName;
  this.lastName = lastName;
}

var me = new Person("John", "Smith");

console.table(me);
```

![](/zh-CN/docs/Web/API/console/table_static/console-table-simple-object.png)

### 打印复合的参数类型

如果需要打印的元素在一个数组中，或者需要打印的属性在一个对象，并且他们本身就是一个数组或者对象，则将会把这个元素显示在同一行，每个元素占一列：

```js
// 二元数组的打印

var people = [
  ["John", "Smith"],
  ["Jane", "Doe"],
  ["Emily", "Jones"],
];
console.table(people);
```

![Table displaying array of arrays](/zh-CN/docs/Web/API/console/table_static/console-table-array-of-array.png)

```js
// 打印一个包含对象的数组

function Person(firstName, lastName) {
  this.firstName = firstName;
  this.lastName = lastName;
}

var john = new Person("John", "Smith");
var jane = new Person("Jane", "Doe");
var emily = new Person("Emily", "Jones");

console.table([john, jane, emily]);
```

请注意，如果数组包含对象，则列将使用属性名称进行标记。

结果显示，如果数组中包含该对象，打印出来的列标签将是该对象的属性名

![Table displaying array of objects](/zh-CN/docs/Web/API/console/table_static/console-table-array-of-objects.png)

```js
// 打印属性名是对象的对象

var family = {};

family.mother = new Person("Jane", "Smith");
family.father = new Person("John", "Smith");
family.daughter = new Person("Emily", "Smith");

console.table(family);
```

![Table displaying object of objects](/zh-CN/docs/Web/API/console/table_static/console-table-object-of-objects.png)

### 选择要隐藏的列

`console.table()` 会把所有元素罗列在每一列，你可以使用 `columns` 参数选择要显示的列的子集：

```js
// 一个对象数组，只打印 firstName

function Person(firstName, lastName) {
  this.firstName = firstName;
  this.lastName = lastName;
}

var john = new Person("John", "Smith");
var jane = new Person("Jane", "Doe");
var emily = new Person("Emily", "Jones");

console.table([john, jane, emily], ["firstName"]);
```

![Table displaying array of objects with filtered output](/zh-CN/docs/Web/API/console/table_static/console-table-array-of-objects-firstname-only.png)

### 按列重新排序

你可以点击每列的顶部标签来重排输出的表格。

语法
--
```

console.table(data [, columns]);
```

### 参数

`data`

要显示的数据。必须是数组或对象。

`columns`

一个包含列的名称的数组。

规范
--

| Specification |
| --- |
| Console Standard # table |

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

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


console：error() 静态方法 - Web API 接口参考

console：error() 静态方法
====================

向 Web 控制台输出一条错误消息。

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

语法
--
```

console.error(obj1 [, obj2, ..., objN]);
console.error(msg [, subst1, ..., substN]);
console.exception(obj1 [, obj2, ..., objN]);
console.exception(msg [, subst1, ..., substN]);
```

**备注：** `console.exception()` 是 `console.error()` 的别名；它们功能相同。

### 参数

`obj1` ... `objN`

要输出的 JavaScript 对象列表。这些对象的字符串形式按顺序加起来然后输出。

`msg`

一个字符串，它包含零个或多个替代字符串。

`subst1` ... `substN`

JavaScript 对象可以用此来替换`msg`里的替代字符串。你可以控制输出的格式。

详情请看`console`文档中的 输出文本到控制台 。

规范
--

| Specification |
| --- |
| Console Standard # error |

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

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

参见
--

* Opera Dragonfly documentation: Console
* MSDN: Using the F12 Tools Console to View Errors and Status
* Chrome Developer Tools: Using the Console


console：assert() 静态方法 - Web API 接口参考

console：assert() 静态方法
=====================

如果断言为 false，则将一个错误消息写入控制台。如果断言是 `true`，没有任何反应。

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

`console.assert()` 方法在 Node.js 中的实现和浏览器中可用的 `console.assert()` 方法实现是不同的。在浏览器中当 `console.assert()` 方法接受到一个值为假断言的时候，会向控制台输出传入的内容，但是并不会中断代码的执行，而在 Node.js v10.0.0 之前，一个值为假的断言也将会导致一个 `AssertionError` 被抛出，使得代码执行被打断。v10.0.0 修复了此差异，所以现在 `console.assert()` 在 Node 和浏览器中执行行为相同。

语法
--

```js
console.assert(assertion, obj1 [, obj2, ..., objN]);
console.assert(assertion, msg [, subst1, ..., substN]); // c-like message formatting
```

### 参数

`assertion`

一个布尔表达式。如果 assertion 为假，消息将会被输出到控制台之中。

`obj1` ... `objN`

被用来输出的 Javascript 对象列表，最后输出的字符串是各个对象依次拼接的结果。

`msg`

一个包含零个或多个子串的 Javascript 字符串。

`subst1` ... `substN`

各个消息作为字串的 Javascript 对象。这个参数可以让你能够控制输出的格式。

案例
--

下面的代码示例演示了 JavaScript 对象的使用：

```js
const errorMsg = "the # is not even";
for (let number = 2; number <= 5; number += 1) {
  console.log("the # is " + number);
  console.assert(number % 2 === 0, { number: number, errorMsg: errorMsg });
  // 或者使用 ES2015 对象简写：
  // console.assert(number % 2 === 0, {number, errorMsg});
}
// 输出：
// the # is 2
// the # is 3
// Assertion failed: {number: 3, errorMsg: "the # is not even"}
// the # is 4
// the # is 5
// Assertion failed: {number: 5, errorMsg: "the # is not even"}
```

请注意，你可以在大多数浏览器中使用 console.log 进行格式化输出

```js
console.log("the word is %s try number %d", "foo", 123);
// 输出：the word is foo try number 123
```

但是 `console.assert` 在不同浏览器中可能获得不同的效果：

```js
console.assert(false, "the word is %s", "foo");
// correct output in Node (e.g. v8.10.0) and some browsers
// (e.g. Firefox v60.0.2):
// Assertion failed: the word is foo
// incorrect output in some browsers
// (e.g. Chrome v67.0.3396.87):
// Assertion failed: the word is %s foo
```

有关详细信息，请参阅 `console` 文档中的 输出文本到控制台。

规范
--

| Specification |
| --- |
| Console Standard # assert |

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

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

参见
--

* WHATWG Console Standard: console.assert
* Opera Dragonfly documentation: Console
* MSDN: Using the F12 Tools Console to View Errors and Status
* Chrome Developer Tools: Using the Console


console：dir() 静态方法 - Web API 接口参考

console：dir() 静态方法
==================

**`console.dir()`** 方法可以显示指定 JavaScript 对象的属性列表，并以交互式的形式展现。输出结果呈现为分层列表，包含展开/折叠的三角形图标，可用于查看子对象的内容。

换句话说，`console.dir()` 是一种在控制台中查看指定 JavaScript 对象的所有属性的方法，开发人员可以通过这种方式轻松获取对象的属性。

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

![console-dir.png](/zh-CN/docs/Web/API/console/dir_static/console-dir.png)

语法
--

```js
dir(object);
```

参数
--

`object`

应输出其属性的 JavaScript 对象。

### 返回值

无（`undefined`）。

规范
--

| Specification |
| --- |
| Console Standard # dir |

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

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

参见
--

* MSDN：使用 F12 工具控制台查看错误和状态
* Chrome 控制台 API 参考


console：group() 静态方法 - Web API 接口参考

console：group() 静态方法
====================

**`console.group()`** 方法在 Web 控制台上创建一个新的分组。随后输出到控制台上的内容都会被添加一个缩进，表示该内容属于当前分组，直到调用 `console.groupEnd()` 之后，当前分组结束。

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

语法
--

```js
group()
group(label)
```

### 参数

`label`

分组标签。

### 返回值

无（`undefined`）。

规范
--

| Specification |
| --- |
| Console Standard # group |

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

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

参见
--

* `console.groupEnd()`


console：debug() 静态方法 - Web API 接口参考

console：debug() 静态方法
====================

**`console.debug()`** 方法将一条消息输出到 web 控制台，消息的日志级别为“debug”。只有在控制台配置为显示调试输出时，才会向用户显示该消息。在大多数情况下，日志级别在控制台 UI 中进行配置。该日志级别可能对应于 **`Debug`** 或 **`Verbose`** 日志级别。

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

语法
--

```js
debug(obj1)
debug(obj1, /\* …, \*/ objN)
debug(msg)
debug(msg, subst1, /\* …, \*/ substN)
```

### 参数

`obj1` … `objN`

要输出的 JavaScript 对象列表。按传参的顺序把对象输出到控制台。

`msg`

包含零个或多个替换字符串的 JavaScript 字符串，这些替换字符串会按照连续的顺序用 `subst1` 到 `substN` 进行替换。

`subst1` … `substN`

JavaScript 对象，用来依次替换 `msg` 中的替代字符串。你可以在替代字符串中指定对象的输出格式。查看使用字符串替换了解替换字符串如何工作。

有关详细信息，请参阅 `console` 对象文档中的输出文本到控制台。

### 返回值

无 (`undefined`)。

规范
--

| Specification |
| --- |
| Console Standard # debug |

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

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


console：trace() 静态方法 - Web API 接口参考

console：trace() 静态方法
====================

`console` 的 **`trace()`** 方法向 Web 控制台输出一个堆栈跟踪。

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

在页面 `console` 文档中查看堆栈跟踪的详细介绍和示例。

语法
--

```js
trace()
trace(object1, /\* …, \*/ objectN)
```

### 参数

`...any, ...data` 可选

Zero or more objects to be output to console along with the trace. These are assembled and formatted the same way they would be if passed to the `console.log()` method.

Example
-------
```

function foo() {
  function bar() {
    console.trace();
  }
  bar();
}

foo();
```

In the console, the following trace will be displayed:
```

bar
foo
<anonymous>
```

规范
--

| Specification |
| --- |
| Console Standard # trace |

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

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

参见
--

* Opera Dragonfly documentation: Console


console：dirxml() 静态方法 - Web API 接口参考

console：dirxml() 静态方法
=====================

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

显示一个明确的 XML/HTML 元素的包括所有后代元素的交互树。如果无法作为一个 element 被显示，那么会以 JavaScript 对象的形式作为替代。它的输出是一个继承的扩展的节点列表，可以让你看到子节点的内容。

语法
--
```

console.dirxml(object);
```

参数
--

`object`

一个属性将被输出的 JavaScript 对象。

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

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

参见
--

* Opera Dragonfly documentation: Console


console：count() 静态方法 - Web API 接口参考

console：count() 静态方法
====================

**`console.count()`** 方法会记录调用 `count()` 的次数。

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

语法
--

```js
count()
count(label)
```

### 参数

`label` 可选

一个字符串。如果给定，`count()` 会输出带有该标签的调用次数。如果未提供，调用 `count()` 的行为就像是带有“default”标签一样。

### 返回值

无（`undefined`）。

示例
--

例如，给定这样的代码：

```js
let user = "";

function greet() {
  console.count();
  return `hi ${user}`;
}

user = "bob";
greet();
user = "alice";
greet();
greet();
console.count();
```

控制台输出看起来像这样：
```

"default: 1"
"default: 2"
"default: 3"
"default: 4"
```

标签显示为 `default`，因为没有提供明确的标签。

如果我们将 `user` 变量作为第一次调用 `count()` 函数时的 `label` 参数传入，并将字符串”alice“作为第二次调用的参数：

```js
let user = "";

function greet() {
  console.count(user);
  return `hi ${user}`;
}

user = "bob";
greet();
user = "alice";
greet();
greet();
console.count("alice");
```

我们会看到如下的输出：
```

"bob: 1"
"alice: 1"
"alice: 2"
"alice: 3"
```

我们现在仅根据 `label` 的值维护单独的计数。

规范
--

| Specification |
| --- |
| Console Standard # count |

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

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


console：clear() 静态方法 - Web API 接口参考

console：clear() 静态方法
====================

**`console.clear()`** 方法会清空控制台，但前提是该控制台允许清空。像浏览器运行的图形控制台就允许清空，而像 Node 运行的终端上显示的控制台则不支持它，调用该方法将不会产生任何效果（也不会报错）。

语法
--

```js
clear();
```

### 参数

无

### 返回值

无（`undefined`）。

规范
--

| Specification |
| --- |
| Console Standard # clear |

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

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


WebSocket: message event - Web API 接口参考

WebSocket: message event
========================

`message` 事件会在 `WebSocket` 接收到新消息时被触发。

| 起泡（Bubbles） | 不 |
| --- | --- |
| 可取消 | 不 |
| 接口 | `MessageEvent` |
| 事件处理程序属性 | `onmessage` |

例子
--

```js
// 创建一个 WebSocket 连接
const socket = new WebSocket("ws://localhost:8080");

// 监听消息
socket.addEventListener("message", function (event) {
  console.log("Message from server ", event.data);
});
```

规范
--

| Specification |
| --- |
| WebSockets Standard # dom-websocket-onmessage |

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

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

另看
--

* WebSocket: close event
* WebSocket: error event
* WebSocket: open event
* Writing WebSocket client applications (en-US)


WebSocket.onclose - Web API 接口参考

WebSocket.onclose
=================

**`WebSocket.onclose`** 属性返回一个事件监听器，这个事件监听器将在 WebSocket 连接的`readyState` 变为 `CLOSED`时被调用，它接收一个名字为“close”的 `CloseEvent` 事件。

语法
--
```

WebSocket.onclose = function(event) {
  console.log("WebSocket is closed now.");
};
```

值
-

一个`EventListener`.

规范
--

| Specification |
| --- |
| WebSockets Standard # dom-websocket-onclose |


WebSocket.readyState - Web API 接口参考

WebSocket.readyState
====================

概要
--

返回当前 `WebSocket` 的链接状态，只读。

语法
--
```

var readyState = WebSocket.readyState;
```

值
-

以下其中之一

0 (`WebSocket.CONNECTING`)

正在链接中

1 (`WebSocket.OPEN`)

已经链接并且可以通讯

2 (`WebSocket.CLOSING`)

连接正在关闭

3 (`WebSocket.CLOSED`)

连接已关闭或者没有链接成功

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

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-readystate① |

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

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


WebSocket.bufferedAmount - Web API 接口参考

WebSocket.bufferedAmount
========================

**`WebSocket.bufferedAmount`是一个只读属性，用于返回已经被**`send()`方法放入队列中但还没有被发送到网络中的数据的字节数。一旦队列中的所有数据被发送至网络，则该属性值将被重置为 0。但是，若在发送过程中连接被关闭，则属性值不会重置为 0。如果你不断地调用`send()`，则该属性值会持续增长

The **`WebSocket.bufferedAmount`** read-only property returns the number of bytes of data that have been queued using calls to `send()` but not yet transmitted to the network. This value resets to zero once all queued data has been sent. This value does not reset to zero when the connection is closed; if you keep calling `send()`, this will continue to climb.

Syntax
------
```

var bufferedAmount = aWebSocket.bufferedAmount;
```

Value
-----

An `unsigned long`.

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

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-bufferedamount① |

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

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


WebSocket.url - Web API 接口参考

WebSocket.url
=============

The **`WebSocket.url`** read-only property returns the absolute URL of the `WebSocket` as resolved by the constructor.

\*\*`WebSocket.url`\*\*是一个只读属性，返回值为当构造函数创建`WebSocket`实例对象时 URL 的绝对路径。

语法
--
```

var url = aWebSocket.url;
```

返回值
---

A `DOMString`.

规范
--

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-url① |

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

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


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

WebSocket.close()
=================

**`WebSocket.close()`** 方法关闭 `WebSocket` 连接或连接尝试（如果有的话）。如果连接已经关闭，则此方法不执行任何操作。

语法
--
```

WebSocket.close();
```

### 参数

`code` 可选

一个数字状态码，它解释了连接关闭的原因。如果没有传这个参数，默认使用 1005。`CloseEvent`的允许的状态码见状态码列表 。

`reason` 可选

一个人类可读的字符串，它解释了连接关闭的原因。这个 UTF-8 编码的字符串不能超过 123 个字节。

### 抛出的异常

`INVALID_ACCESS_ERR`

一个无效的`code`

`SYNTAX_ERR`

`reason` 字符串太长（超过 123 字节）

**备注：** 在 Gecko 8.0 之前版本的 Gecko 里，这个方法不支持传参数。

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

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-close① |

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

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


WebSocket.binaryType - Web API 接口参考

WebSocket.binaryType
====================

**`WebSocket.binaryType`** 返回 websocket 连接所传输二进制数据的类型。

语法
--
```

var binaryType = aWebSocket.binaryType;
```

返回值
---

一条`DOMString`:

`"blob"`

如果传输的是 `Blob` 类型的数据。

`"arraybuffer"`

如果传输的是 `ArrayBuffer` 类型的数据。

规范
--

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-binarytype① |

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

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


WebSocket.onopen - Web API 接口参考

WebSocket.onopen
================

\*\*`WebSocket.onopen`\*\*属性定义一个事件处理程序，当`WebSocket` 的连接状态`readyState` 变为`1`时调用;这意味着当前连接已经准备好发送和接受数据。这个事件处理程序通过 `事件`（建立连接时）触发。

语法
--
```

aWebSocket.onopen = function(event) {
  console.log("WebSocket is open now.");
};
```

返回值
---

An `EventListener`.

规范
--

| Specification |
| --- |
| WebSockets Standard # dom-websocket-onopen |

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

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


WebSocket.extensions - Web API 接口参考

WebSocket.extensions
====================

\*\*`WebSocket.extensions`\*\*是只读属性，返回服务器已选择的扩展值。目前，链接可以协定的扩展值只有空字符串或者一个扩展列表。

The **`WebSocket.extensions`** read-only property returns the extensions selected by the server. This is currently only the empty string or a list of extensions as negotiated by the connection.

语法
--
```

var extensions = aWebSocket.extensions;
```

返回值
---

A `DOMString`.

规范
--

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-extensions① |

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

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


WebSocket.protocol - Web API 接口参考

WebSocket.protocol
==================

**`WebSocket.protocol`** 是个只读属性，用于返回服务器端选中的子协议的名字；这是一个在创建 `WebSocket` 对象时，在参数 `protocols` 中指定的字符串，当没有已建立的链接时为空串。

语法
--
```

var protocol = aWebSocket.protocol;
```

返回值
---

`DOMString`.

规范
--

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-protocol① |

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

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


WebSocket.send() - Web API 接口参考

WebSocket.send()
================

**`WebSocket.send()`** 方法将需要通过 WebSocket 链接传输至服务器的数据排入队列，并根据所需要传输的 data bytes 的大小来增加 `bufferedAmount`的值。若数据无法传输（例如数据需要缓存而缓冲区已满）时，套接字会自行关闭。

语法
--
```

WebSocket.send("Hello server!");
```

### 参数

`data`

用于传输至服务器的数据。它必须是以下类型之一：

`USVString`

文本字符串。字符串将以 UTF-8 格式添加到缓冲区，并且 `bufferedAmount` 将加上该字符串以 UTF-8 格式编码时的字节数的值。

`ArrayBuffer`

你可以使用一有类型的数组对象发送底层二进制数据；其二进制数据内存将被缓存于缓冲区，`bufferedAmount` 将加上所需字节数的值。

`Blob`

`Blob` 类型将队列 blob 中的原始数据以二进制中传输。 `bufferedAmount` 将加上原始数据的字节数的值。

`ArrayBufferView`

你可以以二进制帧的形式发送任何 JavaScript 类数组对象 ；其二进制数据内容将被队列于缓冲区中。值 `bufferedAmount` 将加上必要字节数的值。

### 异常

`INVALID_STATE_ERR`

当前连接未处于 `OPEN` 状态。

`SYNTAX_ERR`

数据是一个包含未配对代理 (unpaired surrogates) 的字符串。

**备注：** Gecko 在 Gecko 6.0 中对 `send()` 方法的实现与规范有些不一致；Gecko 返回一个 `boolean` 来告知当前连接是否依旧处于 `OPEN` 状态（同时也可以使用该返回值来判定数据是否已经被完全缓存或者传输）；这个问题在 Gecko 8.0 中被修正。

而 Gecko 11.0, 支持 `ArrayBuffer` 类型但不支持 `Blob`类型。

规范
--

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-send① |

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

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


WebSocket: 错误事件 - Web API 接口参考

WebSocket: 错误事件
===============

当`websocket`的连接由于一些错误事件的发生 (例如无法发送一些数据) 而被关闭时，一个`error`事件将被引发。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `Event` |
| Event handler property | `onerror` |

示例
--

```js
// Create WebSocket connection
// 创建一个 WebSocket 连接
const socket = new WebSocket("ws://localhost:8080");

// Listen for possible errors
// 监听可能发生的错误
socket.addEventListener("error", function (event) {
  console.log("WebSocket error: ", event);
});
```

规范
--

| Specification |
| --- |
| WebSockets Standard # dom-websocket-onerror |

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

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

查看更多
----

* WebSocket: close event
* WebSocket: message event
* WebSocket: open event
* Writing WebSocket client applications (en-US)


WebSocket() - Web API 接口参考

WebSocket()
===========

 \*\*`WebSocket()`\*\*构造函器会返回一个 `WebSocket` 对象。
语法
--
```

var aWebSocket = new WebSocket(url [, protocols]);
```

### 参数

`url`

要连接的 URL；这应该是 WebSocket 服务器将响应的 URL。

`protocols` 可选

一个协议字符串或者一个包含协议字符串的数组。这些字符串用于指定子协议，这样单个服务器可以实现多个 WebSocket 子协议（例如，你可能希望一台服务器能够根据指定的协议（`protocol`）处理不同类型的交互）。如果不指定协议字符串，则假定为空字符串。

### 抛出异常

`SECURITY_ERR`

正在尝试连接的端口被阻止。

规范
--

| Specification |
| --- |
| WebSockets Standard # ref-for-dom-websocket-websocket① |

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

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


WheelEvent.deltaX - Web API 接口参考

WheelEvent.deltaX
=================

**`WheelEvent.deltaX`** 只读属性是一个 `double` 类型值，声明水平滚动量以`WheelEvent.deltaMode` 为单位。

语法
--
```

var dX = event.deltaX;
```

例子
--

```js
var syntheticEvent = new WheelEvent("syntheticWheel", {
  deltaX: 4,
  deltaMode: 0,
});

console.log(syntheticEvent.deltaX);
```

规范
--

| Specification |
| --- |
| UI Events # dom-wheelevent-deltax |

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

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

另见
--

* `wheel`
* `WheelEvent`


WheelEvent.deltaMode - Web API 接口参考

WheelEvent.deltaMode
====================

**`WheelEvent.deltaMode`** 只读属性返回一个 `unsigned long` 类型的值，声明 delta 的滚动值的单位。可能的值为：

| Constant | Value | Description |
| --- | --- | --- |
| `DOM_DELTA_PIXEL` | `0x00` | delta 的值为 像素 级别。 |
| `DOM_DELTA_LINE` | `0x01` | delta 的值为 行 级别。 |
| `DOM_DELTA_PAGE` | `0x02` | delta 的值为 页 级别。 |

语法
--
```

var unit = event.deltaMode;
```

例子
--

```js
var syntheticEvent = new WheelEvent("syntheticWheel", {
  deltaX: 4,
  deltaMode: 0,
});

console.log(syntheticEvent.deltaMode);
```

规范
--

| Specification |
| --- |
| UI Events # dom-wheelevent-deltamode |

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

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

另见
--

* `wheel`
* `WheelEvent`


WheelEvent.deltaY - Web API 接口参考

WheelEvent.deltaY
=================

**`WheelEvent.deltaY`** 只读属性是一个 `double` 类型值，声明垂直滚动量以 `WheelEvent.deltaMode` 为单位。

语法
--

```js
var dY = event.deltaY;
```

例子
--

```js
var syntheticEvent = new WheelEvent("syntheticWheel", {
  deltaY: 4,
  deltaMode: 0,
});

console.log(syntheticEvent.deltaY);
```

规范
--

| Specification |
| --- |
| UI Events # dom-wheelevent-deltay |

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

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

另见
--

* `wheel`
* `WheelEvent`


WheelEvent.deltaZ - Web API 接口参考

WheelEvent.deltaZ
=================

**`WheelEvent.deltaZ`** 只读属性是一个 `double` 类型值，声明 Z 轴滚动量以`WheelEvent.deltaMode` 为单位。

语法
--
```

var dZ = event.deltaZ;
```

例子
--

```js
var syntheticEvent = new WheelEvent("syntheticWheel", {
  deltaZ: 4,
  deltaMode: 0,
});

console.log(syntheticEvent.deltaZ);
```

规范
--

| Specification |
| --- |
| UI Events # dom-wheelevent-deltaz |

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

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

另见
--

* `wheel`
* `WheelEvent`


Node.nodeValue - Web API 接口参考

Node.nodeValue
==============

`Node` 的 **`nodeValue`** 属性返回或设置当前节点的值。

语法
--
```

str = node.nodeValue;
node.nodeValue = str;
```

value 是一个包含当前节点的值的字符串（如果有的话）。

### 值

对于文档节点来说，`nodeValue`返回`null`. 对于 text, comment，和 CDATA 节点来说，`nodeValue 返回该节点的文本内容`. 对于 attribute 节点来说，返回该属性的属性值。

下表就是不同类型的节点所返回的该属性的值。

| Node | Value of nodeValue |
| --- | --- |
| `CDATASection` | CDATA 的文本内容 |
| `Comment` | 注释的文本内容 |
| `Document` | null |
| `DocumentFragment` | null |
| `DocumentType` | null |
| `Element` | null |
| `NamedNodeMap` | null |
| `EntityReference` | null |
| `Notation` | null |
| `ProcessingInstruction` (en-US) | 整个标签的文本内容 |
| `Text` (en-US) | 文本节点的内容 |

如果 `nodeValue` 的值为 `null`,则对它赋值也不会有任何效果。

规范
--

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

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

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


Node.parentNode - Web API 接口参考

Node.parentNode
===============

概述
--

返回指定的节点在 DOM 树中的父节点。

语法
--
```

parentNode = node.parentNode
```

`parentNode` 是指定节点的父节点。一个元素节点的父节点可能是一个元素（`Element`）节点，也可能是一个文档（`Document`）节点，或者是个文档碎片（`DocumentFragment`）节点。

例子
--
```

if (node.parentNode) {
  // 从 DOM 树中删除 node 节点，除非它已经被删除了。
  node.parentNode.removeChild(node);
}
```

备注
--

对于下面的节点类型: `Attr`, `Document`, `DocumentFragment`, `Entity`, `Notation`,其`parentNode`属性返回`null`.

如果当前节点刚刚被建立，还没有被插入到 DOM 树中，则该节点的 `parentNode` 属性也返回 `null`.

相关链接
----

`element.firstChild`, `element.lastChild`, `element.childNodes`, `element.nextSibling`, `element.previousSibling`.

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

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

规范
--

DOM Level 2 Core: Node.parentNode


Node.parentElement - Web API 接口参考

Node.parentElement
==================

返回当前节点的父元素节点，如果该元素没有父节点，或者父节点不是一个 DOM `元素`，则返回 `null`。

语法
--
```

parentElement = node.parentElement
```

`parentElement` 是当前节点的父元素。它永远是一个 DOM `元素` 对象，或者 `null`。

例子
--

```js
if (node.parentElement) {
  node.parentElement.style.color = "red";
}
```

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

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

在一些浏览器上，`parentElement` 属性只对自身为 `Element` 的节点定义，也就是说，对文本节点不定义。

规范
--

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

参见
--

* `Node.parentNode`


Node.childNodes - Web API 接口参考

Node.childNodes
===============

概述
--

**Node.childNodes** 返回包含指定节点的子节点的集合，该集合为即时更新的集合（live collection）。

语法
--
```

var ndList = elementNodeReference.childNodes;
```

ndList 变量为 `NodeList` 类型，且为只读。

例子
--
```

// parg 是一个对 <p> 元素的引用
if (parg.hasChildNodes())
// 首先我们检查它是否包含子节点
 {
   var children = parg.childNodes;
   for (var i = 0; i < children.length; i++)
   {
   // children[i] 就是遍历到的每个子节点。
   // 注意：该 NodeList 对象为 LIVE 类型的 NodeList，添加或删除子节点都会实时的改变整个 NodeList 对象。
   };
 };
```

```
//下面的方法可以删除节点 box 的所有子节点
while (box.firstChild)
 {
    //box 为 LIVE 类型的 NodeList，所以 firstChild 属性每次会指向不同的子节点
    box.removeChild(box.firstChild);
 };
```

备注
--

集合的元素是一个节点而不是字符串。要从集合的元素获取数据，你必须使用它们的属性（例如：用 `elementNodeReference.childNodes[1].nodeName` 获取它们的名称，等等）。

`document`节点 (文档节点) 包含两个子节点：Doctype 声明和根节点。根节点通常为 `documentElement` 引用，且在 (X)HTML 文档中为 HTML 元素。

规范
--

* W3C DOM 2 Core: childNodes
* W3C DOM 3 Core: childNodes
* W3C DOM 3 NodeList interface
相关链接
----

* `Node.firstChild`
* `Node.lastChild`
* `Node.nextSibling`
* `Node.previousSibling`
* `ParentNode.children` (en-US)


Node.cloneNode - Web API 接口参考

Node.cloneNode
==============

**`Node.cloneNode()`** 方法返回调用该方法的节点的一个副本。

语法
--
```

var dupNode = node.cloneNode(deep);
```

`node`

将要被克隆的节点

`dupNode`

克隆生成的副本节点

`deep` 可选

是否采用深度克隆，如果为 `true`，则该节点的所有后代节点也都会被克隆，如果为 `false`，则只克隆该节点本身。

**备注：** 在 DOM4 规范中 (实现于 Gecko 13.0)，`deep`是一个可选参数。如果省略的话，参数的默认值为 `true，`也就是说默认是深度克隆。如果想使用浅克隆，你需要将该参数设置为 `false`。

在最新的规范里，该方法的行为已经改变了，其默认值变成了 false。虽然该参数仍旧是可选的，但是你必须要为该方法设置 deep 参数，无论是为了向前还是向后兼容考虑。假如开发者没设置参数的话，Gecko 28.0) 版本的控制台会发出警告。从 Gecko 29.0) 开始该方法默认为浅复制而不是深度复制。

示例
--

```js
var p = document.getElementById("para1"),
var p_prime = p.cloneNode(true);
```

附注
--

克隆一个元素节点会拷贝它所有的属性以及属性值，当然也就包括了属性上绑定的事件 (比如`onclick="alert(1)"`),但不会拷贝那些使用`addEventListener()`方法或者`node.onclick = fn`这种用 JavaScript 动态绑定的事件。

在使用`Node.appendChild()`或其他类似的方法将拷贝的节点添加到文档中之前，那个拷贝节点并不属于当前文档树的一部分，也就是说，它没有父节点。

如果`deep`参数设为`false`,则不克隆它的任何子节点。该节点所包含的所有文本也不会被克隆，因为文本本身也是一个或多个的`Text` (en-US)节点。

如果 `deep` 参数设为 `true`,则会复制整棵 DOM 子树 (包括那些可能存在的`Text` (en-US)子节点).对于空结点 (例如`<img>`和`<input>`元素), 则 `deep` 参数无论设为 `true` 还是设为 `false`, 都没有关系，但是仍然需要为它指定一个值。

**警告：** 为了防止一个文档中出现两个 ID 重复的元素，使用`cloneNode()` 方法克隆的节点在需要时应该指定另外一个与原 ID 值不同的 ID

如果原始节点设置了 ID，并且克隆节点会被插入到相同的文档中，那么应该更新克隆节点的 ID 以保证唯一性。name 属性可能也需要进行修改，取决于你是否希望有相同名称的节点存在于文档中。

想要克隆一个节点来添加到另外一个文档中，请使用`Document.importNode()`代替本方法。

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

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

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

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


Node.lookupNamespaceURI - Web API 接口参考

Node.lookupNamespaceURI
=======================

返回当前节点上与指定命名空间前缀绑定的命名空间 URI，如果没有，返回`null，如果参数为 null`,返回默认的命名空间。

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

### 相关链接

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


Node.removeChild - Web API 接口参考

Node.removeChild
================

**Node.removeChild()** 方法从 DOM 中删除一个子节点。返回删除的节点。

语法
--
```

let oldChild = node.removeChild(child);

//OR

element.removeChild(child);
```

* `child` 是要移除的那个子节点。
* `node` 是`child`的父节点。
* oldChild 保存对删除的子节点的引用。`oldChild` === `child`.

被移除的这个子节点仍然存在于内存中，只是没有添加到当前文档的 DOM 树中，因此，你还可以把这个节点重新添加回文档中，当然，实现要用另外一个变量比如`上例中的 oldChild`来保存这个节点的引用。如果使用上述语法中的第二种方法，即没有使用 oldChild 来保存对这个节点的引用，则认为被移除的节点已经是无用的，在短时间内将会被内存管理回收。

如果上例中的`child 节点`不是`node`节点的子节点，则该方法会抛出异常。

示例
--
```

<!--Sample HTML code-->
<div id="top" align="center"> </div>

<script type="text/javascript">
      var top = document.getElementById("top");
      var nested = document.getElementById("nested");
      var garbage = top.removeChild(nested);
      //Test Case 2: the method throws the exception (2)
</script>

<!--Sample HTML code-->
<div id="top" align="center">
 <div id="nested"></div>
</div>

<script type="text/javascript">
      var top = document.getElementById("top");
      var nested = document.getElementById("nested");
      var garbage = top.removeChild(nested);
      // This first call remove correctly the node
      garbage = top.removeChild(nested);
      // Test Case 1: the method in the second call here, throws the exception (1)
</script>
```

```
<!--示例 HTML 代码-->

<div id="top" align="center">
  <div id="nested"></div>
</div>
```

```js
// 先定位父节点，然后删除其子节点
var d = document.getElementById("top");
var d_nested = document.getElementById("nested");
var throwawayNode = d.removeChild(d_nested);
```

```js
// 无须定位父节点，通过 parentNode 属性直接删除自身
var node = document.getElementById("nested");
if (node.parentNode) {
  node.parentNode.removeChild(node);
}
```

```js
// 移除一个元素节点的所有子节点
var element = document.getElementById("top");
while (element.firstChild) {
  element.removeChild(element.firstChild);
}
```

规范
--

* DOM Level 1 Core: removeChild
* DOM Level 2 Core: removeChild
* DOM Level 3 Core: removeChild
相关链接
----

* `Node.replaceChild`
* `Node.parentNode`
* `ChildNode.remove` (en-US)


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

Node.normalize()
================

`Node.normalize()` 方法将当前节点和它的后代节点”规范化“（normalized）。在一个"规范化"后的 DOM 树中，不存在一个空的文本节点，或者两个相邻的文本节点。

注 1：“空的文本节点”并不包括空白字符 (空格，换行等) 构成的文本节点。

注 2：两个以上相邻文本节点的产生原因包括：

1. 通过脚本调用有关的 DOM 接口进行了文本节点的插入和分割等。
2. HTML 中超长的文本节点会被浏览器自动分割为多个相邻文本节点。
语法
--
```

element.normalize();
```

例子
--

```js
var wrapper = document.createElement("div");

wrapper.appendChild(document.createTextNode("Part 1 "));
wrapper.appendChild(document.createTextNode("Part 2 "));

// 这时 (规范化之前),wrapper.childNodes.length === 2
// wrapper.childNodes[0].textContent === "Part 1 "
// wrapper.childNodes[1].textContent === "Part 2 "

wrapper.normalize();
// 现在 (规范化之后), wrapper.childNodes.length === 1
// wrapper.childNodes[0].textContent === "Part 1 Part 2"
```

规范
--

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

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

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

See also
--------

* `Text.splitText()`


Node.ownerDocument - Web API 接口参考

Node.ownerDocument
==================

**Node.ownerDocument** 只读属性会返回当前节点的顶层的 document 对象。

语法
--
```

document = node.ownerDocument
```

* `document` 是当前元素的 `document` 对象，其是当前元素的祖先。
例子
--
```

// 得到 p 元素所在文档的 HTML 节点
d = p.ownerDocument;
html = d.documentElement;
```

注意
--

`被此属性返回的 document` 对象是在实际的 HTML 文档中的所有子节点所属的主对象`。如果在文档节点自身上使用此属性，则结果是 null`。

规范
--

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

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

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


Node.firstChild - Web API 接口参考

Node.firstChild
===============

**Node.firstChild** 只读属性返回树中节点的第一个子节点，如果节点是无子节点，则返回 `null`。

### 语法
```

var childNode = node.firstChild;
```

### 描述

如果有一个子节点，childNode 是节点的第一个子节点的引用，否则为 null。

### 示例

#### 示例 1

这个例子演示了`firstChild`属性的用法以及空白符节点对该属性的使用可能造成的影响。参见备注部分了解 Gecko DOM 中关于处理空白符的更多信息。
```

<p id="para-01">
  <span>First span</span>
</p>

<script type="text/javascript">
  var p01 = document.getElementById('para-01');
  alert(p01.firstChild.nodeName)
</script>
```

在上面的示例中，提示框将显示 '#text',因为在
标签和标签之前，有一个换行符和多个空格充当了一个文本节点。在 Gecko 中，任意多个的空白符都将导致文本节点的插入，包括一个到多个空格符，换行符，制表符等等。

和
标签之间就是另外一个文本节点。

如果从源代码移出对应的空白符，则不会有文本节点被插入，span 元素就成为了第一个子节点。下面的代码将弹出 'SPAN'.
```

<p id="para-01"><span>First span</span></p>

<script type="text/javascript">
  var p01 = document.getElementById('para-01');
  alert(p01.firstChild.nodeName)
</script>
```

#### 示例 2

假设我们有一个 HTML 文档，如果该文档有一个 DTD（文档类型定义），则下面的语句会弹出 `[object DocumentType]`，如果该文档没有一个 DTD，则下面的语句会弹出 `[object HTMLHtmlElement]`。
```

alert(document.firstChild);
```

### 备注

 Gecko 内核的浏览器会在源代码中标签内部有空白符的地方插入一个文本结点到文档中。因此，使用诸如
 `Node.firstChild` 和 `Node.previousSibling` 之类的方法可能会引用到一个空白符文本节点，
 而不是使用者所预期得到的节点。

 详情请参见 DOM 中的空白符 (en-US)
 和W3C DOM 3 FAQ: 为什么一些文本节点是空的.

### 规范

DOM Level 1 Core: firstChild

DOM Level 2 Core: firstChild


Node.isConnected - Web API 接口参考

Node.isConnected
================

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

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

* Learn more
* See full compatibility
* Report feedback
**`isConnected`** 是 `Node` 的一个只读属性接口。无论节点是否与 DOM 树连接，该属性都会返回一个`布尔值` (en-US)。例如：`Document` 对象与一般 DOM 树连接，`ShadowRoot` 与 shadow DOM 连接。

语法
--
```

var isItConnected = nodeObjectInstance.isConnected
```

### 返回值

返回 `布尔值` (en-US) — 如果该节点与 DOM 树连接则返回 `true`, 否则返回 `false`。

样例
--

### 标准 DOM 树

```js
let test = document.createElement("p");
console.log(test.isConnected); // Returns false
document.body.appendChild(test);
console.log(test.isConnected); // Returns true
```

### Shadow DOM 树

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

// Create some CSS to apply to the shadow dom
var style = document.createElement("style");
console.log(style.isConnected); // returns false

style.textContent =
  ".wrapper {" +
  "position: relative;" +
  "}" +
  ".info {" +
  "font-size: 0.8rem;" +
  "width: 200px;" +
  "display: inline-block;" +
  "border: 1px solid black;" +
  "padding: 10px;" +
  "background: white;" +
  "border-radius: 10px;" +
  "opacity: 0;" +
  "transition: 0.6s all;" +
  "position: absolute;" +
  "bottom: 20px;" +
  "left: 10px;" +
  "z-index: 3;" +
  "}" +
  // Attach the created style element to the shadow dom

  shadow.appendChild(style);
console.log(style.isConnected); // Returns true
```

规范
--

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

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

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


Node.hasChildNodes - Web API 接口参考

Node.hasChildNodes
==================

### 概述

**hasChildNodes**方法返回一个布尔值,表明当前节点是否包含有子节点.

语法
--
```

element.hasChildNodes()
```

例子
--

下面的例子演示了：如果 id 为 foo 的这个元素有子节点，则从 dom 树中删除它的第一个子节点。

```js
var foo = document.getElementById("foo");

if (foo.hasChildNodes()) {
  foo.removeChild(foo.childNodes[0]);
}
```

**备注：** `Node.hasChildNodes`是个方法，而不是普通属性，使用时必须加括号才能调用。

总结
--

有三种方法可以判断当前节点是否有子节点。

* node.firstChild !== null
* node.childNodes.length > 0
* node.hasChildNodes()
规范
--

* WHATWG: hasChildNodes
* hasChildNodes
相关链接
----

* `Node.childNodes`
* `Node.hasAttributes`


Node.appendChild - Web API 接口参考

Node.appendChild
================

**`Node.appendChild()`** 方法将一个节点附加到指定父节点的子节点列表的末尾处。如果将被插入的节点已经存在于当前文档的文档树中，那么 `appendChild()` 只会将它从原先的位置移动到新的位置（不需要事先移除要移动的节点）。

这意味着，一个节点不可能同时出现在文档的不同位置。所以，如果某个节点已经拥有父节点，在被传递给此方法后，它首先会被移除，再被插入到新的位置。若要保留已在文档中的节点，可以先使用 `Node.cloneNode()` 方法来为它创建一个副本，再将副本附加到目标父节点下。请注意，用 `cloneNode` 制作的副本不会自动保持同步。

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

**备注：** **有更加新的 API 可供使用！** > `ParentNode.append()` (en-US) 方法支持多个参数，接受字符串作为参数，会将字符串转换为文本节点再附加。

语法
--
```

element.appendChild(aChild)
```

### 参数

`aChild`

要追加给父节点（通常为一个元素）的节点。

### 返回值

返回追加后的子节点（`aChild`），除非 `aChild` 是一个文档片段（`DocumentFragment`），这种情况下将返回空文档片段（`DocumentFragment`）。

附注
--

如果你需要保留这个子节点在原先位置的显示，则你需要先用`Node.cloneNode`方法复制出一个节点的副本，然后在插入到新位置。

这个方法只能将某个子节点插入到同一个文档的其他位置，如果你想跨文档插入，你需要先调用`document.importNode`方法。

备注
--

由于 `appendChild()` 返回的是被附加的子元素，所以链式调用可能无法按照你的预期去执行：

```js
let aBlock = document
  .createElement("block")
  .appendChild(document.createElement("b"));
```

（上述代码）只会将 `aBlock` 设置为 `<b></b>` ，这可能不是你所想要的。

示例
--

```js
// 创建一个新的段落元素 <p>，然后添加到 <body> 的最尾部
var p = document.createElement("p");
document.body.appendChild(p);
```

规范
--

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

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

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

参见
--

* `Node.removeChild`
* `Node.replaceChild`
* `Node.insertBefore`
* `Node.hasChildNodes`


Node.nextSibling - Web API 接口参考

Node.nextSibling
================

**`Node.nextSibling`** 是一个只读属性，返回其父节点的 `childNodes` 列表中紧跟在其后面的节点，如果指定的节点为最后一个节点，则返回 `null`。

语法
--
```

nextNode = node.nextSibling
```

备注
--

Gecko 内核的浏览器会在源代码中标签内部有空白符的地方插入一个文本结点到文档中。因此，使用诸如 `Node.firstChild` 和 `Node.previousSibling` 之类的方法可能会引用到一个空白符文本节点，而不是使用者所预期得到的节点。

详情请参见 DOM 中的空白符 (en-US) 和W3C DOM 3 FAQ: 为什么一些文本节点是空的.

示例
--

```html
<div id="div-1">Here is div-1</div>
<div id="div-2">Here is div-2</div>
<br />
<output><em>Not calculated.</em></output>
```

```js
let el = document.getElementById("div-1").nextSibling;
let i = 1;

let result = "Siblings of div-1:<br/>";

while (el) {
  result += `${i}. ${el.nodeName}<br/>`;
  el = el.nextSibling;
  i++;
}

const output = document.querySelector("output");
output.innerHTML = result;
```

规范
--

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

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

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

相关链接
----

* `Element.nextElementSibling`
* `Node.previousSibling`


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

Node.getRootNode()
==================

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

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

* Learn more
* See full compatibility
* Report feedback
`Node` 接口的 **`getRootNode()`** 方法返回上下文中的根节点，如果 shadow DOM 可用，则对 shadow DOM 同样适用。

语法
--
```

var root = node.getRootNode(options);
```

### 参数

`options` 可选

获取根节点时的可选参数对象。下列值可供选择：

* `composed`: `Boolean` 如果检索到 shadow Root 需要返回，则设置为（`false`，默认值），如果跳过 shadow Root 检索普通 Root 则设置为（`true`）。

### 返回值

返回一个继承自 `Node` 的对象。返回值会因为 `getRootNode()` 调用的地方不同而不同; 比如说：

* 在标准的网页中调用将会返回一个 `HTMLDocument` 对象表示整个网页。
* 在 Shadow DOM 里调用将会返回一个与之相关联的 `ShadowRoot` 。
示例
--

第一个例子很简单，返回一个参照 HTML/document node 位置的一个节点。

```js
rootNode = node.rootNode;
```

我们来看一个稍微复杂的例子。这个例子展示了该属性在普通的 DOM 的 shadow DOM 的差别。 (See the full source code):

```html
<!-- source: https://github.com/jserz/js\_piece/blob/master/DOM/Node/getRootNode()/demo/getRootNode.html -->
<div class="js-parent">
  <div class="js-child"></div>
</div>
<div class="js-shadowHost"></div>
<script>
 // work on Chrome 54+，Opera41+

 var parent = document.querySelector(".js-parent"),
 child = document.querySelector(".js-child"),
 shadowHost = document.querySelector(".js-shadowHost");

 console.log(parent.getRootNode().nodeName); // #document
 console.log(child.getRootNode().nodeName); // #document

 // create a ShadowRoot
 var shadowRoot = shadowHost.attachShadow({ mode: "open" });
 shadowRoot.innerHTML =
 "<style>div{background:#2bb8aa;}</style>" +
 '<div class="js-shadowChild">content</div>';
 var shadowChild = shadowRoot.querySelector(".js-shadowChild");

 // The default value of composed is false
 console.log(shadowChild.getRootNode() === shadowRoot); // true
 console.log(shadowChild.getRootNode({ composed: false }) === shadowRoot); // true
 console.log(shadowChild.getRootNode({ composed: true }).nodeName); // #document
</script>
```

规范
--

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

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

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


Node.isEqualNode - Web API 接口参考

Node.isEqualNode
================

**`Node.isEqualNode()`** 方法可以判断两个节点是否相等。当两个节点的类型相同，定义特征 (defining characteristics) 相同（对元素来说，即 id，孩子节点的数量等等），属性一致等，这两个节点就是相等的。一些具体的数据指出：多数时候的比较是根据节点的类型来的。

### 语法
```

var isEqualNode = node.isEqualNode(otherNode);
```

* otherNode: 比较是否相等的节点。
示例
--

在本例中，我们创建了三个 `<div>` 块。第一个和第三个 div 都拥有相同的内容和属性，第二个则不一样。然后我们运行 JavaScript，使用 `isEqualNode()` 来比较这几个节点。

### HTML

```html
<div>This is the first element.</div>
<div>This is the second element.</div>
<div>This is the first element.</div>

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

### JavaScript

```js
let output = document.getElementById("output");
let divList = document.getElementsByTagName("div");

output.innerHTML +=
  "div 0 equals div 0: " + divList[0].isEqualNode(divList[0]) + "<br/>";
output.innerHTML +=
  "div 0 equals div 1: " + divList[0].isEqualNode(divList[1]) + "<br/>";
output.innerHTML +=
  "div 0 equals div 2: " + divList[0].isEqualNode(divList[2]) + "<br/>";
```

### 结果

### 规范

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

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

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

参见
--

* `Node.isSameNode()`


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

Node.contains()
===============

`Node` 接口的 **`contains()`** 方法返回一个布尔值，表示一个节点是否是给定节点的后代，即该节点本身、其直接子节点（`childNodes`）、子节点的直接子节点等。

**备注：** 节点*包含*在自身内部。

语法
--

```js
contains(otherNode)
```

参数
--

`otherNode`

要测试的节点。

**备注：** `otherNode` 不是可选的，但是可以设置为 `null`。

返回值
---

返回一个布尔值，如果 `otherNode` 包含在节点中会返回 `true`，否则返回 `false`。

如果 `otherNode` 参数为 `null`，则 `contains()` 始终返回 `false`。

示例
--

下面的函数用来检查一个元素是否是 body 元素的后代元素。由于 `contains` 会包含元素自身，而确定 body 是否包含自身不是设计 `isInPage` 的意图，这种情况明确返回 `false`。

```js
function isInPage(node) {
  return node === document.body ? false : document.body.contains(node);
}
```

规范
--

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

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

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

参见
--

* `Node.compareDocumentPosition`
* `Node.hasChildNodes`


Node.previousSibling - Web API 接口参考

Node.previousSibling
====================

### 概述

返回当前节点的前一个兄弟节点，没有则返回`null.`

### 语法
```

previousNode = node.previousSibling
```

### 例子
```

// <a><b1 id="b1"/><b2 id="b2"/></a>
alert(document.getElementById("b1").previousSibling); // null
alert(document.getElementById("b2").previousSibling.id); // "b1"
```

### 备注

Gecko 内核的浏览器会在源代码中标签内部有空白符的地方插入一个文本结点到文档中。因此，使用诸如 `Node.firstChild` 和 `Node.previousSibling` 之类的方法可能会引用到一个空白符文本节点，而不是使用者所预期得到的节点。

详情请参见 DOM 中的空白符 (en-US) 和W3C DOM 3 FAQ: 为什么一些文本节点是空的.

获取后一个兄弟节点，请使用Node.nextSibling.

### 规范

DOM Level 1 Core: previousSibling

DOM Level 2 Core: previousSibling


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

Node.replaceChild()
===================

**`Node.replaceChild()`** 方法用指定的节点替换当前节点的一个子节点，并返回被替换掉的节点。

语法
--

```js
replaceChild(newChild, oldChild)
```

### 参数

**`newChild`**

用来替换 `oldChild` 的新节点。如果该节点已经存在于 DOM 树中，则它首先会被从原始位置删除。

**`oldChild`**

被替换掉的原始节点。

### 返回值

返回值为被替换的节点，与 `oldChild` 为同一个节点。

示例
--

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

// 创建一个空的 span 元素节点
// 没有 id，没有任何属性和内容
const sp1 = document.createElement("span");

// 添加一个 id 属性，值为 'newSpan'
sp1.setAttribute("id", "newSpan");

// 创建一个文本节点
const sp1_content = document.createTextNode("新的 span 元素的内容。");

// 将文本节点插入到 span 元素中
sp1.appendChild(sp1_content);

// 获得被替换节点和其父节点的引用。
const sp2 = document.getElementById("childSpan");
const parentDiv = sp2.parentNode;

// 用新的 span 元素 sp1 来替换掉 sp2
parentDiv.replaceChild(sp1, sp2);

// 结果：
// <div>
// <span id="newSpan">新的 span 元素的内容。</span>
// </div>
```

规范
--

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

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

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

参见
--

* `Node.removeChild`
* `Element.replaceWith`


Node.isDefaultNamespace - Web API 接口参考

Node.isDefaultNamespace
=======================

### 概述

`isDefaultNamespace` 接受一个命名空间 URI 作为参数，如果该命名空间是当前节点的默认命名空间，则返回`true`,否则返回`false`.

### 语法
```

result = node.isDefaultNamespace(namespaceURI)
```

* `result` 为 `true` 或 `false`.
* `namespaceURI` 为一个命名空间 URI.
### 例子
```

var XULNS = "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul";
var el = document.getElementsByTagNameNS(XULNS, 'textbox')[0];
alert(el.isDefaultNamespace(XULNS)); // true
```

### 规范

* DOM Level 3 Core: isDefaultNamespace
* Code snippets: isDefaultNamespace