Document
========

**`Document`** 接口表示任何在浏览器中载入的网页，并作为网页内容的入口，也就是 DOM 树 (en-US)。

DOM 树包含了像 `<body>`、`<table>` 这样的元素，以及大量其他元素。它向网页文档本身提供了全局操作功能，能解决如何获取页面的 URL，如何在文档中创建一个新的元素这样的问题。

EventTarget

Node

Document
`Document` 接口描述了任何类型的文档的通用属性与方法。根据不同的文档类型（例如 HTML、XML (en-US)、SVG，...），还能使用更多 API：使用 `"text/html"` 作为内容类型（content type）的 HTML 文档，还实现了 `HTMLDocument` 接口，而 XML 和 SVG 文档则（额外）实现了 `XMLDocument` 接口。

构造函数
----

`Document()`

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

属性
--

*此接口也继承自 `Node` 和 `EventTarget` 接口。*

`Document.activeElement` 只读 

返回一个目前处于聚焦状态的 `Element`。

`Document.adoptedStyleSheets` (en-US)

设置用于构造文档样式表的数组。这些样式表也可与同一文档的 shadow DOM 子树共享。

`Document.body`

返回当前文档的 `<body>` 或 `<frameset>` 节点。

`Document.characterSet` 只读 

返回文档正在使用的字符集。

`Document.childElementCount` (en-US) 只读 

返回文档正在使用的子元素的数量。

`Document.children` (en-US) 只读 

返回当前文档的子元素。

`Document.compatMode` 只读 

指示文档是否以*怪异模式*（quirks）或*严格模式*（strict）渲染。

`Document.contentType` 只读 

根据当前文档的 MIME 标头，返回它的 Content-Type。

`Document.currentScript` 只读 

返回目前正在处理且不是 JavaScript 模块的 `<script>` 元素。

`Document.doctype` 只读 

返回当前文档的文档类型定义（Document Type Definition，DTD）。

`Document.documentElement` 只读 

返回当前文档的直接子节点。对于 HTML 文档，`HTMLHtmlElement` 对象一般代表该文档的`<html>` 元素。

`Document.documentURI` 只读 

以字符串的类型，返回当前文档的路径。

`Document.embeds` 只读 

返回一个包含当前文档的嵌入式的元素 `<embed>` 的 `HTMLCollection`。

`Document.firstElementChild` (en-US) 只读 

返回当前文档的第一个子元素。

`Document.fonts`

返回当前文档的 `FontFaceSet` 接口。

`Document.forms` 只读 

返回一个包含当前文档中所有表单元素 `<form>` 的 `HTMLCollection`。

`Document.fullscreenElement` 只读 

返回文档中正处于全屏模式的元素。

`Document.head` 只读 

返回当前文档的 `<head>` 元素。

`Document.hidden` 只读 

返回一个布尔值，表明当前页面是否隐藏。

`Document.images` 只读 

返回当前文档中所包含的图片的 `HTMLCollection`。

`Document.implementation` 只读 

返回与当前文档相关联的 DOM 实现。

`Document.lastElementChild` (en-US) 只读 

返回当前文档的最后一个子元素。

`Document.links` 只读 

返回一个包含文档中所有超链接的 `HTMLCollection`。

`Document.pictureInPictureElement` 只读 

返回文档中正处于画中画模式的 `Element`。

`Document.pictureInPictureEnabled` 只读 

若画中画特性可用，则返回 `true`。

`Document.plugins` 只读 

返回一个包含可用插件的 `HTMLCollection`。

`Document.pointerLockElement` 只读 

当指针被锁定时，返回鼠标事件的目标的元素集合。若锁定正处于等待状态、指针已被解锁，或是目标正处于另一个文档中，则返回 `null`。

`Document.featurePolicy` (en-US) 
实验性
 只读 

返回一个 `FeaturePolicy` (en-US) 接口，该结构为应用于特定文档的特性策略提供了一个简单的 API。

`Document.scripts` 只读 

返回包含文档中所有的 `<script>` 元素的 `HTMLCollection`。

`Document.scrollingElement` 只读 

返回对滚动文档的 `Element` 的引用。

`Document.styleSheets` 只读 

返回一个包含显式链接或嵌入到文档中的 `CSSStyleSheet` 对象的 `StyleSheetList`。

`Document.timeline` 只读 

返回 `DocumentTimeline` (en-US) 的一个实例，该实例是在页面加载时自动创建的。

`Document.visibilityState` 只读 

返回一个 `string`，表明当前文档的可见性。可能的取值有 `visible`、`hidden`、`prerender` 和 `unloaded`。

### HTMLDocument 的扩展

*HTML 文件的 `Document` 接口继承自 `HTMLDocument` 接口，或扩展了这些方法：*

`Document.cookie`

返回一个使用分号分隔的 cookie 列表，或设置（写入）一个 cookie。

`Document.defaultView` 只读 

返回一个对 `window` 对象的引用。

`Document.designMode`

获取或设置编辑整个文档的能力。

`Document.dir`

获取或设置文档的文字方向（rtl 或 ltr）。

`Document.domain` 
已弃用

获取或设置当前文档的域。

`Document.lastModified` 只读 

返回文档最后修改的时间。

`Document.location` 只读 

返回当前文档的 URI。

`Document.readyState` 只读 

返回当前文档的加载状态。

`Document.referrer` 只读 

返回来源页面的 URI。

`Document.title`

获取或设置当前文档的标题。

`Document.URL` 只读 

以字符串形式返回文档的地址栏链接。

### 已弃用的属性

`Document.alinkColor` 
已弃用

获取或设置文档正文部分启用的链接的颜色。

`Document.all` 
已弃用

返回一个以文档节点为根节点的 `HTMLAllCollection` (en-US) 集合，以访问文档中所有的元素。这是遗留的非标准属性，不应使用。

`Document.anchors` 
已弃用
 只读 

返回文档中所有锚点元素的列表。

`Document.applets` 
已弃用
 只读 

返回文档中 `applet` 对象的有序列表。

`Document.bgColor` 
已弃用

获取或设置当前文档的背景颜色。

`Document.charset` 
已弃用
 只读 

`Document.characterSet` 的别名，请使用原始属性替换。

`Document.fullscreen` 
已弃用

若文档处于全屏模式，则返回 `true`。

`Document.height` 
非标准

已弃用

获取或设置当前文档的高度。

`Document.inputEncoding` (en-US) 只读  
已弃用

`Document.characterSet` 的别名，请使用原始属性替换。

`Document.lastStyleSheetSet` 
已弃用
 只读  
非标准

返回最后启用的样式表的名字。在设置 `selectedStyleSheetSet` 前，其值都为 `null`。

`Document.linkColor` 
已弃用

获取或设置文档中超链接的颜色。

`Document.preferredStyleSheetSet` 
已弃用
 只读  
非标准

返回文档作者首选的样式表。

`Document.rootElement` (en-US) 
已弃用

类似于 `Document.documentElement`，但其仅用于 `<svg>` 根元素。请使用后者代替。

`Document.selectedStyleSheetSet` 
已弃用
 只读 

返回当前正使用的样式表的集合。

`Document.styleSheetSets` 
已弃用
 只读  
非标准

返回文档上可用样式表的集合。

`Document.vlinkColor` (en-US) 
已弃用

获取或设置被访问的超链接的颜色。

`Document.width` 
非标准

已弃用

返回当前文档的宽度。

`Document.xmlEncoding` (en-US) 
已弃用

返回由 XML 声明的编码类型。

`Document.xmlStandalone` 
已弃用

若 XML 声明指定的文档是独立的（例如：文档类型定义的外部内容会影响文档的内容），则返回 `true`，否则返回 `false`。

`Document.xmlVersion` (en-US) 
已弃用

返回 XML 声明中指定的版本号，若声明不存在则为 `"1.0"`。

方法
--

*该接口同样继承了 `Node` 和 `EventTarget` 接口。*

`Document.adoptNode()`

从外部文档中采用的节点。

`Document.append()` (en-US)

在文档的最后一个子节点后插入一个 `Node` 对象或字符串对象的集合。

`Document.captureEvents()` 
已弃用

参见 `Window.captureEvents` (en-US)。

`Document.caretPositionFromPoint()`

返回一个包含 DOM 节点（包含插入符号以及该符号在节点中的字符偏移量）的 `CaretPosition` 对象。

`Document.caretRangeFromPoint()` 
非标准

获取一个 `Range` 对象，其为指定坐标下的文档片段。

`Document.createAttribute()`

创建一个新的 `Attr` 对象并返回。

`Document.createAttributeNS()` (en-US)

在给定命名空间创建一个新的属性节点并返回。

`Document.createCDATASection()`

创建一个新的数据（CDATA）节点并返回。

`Document.createComment()`

创建一个新的注释节点并返回。

`Document.createDocumentFragment()`

创建一个新的文档片段。

`Document.createElement()`

用给定标签名创建一个新的元素。

`Document.createElementNS()`

用给定标签名和命名空间创建一个新的元素。

`Document.createEntityReference()` (en-US) 
已弃用

创建一个新的实体引用对象并返回。

`Document.createEvent()`

创建一个事件对象。

`Document.createNodeIterator()`

创建一个 `NodeIterator` 对象。

`Document.createProcessingInstruction()`

创建一个新的 `ProcessingInstruction` (en-US) 对象。

`Document.createRange()`

创建一个 `Range` 对象。

`Document.createTextNode()`

创建一个文本节点。

`Document.createTouch()` (en-US) 
已弃用

非标准

创建一个 `Touch` 对象。

`Document.createTouchList()` (en-US) 
已弃用

非标准

创建一个 `TouchList` 对象。

`Document.createTreeWalker()`

创建一个 `TreeWalker` 对象。

`Document.elementFromPoint()`

返回指定坐标最顶层的元素。

`Document.elementsFromPoint()`

返回包含指定坐标下所有元素的数组。

`Document.enableStyleSheetsForSet()` (en-US) 
已弃用

非标准

启用指定的样式表集合。

`Document.exitPictureInPicture()`

从浮动的画中画窗口中移除视频，并返回到它的原始容器。

`Document.exitPointerLock()`

释放指针锁。

`Document.getAnimations()` (en-US)

返回包含所有目前有效的 `Animation` 对象（其目标元素为 `document`）的数组。

`Document.getBoxQuads()` 
实验性

返回一个 `DOMQuad` 对象（表示节点中的 CSS 片段）的列表。

`Document.getElementById()`

返回标识元素的引用对象。

`Document.getElementsByClassName()`

返回具有给定类名的元素列表。

`Document.getElementsByTagName()`

返回具有给定标签名的元素列表。

`Document.getElementsByTagNameNS()`

返回具有给定标签名和命名空间的元素列表。

`Document.getSelection()` (en-US)

返回一个 `Selection` 对象，表示用户选择的文本范围或是插入符号当前的位置。

`Document.hasStorageAccess()`

返回一个 `Promise`，会兑现一个布尔值，用于表示文档是否有访问第一方储存的权限。

`Document.importNode()`

返回外部文档的节点的拷贝。

`Document.normalizeDocument()` 
已弃用

替换实体、规范化文本节点，等待。

`Document.prepend()` (en-US)

在文档的第一个子节点前插入一个 `Node` 对象或字符串对象的集合。

`Document.querySelector()`

返回文档中与指定的选择器匹配的第一个元素节点。

`Document.querySelectorAll()`

返回包含文档中与指定的选择器匹配的所有元素节点的列表。

`Document.releaseCapture()` 
非标准

若鼠标在当前文档的某一个元素之上，则释放当前的鼠标捕获。

`Document.releaseEvents()` 
已弃用

参见 `Window.releaseEvents()` (en-US)。

`Document.replaceChildren()` (en-US)

用一哥指定的新的子节点集合替换替换文档中现有的子节点。

`Document.requestStorageAccess()` (en-US)

返回一个 `Promise`，若第一方存储权限可用，则兑现，否则拒绝。

`Document.mozSetImageElement()` (en-US) 
非标准

允许你使用具有给定 ID 的元素作为背景图片。

`Document` 接口使用 `XPathEvaluator` 接口扩展：

`Document.createExpression()`

编译一个 `XPathExpression` (en-US)，以用于（重复）执行。

`Document.createNSResolver()` (en-US)

创建一个 `XPathNSResolver` (en-US) 对象。

`Document.evaluate()`

执行一个 XPath 表达式。

### HTML 文档的扩展

HTML 文档的 `Document` 接口继承自 `HTMLDocument` 接口，或扩展了这些方法：

`Document.clear()` 
已弃用

在大多数现代浏览器中，包括最新版本的 Firefox 和 Internet Explorer，这个方法没有任何作用。

`Document.close()`

关闭用于写入的文档流。

`Document.execCommand()` 
已弃用

在可编辑文档中执行格式化命令。

`Document.getElementsByName()`

返回一个具有给定名称的元素的列表。

`Document.hasFocus()`

若焦点目前位于给定的文档内，则返回 `true`。

`Document.open()`

打开用于写入的文档流。

`Document.queryCommandEnabled()` 
已弃用

非标准

若可在当前范围内执行格式化命令，则返回 `true`。

`Document.queryCommandIndeterm()` 
已弃用

若格式化命令在当前范围内处于不确定的状态，则返回 `true`。

`Document.queryCommandState()` 
已弃用

非标准

若格式化命令已在当前范围内执行，则返回 `true`。

`Document.queryCommandSupported()` 
已弃用

非标准

若当前范围支持格式化命令，则返回 `true`。

`Document.queryCommandValue()` 
已弃用

返回格式化命令当前的范围。

`Document.write()`

向文档写入文本。

`Document.writeln()`

向文档写入一行文本。

事件
--

列出了使用 `addEventListener()` 或为接口的事件处理器属性 `oneventname` 赋值的方式来监听的事件。

`afterscriptexecute` 
非标准

在静态的 `<script>` 元素执行完其中的脚本时触发。

`beforescriptexecute`

在静态的 `<script>` 开始执行脚本时触发。

`scroll`

在滚动文档视图或元素时触发。

`visibilitychange`

在变前的内容变为可见、隐藏时触发。

`wheel` (en-US)

在用户在点击设备（通常为鼠标）上转动滚轮时触发。

### 动画事件

`animationcancel` (en-US)

在动画意外中止时触发。

`animationend` (en-US)

在动画正常完成时触发。

`animationiteration` (en-US)

在动画迭代完成时触发。

`animationstart` (en-US)

在动画开始时触发。

### 剪切板事件

`copy` (en-US)

在用户通过浏览器的用户界面使用复制操作时触发。

`cut` (en-US)

在用户通过浏览器的用户界面使用剪切操作时触发。

`paste` (en-US)

在用户通过浏览器的用户界面使用粘贴操作时触发。

### 拖放事件

`drag`

在用户拖动元素或选择的文本时每几百毫秒触发一次。

`dragend`

在拖动操作结束（通过释放鼠标按钮或按下退出键））时触发。

`dragenter`

在拖动的元素或选择的文本进入有效的放置目标时触发。

`dragleave`

在拖动的元素或选择的文本离开有效的放置目标时触发。

`dragover`

在拖动的元素或选择的文本在有效的放置目标时触发（每几百毫秒）。

`dragstart`

在用户开始拖动元素或选择的文本时触发。

`drop`

在元素或选择的文本被放置在有效的放置目标时触发。

### 全屏事件

`fullscreenchange`

在 `Document` 进入或退出全屏模式时触发。

`fullscreenerror`

在尝试进入或退出全屏模式而发生错误时触发。

### 键盘事件

`keydown` (en-US)

在某个键被按下时触发。

`keypress` 
已弃用

在按下产生字符值的键时触发。

`keyup` (en-US)

在释放按键时触发。

### 加载和卸载事件

`DOMContentLoaded`

在文档完全加载并解析后触发，无需等待样式表、图像和子框架完成加载。

`readystatechange`

在文档的 `readyState` 属性发生变化时触发。

### 指针事件

`gotpointercapture` (en-US)

在使用 `setPointerCapture()` 捕获元素时触发。

`lostpointercapture` (en-US)

在捕获指针释放时触发。

`pointercancel` (en-US)

在指针事件取消时触发。

`pointerdown` (en-US)

在指针变为活动状态时触发。

`pointerenter` (en-US)

在指针移入到元素或其子元素之一的命中测试边界时触发。

`pointerleave` (en-US)

在指针移出元素的命中测试边界时触发。

`pointerlockchange`

在指针被锁定或解锁时触发。

`pointerlockerror` (en-US)

在指针锁定失败时触发。

`pointermove` (en-US)

在指针坐标改变时触发。

`pointerout` (en-US)

在指正移除元素的*命中测试*边界（或其他原因）时触发。

`pointerover` (en-US)

在指针移入元素的命中测试边界时触发。

`pointerup` (en-US)

在指针不再活动时触发。

### 选择事件

`selectionchange`

在文档中的选中的文本发生改变时触发。

### 触摸事件

`touchcancel`

在一个或多个接触点以特定于实现的方式中断（例如，创建了太多的接触点）时触发。

`touchend`

在从接触面移除一个或多个接触点时触发。

`touchmove`

在一个或多个接触点沿接触面移动时触发。

`touchstart`

在向接触面放置一个或多个接触点时触发。

### 过渡事件

`transitioncancel` (en-US)

在 CSS 过渡取消时触发。

`transitionend` (en-US)

在 CSS 过渡完成时触发。

`transitionrun` (en-US)

在 CSS 过渡第一次创建时触发。

`transitionstart` (en-US)

在 CSS 过渡实际开始时触发。

规范
--

| Specification |
| --- |
| DOM Standard # interface-document |
| HTML Standard # the-document-object |
| CSSOM View Module # extensions-to-the-document-interface |
| Pointer Lock 2.0 # extensions-to-the-document-interface |
| Selection API # extensions-to-document-interface |

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

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