recursal/MDN huggingface dataset:
MouseEvent.initMouseEvent()
===========================

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

**`MouseEvent.initMouseEvent()`** 方法用以在鼠标事件创建时 (一般用 `Document.createEvent()`方法创建) 初始化其属性的值。

事件初始化是在事件被`Document.createEvent()`方法创建后必需的。这个方法必须在事件被`EventTarget.dispatchEvent()`方法发送出来前调用。一旦事件被发送后，它将不再起任何作用。

**备注：** **不要再用此方法，已过时。**

使用特定的事件构造器来替代它，像 `MouseEvent()`。创建并发送事件 (en-US) 页面里有更多的使用信息。

语法
--
```

event.initMouseEvent(type, canBubble, cancelable, view,
                     detail, screenX, screenY, clientX, clientY,
                     ctrlKey, altKey, shiftKey, metaKey,
                     button, relatedTarget);
```

### 形参

*`type`*

设置事件类型`type` 的字符串，包含以下几种鼠标事件：`click`，`mousedown`，`mouseup`，`mouseover`，`mousemove`，`mouseout`。

*`canBubble`*

是否可以冒泡。取值集合见`Event.bubbles`。

*`cancelable`*

是否可以阻止事件默认行为。取值集合见`Event.cancelable`。

*`view`*

事件的 AbstractView 对象引用，这里其实指向`window` 对象。取值集合见 `UIEvent.view`。

*`detail`*

事件的鼠标点击数量。取值集合见`Event.detail` (en-US)。

*`screenX`*

事件的屏幕的 x 坐标。取值集合见`MouseEvent.screenX`。

*`screenY`*

事件的屏幕的 y 坐标。取值集合见`MouseEvent.screenY`。

*`clientX`*

事件的客户端 x 坐标。取值集合见`MouseEvent.clientX`。

*`clientY`*

事件的客户端 y 坐标。取值集合见`MouseEvent.clientY`。

*`ctrlKey`*

事件发生时

`control`

键是否被按下。取值集合见`MouseEvent.ctrlKey`。

*`altKey`*

事件发生时

`alt`

键是否被按下。取值集合见`MouseEvent.altKey`。

*`shiftKey`*

事件发生时

`shift`

键是否被按下。取值集合见`MouseEvent.shiftKey`。

*`metaKey`*

事件发生时

`meta`

键是否被按下。取值集合见`MouseEvent.metaKey`。

*`button`*

鼠标按键值 `button`。

*`relatedTarget`*

事件的相关对象。只在某些事件类型有用 (例如 `mouseover` ?和 `mouseout`)。其他的传 null。

示例
--

### HTML


```html
<div style="background:red;width:180px;padding:10px;">
  <div id="out"></div>
  <input type="text" />
</div>
```

### JavaScript


```js
document.body.onclick = function () {
  e = arguments[0];
  var dt = e.target,
    stag = dt.tagName.toLowerCase();
  document.getElementById("out").innerHTML = stag;
};
var simulateClick = function () {
  var evt = document.createEvent("MouseEvents");
  evt.initMouseEvent(
    "click",
    true,
    true,
    window,
    0,
    0,
    0,
    80,
    20,
    false,
    false,
    false,
    false,
    0,
    null,
  );
  document.body.dispatchEvent(evt);
};
simulateClick(); //Why it can not show "input" ?
```


这里有个在线演示

规范
--

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

请使用 `MouseEvent()` 构造函数代替。

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

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

参阅
--

* `MouseEvent()`构造器，更标准的创建`MouseEvent`对象方法。
* `Event.initEvent()`可以简单达到相同目的的方法。它已过时不再使用。
MouseEvent.mozInputSource
=========================

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

`MouseEvent`中的 **`MouseEvent.mozInputSource`** 是只读属性，它提供触发事件的设备信息。例如，当一个鼠标事件发生时，你能根据 **`MouseEvent.mozInputSource`** 属性判断该事件是由鼠标还是由触屏设备触发的（这将影响到你对于事件发生坐标解释的精确度）。

语法
--
```

var source = event.mozInputSource;
```

### 值

下列值都是合法的

| 常量名称 | 值 | 描述 |
| --- | --- | --- |
| `MOZ_SOURCE_UNKNOWN` | 0 | 该事件是由未知设备触发的。 |
| `MOZ_SOURCE_MOUSE` | 1 | 该事件是由鼠标（或类似的设备）触发的。 |
| `MOZ_SOURCE_PEN` | 2 | 该事件是由触屏笔在写字板上触发的。 |
| `MOZ_SOURCE_ERASER` | 3 | 该事件是由触屏橡皮擦在写字板上触发的。 |
| `MOZ_SOURCE_CURSOR` | 4 | 该事件是由指针触发的。 |
| `MOZ_SOURCE_TOUCH` | 5 | 该事件是在触屏设备上触发的。 |
| `MOZ_SOURCE_KEYBOARD` | 6 | 该事件是由键盘触发的。 |

详述
--

无
MouseEvent.movementY
====================

`MouseEvent` 接口的 **`MouseEvent.movementY`** 只读属性提供了当前事件和上一个 `mousemove` 事件之间鼠标在竖直方向上的移动值。换句话说，这个值是这样计算的：`currentEvent.movementY = currentEvent.screenY - previousEvent.screenY`。

语法
--
```

var yShift = instanceOfMouseEvent.movementY
```

### 返回值

A number

规范
--

| Specification |
| --- |
| Pointer Lock 2.0 # dom-mouseevent-movementy |

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

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

相关
--

* `MouseEvent`
* Pointer Lock (en-US)
MouseEvent.offsetX
==================

`MouseEvent` 接口的只读属性 **offsetX** 规定了事件对象与目标节点的内填充边（padding edge）在 X 轴方向上的偏移量。

语法
--
```

var xOffset = instanceOfMouseEvent.offsetX;
```

### 返回值

一个`双精度` 浮点值。早期的规范将其规定为整数值。详见浏览器兼容性部分。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-mouseevent-offsetx |

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

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

相关内容
----

* `MouseEvent`
Touch.target
============

概述
--

这个属性返回触摸点最初接触的 `Element`，即使这个触摸点已经移出那个元素的交互区域，甚至移出文档。需要注意的是，如果这个元素在触摸过程中被移除，这个事件仍然会指向它，因此这个事件也不会冒泡到 `window` 或 `document` 对象。因此，如果有元素在触摸过程中可能被移除，最佳实践是将触摸事件的监听器绑定到这个元素本身，防止元素被移除后，无法再从它的上一级元素上侦测到从该元素冒泡的事件。

语法
--
```

var el = touchPoint.target;
```

### 返回值

`el`

`Touch` 对象的目标元素。

示例
--

这个例子展示了如何访问 `Touch` 对象的 `Touch.target` 属性。`Touch.target` 属性是最初接触平面的触摸点下的 `Element` (`EventTarget`) 。

在下面的代码片段中，我们假设用户在 `source` 元素上开始接触，因此初始化了一个或多个触摸点。当这个元素上的 `touchstart` 事件处理程序被调用时，每个触摸点的 `Touch.target` 属性可经事件的 `TouchEvent.targetTouches` 列表访问。


```js
// 为'source'元素注册一个触摸监听器
var src = document.getElementById("source");

src.addEventListener(
  "touchstart",
  function (e) {
    // 在这个元素上激活的触点间循环
    for (var i = 0; i < e.targetTouches.length; i++) {
      console.log(
        "touchpoint[" + i + "].target = " + e.targetTouches[i].target,
      );
    }
  },
  false,
);
```

规范
--

| Specification |
| --- |
| Touch Events # dom-touch-target |

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

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

### 概述

返回一个可以唯一地识别和触摸平面接触的点的值。这个值在这根手指（或触摸笔等）所引发的所有事件中保持一致，直到它离开触摸平面。

### 语法
```

var id = touchItem.identifier;
```

### 返回值

`id`

`Touch` 对象的唯一标识符。

### 标准定义

Touch Events Specification
Touch.pageX
===========

### 概述

触点相对于 HTML 文档左边沿的的 X 坐标。和 `clientX` 属性不同，这个值是相对于整个 html 文档的坐标，和用户滚动位置无关。因此当存在水平滚动的偏移时，这个值包含了水平滚动的偏移。

### 语法
```

var x = touchItem.pageX;
```

### 返回值

`x`

触点相对于 HTML 文档左边沿的的 X 坐标。当存在水平滚动的偏移时，这个值包含了水平滚动的偏移。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.pageY`
* `Touch.screenX`
* `Touch.clientX`
Touch()
=======

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

**`Touch()`** 构造器创建一个新的 `Touch` 对象。

Syntax
------
```

 touch = new Touch(touchInit);
```

### Arguments

*touchInit*

是一个`TouchInit` 字典，它拥有以下属性：

* `"identifier"`, 必须，是一个长整型，表示一个触摸点的数字标记。
* `"target"`, 必须，是 `EventTarget`类型，表示在触摸点开始接触接触面时的节点。
* `"clientX"`, 可选，默认为 0，为双精度浮点数类型，表示触摸在浏览器视口的横轴坐标，不包括滚动条的偏移距离。
* `"clientY"`, 可选，默认为 0，为双精度浮点数类型，表示触摸在浏览器视口的横轴坐标，不包括滚动条的偏移距离。
* `"screenX"`, 可选，默认为 0，为双精度浮点数类型，表示以用户屏幕为基准的，触摸点横坐标。
* `"screenY"`, 可选，默认为 0，为双精度浮点数类型，表示以用户屏幕为基准的，触摸点纵坐标。
* `"pageX"`,可选，默认为 0，为双精度浮点数类型，表示触摸在用户屏幕的横轴坐标，包括滚动条的偏移距离。
* `"pageY"`, 可选，默认为 0，为双精度浮点数类型，表示触摸在用户屏幕的纵轴坐标，包括滚动条的偏移距离。
* `"radiusX"`, 可选，默认为 0，为浮点数类型。表示接触面（比如手指，触控笔）接触形成的椭圆，在 rotationAngle 角度下横轴上形成的椭圆半径。和 screenX 使用的 CSS 像素保持同一个缩放大小。这个值不能为负。
* `"radiusY"`, 可选，默认为 0，为浮点数类型。表示接触面（比如手指，触控笔）接触形成的椭圆，在 rotationAngle 角度下纵轴上形成的椭圆半径。和 screenY 使用的 CSS 像素保持同一个缩放大小。这个值不能为负。
* `"rotationAngle"`, 可选，默认为 0，为浮点数类型。表示由 radiusX 和 radiusY 决定的椭圆在顺时针方向相对其中心偏转的角度。这个值介于 0 到 90 度之间。如果由 radiusX 和 radiusY 决定的椭圆是一个标准圆形，则 rotationAngle 没有任何效用。用户设备可能用 0 表示这种标准圆形的情况，或者用其他符合要求范围的值来表示（比如，用户设备可能用上一次的触摸事件 rotationAngle 值，来避免突然变动）。
* `"force"`,可选，默认为 0，为浮点数类型。表示触摸体对触摸面的压力值。范围为从 0 到 1:0 表示压力为零，1 表示设备能承受的最大压力敏感值。对压力的敏感值变动范围根据不同环境变动比较大。

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

| Specification |
| --- |
| Touch Events # dom-touch-constructor |

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

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

See also
--------

* `TouchEvent`, the interface of the objects it constructs.
Touch.radiusY
=============

### 概述

能够包围用户和触摸平面的接触面的最小椭圆的垂直轴 (Y 轴) 半径。这个值的单位和 `screenY` 相同。

这个属性和 `Touch.radiusX`、`Touch.rotationAngle` 一起，描述了用户和触摸平面的接触面。这在面向非精确触摸设备 (由手指直接操作的触摸屏) 开发时非常有用。这些值描述了一个尽可能接近实际接触面 (例如用户的指尖) 的椭圆。

### 语法
```

var yRadius = touchItem.radiusY;
```

### 返回值

`yRadius`

能够包围用户和触摸平面的接触面的最小椭圆的垂直轴 (Y 轴) 半径。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.radiusX`
* `Touch.rotationAngle`
* `Touch.force`
Touch.pageY
===========

### 概述

触点相对于 HTML 文档上边沿的的 Y 坐标。和 `clientY` 属性不同，这个值是相对于整个 html 文档的坐标，和用户滚动位置无关。因此当存在垂直滚动的偏移时，这个值包含了垂直滚动的偏移。

### 语法
```

var y = touchItem.pageY;
```

### 返回值

`y`

触点相对于 HTML 文档上边沿的的 Y 坐标。当存在垂直滚动的偏移时，这个值包含了垂直滚动的偏移。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.pageX`
* `Touch.screenY`
* `Touch.clientY`
Touch.radiusX
=============

### 概述

能够包围用户和触摸平面的接触面的最小椭圆的水平轴 (X 轴) 半径。这个值的单位和 `screenX` 相同。

这个属性和 `Touch.radiusY` 、`Touch.rotationAngle` 一起，描述了用户和触摸平面的接触面。这在面向非精确触摸设备 (由手指直接操作的触摸屏) 开发时非常有用。这些值描述了一个尽可能接近实际接触面 (例如用户的指尖) 的椭圆。

### 语法
```

var xRadius = touchItem.radiusX;
```

### 返回值

`xRadius`

能够包围用户和触摸平面的接触面的最小椭圆的水平轴 (X 轴) 半径。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.radiusY`
* `Touch.rotationAngle`
* `Touch.force`
Touch.rotationAngle
===================

### 概述

返回以度为单位的旋转角。由 `radiusX` 和 `radiusY` 描述的正方向的椭圆，通过顺时针旋转这个角度后，能最精确地覆盖住用户和触摸平面的接触面的角度。这个值可能从 0 到 90。这三个值一起描述了用户和触摸平面的接触面的形状的大小。例如，当用户使用手指和平面接触时，它可能是一个较大的椭圆，而当用户使用触摸笔时，它可能是很小的椭圆。

### 语法
```

var angle = touchItem.rotationAngle;
```

### 返回值

`angle`

以度为单位的旋转角。由 `radiusX` 和 `radiusY` 描述的正方向的椭圆，通过顺时针旋转这个角度后，能最精确地覆盖住用户和触摸平面的接触面的角度。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.radiusX`
* `Touch.radiusY`
* `Touch.force`
Touch.force
===========

### 概述

返回这个 `Touch` 对象对应的手指挤压触摸平面的压力大小，从 0.0(没有压力) 到 1.0(最大压力) 的浮点数。

### 语法
```

var force = touchItem.force;
```

### 返回值

`force`

手指挤压触摸平面的压力大小。从 0.0(没有压力) 到 1.0(设备可识别的最大压力) 的浮点数。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.radiusX`
* `Touch.radiusY`
* `Touch.rotationAngle`
Touch.screenX
=============

### 概述

返回触点相对于屏幕左边沿的的 X 坐标。不包含页面滚动的偏移量。

### 语法
```

var x = touchItem.screenX;
```

### 返回值

`x`

触点相对于屏幕左边沿的的 X 坐标。不包含页面滚动的偏移量。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.screenY`
* `Touch.clientX`
* `Touch.pageX`
Touch.clientX
=============

### 概述

返回触点相对于可见视区 (visual viewport) 左边沿的的 X 坐标。不包括任何滚动偏移。这个值会根据用户对可见视区的缩放行为而发生变化。

### 语法
```

var x = touchItem.clientX;
```

### 返回值

`x`

触点相对于可见视区 (visual viewport) 左边沿的的 X 坐标。不包括任何滚动偏移。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.clientY`
* `Touch.screenX`
* `Touch.pageX`
Touch.clientY
=============

### 概述

返回触点相对于可见视区 (visual viewport) 上边沿的的 Y 坐标。不包括任何滚动偏移。这个值会根据用户对可见视区的缩放行为而发生变化。

### 语法
```

var y = touchItem.clientY;
```

### 返回值

`y`

返回触点相对于可见视区 (visual viewport) 上边沿的的 Y 坐标。不包括任何滚动偏移。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.clientX`
* `Touch.screenY`
* `Touch.pageY`
Touch.screenY
=============

### 概述

返回触点相对于屏幕上边沿的 Y 坐标。不包含页面滚动的偏移量。

### 语法
```

var y = touchItem.screenY;
```

### 返回值

`y`

触点相对于屏幕上边沿的 Y 坐标。不包含页面滚动的偏移量。

### 标准定义

Touch Events Specification

### 相关链接

* `Touch.screenX`
* `Touch.clientY`
* `Touch.pageY`
MediaCapabilitiesInfo
=====================

Media Capabilities API (en-US)的\*\*`MediaCapabilitiesInfo`\*\* 接口在 `MediaCapabilities` (en-US)接口的 `MediaCapabilities.encodingInfo()` 或 `MediaCapabilities.decodingInfo()` (en-US) 方法返回的 promise 完成时变得可用。它提供了媒体类型是否支持，在编码或解码此媒体时是否流畅和能效等信息。

属性
--

`MediaCapabilitiesInfo` 接口包含 3 个布尔属性：

* `supported`: 给出 `MediaConfiguration` 中定义的属性，确定指定的媒体内容能否完全被 编码 (如果 `MediaEncodingConfiguration` (en-US) 已设置) 或 解码 (如果 `MediaDecodingConfiguration` (en-US) 已设置) 。如果是，`supported` 为 *true*. 否则为 *false*.
* `smooth`: 给出 `MediaConfiguration` 中定义的属性，确定指定的媒体内容在回放时能否高质量和流畅。如果 `supported` 为 `true`, 并且回放时将流畅，`smooth` 为 *true*, 否则为 *false.*
* `powerEfficient`: 给出 `MediaConfiguration` 中定义的属性，确定指定的媒体内容在回放时能否高能效。如果 `supported` 为 `true`, 并且回放时将高能效，`powerEfficient` 为 *true*, 否则为 *false.*

浏览器将报告一个支持的媒体配置为 `smooth` 和 `powerEfficient` 直到此设备的统计信息被记录。所有受支持的音频编解码器将报告为高能效。

范例
--


```js
// 测试的 MediaConfiguration
const mediaConfig = {
    type : 'file',
    audio : {
        contentType : "audio/ogg",
        channels : 2,
        bitrate : 132700,
        samplerate : 5200
     },
};

// 检查支持和性能
navigator.mediaCapabilities.decodingInfo(mediaConfig).then(result => { // result 包含媒体兼容信息
    console.log('This configuration is ' +
        (result.supported ? '' : 'not ') + 'supported, ' +             // 配置的媒体能否被用户代理解码？
        (result.smooth ? '' : 'not ') + 'smooth, and ' +               // 是否流畅？
        (result.powerEfficient ? '' : 'not ') + 'power efficient.').   // 是否高能效？
});
```

规范
--

| Specification |
| --- |
| Media Capabilities # ref-for-dom-mediacapabilities-encodinginfo |

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

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

参考
--

* `MediaConfiguration`
* `MediaCapabilities.encodingInfo()`
* `MediaCapabilities.decodingInfo()` (en-US)
FileSystemDirectoryReader.readEntries()
=======================================

`FileSystemDirectoryReader` (en-US) 接口的 **`readEntries()`** 方法用于检索正在读取的目录中的目录条目，并将它们以数组的形式传递给提供的回调函数。

数组中的对象都是 `FileSystemEntry` (en-US) 实例。它们要么是代表标准文件的 `FileSystemFileEntry` 对象，要么是代表目录的 `FileSystemDirectoryEntry` 对象。

语法
--


```js
readEntries(successCallback)
readEntries(successCallback, errorCallback)
```

### 参数

`successCallback`

在目录中的内容被成功检索时调用的回调函数。该函数接收一个输入参数——文件系统条目对象的数组，其中的每一个对象都基于 `FileSystemEntry` (en-US)。通常，它们要么是代表标准文件的 `FileSystemFileEntry` 对象，要么是代表目录的 `FileSystemDirectoryEntry` 对象。如果目录中没有剩余的文件，或是你已经调用过 `FileSystemDirectoryReader` (en-US) 的 `readEntries()` 方法，则数组为空。

`errorCallback` 可选

一个在目录读取发生错误时调用的回调函数。它接收一个输入参数——一个 `DOMException` 对象，用于描述发生的错误。

### 返回值

无（`undefined`）。

示例
--

参见 `DataTransferItem.webkitGetAsEntry()` 以获取使用此方法的示例代码。

规范
--

| Specification |
| --- |
| File and Directory Entries API # dom-filesystemdirectoryreader-readentries |

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

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

在 Chrome 77 上，`readEntries()` 只会返回前 100 个 `FileSystemEntry` 实例。为了获取所有的实例，请多次调用 `readEntries()`。

参见
--

* 文件与目录条目 API
* 文件与目录条目 API 简介
* `FileSystemDirectoryEntry`
* `FileSystem`
使用文档对象模型
========

*文档对象模型*（DOM）是一个用于操作 HTML 和 XML 文档（包括其他树状文档）的 DOM 树的 API。这个 API 是页面描述的根源，并作为 web 脚本的基础。

什么是内容树？
-------

**DOM 树**是一种树状结构，其节点代表 HTML 或 XML 文档内容。每一个 HTML 或 XML 文档都有其 DOM 树表示方法。例如，考虑如下文档：


```html
<html lang="en">
  <head>
    <title>My Document</title>
  </head>
  <body>
    <h1>Header</h1>
    <p>Paragraph</p>
  </body>
</html>
```


其 DOM 树类似于这样：

![DOM 是一种树状的文档表示，它有一个根和包含内容的节点元素](/zh-CN/docs/Web/API/Document_object_model/Using_the_Document_Object_Model/using_the_w3c_dom_level_1_core-doctree.jpg)

虽然上面的树与上面文档的 DOM 树相似，但并不完全相同，因为实际的 DOM 树保留了空白。

当 web 浏览器解析 HTML 文档时，它建立了一个 DOM 树，然后用它来显示文档。

文档 API 会做些什么？
-------------

文档 API，有时也称为 DOM API，允许你以任何你想要的方式修改 DOM 树。它使你能够从头开始创建任何 HTML 或 XML 文档，或者改变一个给定的 HTML 或 XML 文档的任何内容。网页作者可以使用 JavaScript 来编辑文档的 DOM，访问全局对象的 `document` 属性。这个 `document` 对象实现了 `Document` 接口。

一个简单的示例
-------

假设作者改变上面文档的头部内容，并且使用两个段落取代一个段落。实现代码如下：

### HTML


```html
<html lang="zh-CN">
  <head>
    <title>我的文档</title>
  </head>
  <body>
    <input type="button" value="改变这个文档。" onclick="change()" />
    <h2>头部</h2>
    <p>段落</p>
  </body>
</html>
```

### JavaScript


```js
function change() {
  // document.getElementsByTagName("h2") 返回文档中所有 <h2> 组成的 NodeList，第一项用数字 0 取到：
  const header = document.getElementsByTagName("h2").item(0);

  // header 的第一个子节点（firstChild）是一个文本节点
  header.firstChild.data = "一个动态文档";

  // 现在 header 的内容为“一个动态文档”

  // 访问第一个段落
  const para = document.getElementsByTagName("p").item(0);
  para.firstChild.data = "这是第一段。";

  // 创建一个用于引用第二段的文本节点
  const newText = document.createTextNode("这是第二段。");

  // 创建一个作为第二段的元素
  const newElement = document.createElement("p");

  // 将文本放入段落元素中
  newElement.appendChild(newText);

  // 通过向 body（para 的父节点）末尾添加的方式将段落元素放在文档的末尾
  para.parentNode.appendChild(newElement);
}
```

想学习更多？
------

现在你已经熟悉了 DOM 的基本概念，你可能想通过阅读如何用 JavaScript 和 DOM 接口遍历 HTML 表格来了解更多关于文档 API 的基本特性。

参见
--

* 文档对象模型（DOM）
使用选择器定位 DOM 元素
==============

Selectors API 提供了通过与一组选择器匹配来轻松快速地从 DOM 检索 `Element` 节点的方法。这比以前的技术要快得多，例如，过去的技术需要在 JavaScript 代码中使用循环来定位你需要查找的特定项目。

NodeSelector 接口
---------------

此规范向实现 `Document`、`DocumentFragment` 或 `Element` 接口的任何对象添加了两种新方法：

`querySelector()`

返回节点子树内与之相匹配的第一个 `Element` 节点。如果没有匹配的节点，则返回 `null`。

`querySelectorAll()`

返回一个包含节点子树内所有与之相匹配的 `Element` 节点的 `NodeList`，如果没有匹配的节点，则返回一个空的 `NodeList`。


**备注：** 由 `querySelectorAll()` 返回的 `NodeList` 不是动态实时的，这意味着在 DOM 中的更改不会在该列表中反映。这和其他 DOM 查询方法返回动态实时节点列表不一样。

你可以在 `Element.querySelector()` 和 `Element.querySelectorAll()` 方法的文档中寻找到更多示例和细节。

选择器
---

选择器方法接受若干选择器来决定应该返回什么元素或哪些元素。这包括选择器列表，所以你可以在一个查询中分组多个选择器。

为了保护用户的隐私，一些伪类不被支持或表现得不同。例如，`:visited` 将不返回任何匹配，`:link` 则被视为 `:any-link`。

只有元素可以被选择，故不支持伪类。

示例
--

要选择所有包含 `warning` 或 `note` 类的所有段落（`p`）元素，你可以这样做：


```js
const special = document.querySelectorAll("p.warning, p.note");
```


也可以通过 ID 来查询，例如：


```js
const el = document.querySelector("#main, #basic, #exclamation");
```


执行上述代码后，`el` 包含文档中的第一个元素，其 ID 是 `main`、`basic` 或 `exclamation` 之一。

`querySelector()` and `querySelectorAll()` 里可以使用任何 CSS 选择器。

参见
--

* 选择器规范
* CSS 选择器
* `Element.querySelector()`
* `Element.querySelectorAll()`
* `Document.querySelector()`
* `Document.querySelectorAll()`
如何创建一个 DOM 树
============

本页描述了如何使用 JavaScript 中的 DOM API 创建 XML 文档。

考虑如下 XML 文档：


```xml
<?xml version="1.0"?>
<people>
  <person first-name="eric" middle-initial="H" last-name="jung">
    <address street="321 south st" city="denver" state="co" country="usa"/>
    <address street="123 main st" city="arlington" state="ma" country="usa"/>
  </person>

  <person first-name="jed" last-name="brown">
    <address street="321 north st" city="atlanta" state="ga" country="usa"/>
    <address street="123 west st" city="seattle" state="wa" country="usa"/>
    <address street="321 south avenue" city="denver" state="co" country="usa"/>
  </person>
</people>
```


你可以通过 DOM API 创建该文档的内存表示：


```js
const doc = document.implementation.createDocument("", "", null);
const peopleElem = doc.createElement("people");

const personElem1 = doc.createElement("person");
personElem1.setAttribute("first-name", "eric");
personElem1.setAttribute("middle-initial", "h");
personElem1.setAttribute("last-name", "jung");

const addressElem1 = doc.createElement("address");
addressElem1.setAttribute("street", "321 south st");
addressElem1.setAttribute("city", "denver");
addressElem1.setAttribute("state", "co");
addressElem1.setAttribute("country", "usa");
personElem1.appendChild(addressElem1);

const addressElem2 = doc.createElement("address");
addressElem2.setAttribute("street", "123 main st");
addressElem2.setAttribute("city", "arlington");
addressElem2.setAttribute("state", "ma");
addressElem2.setAttribute("country", "usa");
personElem1.appendChild(addressElem2);

const personElem2 = doc.createElement("person");
personElem2.setAttribute("first-name", "jed");
personElem2.setAttribute("last-name", "brown");

const addressElem3 = doc.createElement("address");
addressElem3.setAttribute("street", "321 north st");
addressElem3.setAttribute("city", "atlanta");
addressElem3.setAttribute("state", "ga");
addressElem3.setAttribute("country", "usa");
personElem2.appendChild(addressElem3);

const addressElem4 = doc.createElement("address");
addressElem4.setAttribute("street", "123 west st");
addressElem4.setAttribute("city", "seattle");
addressElem4.setAttribute("state", "wa");
addressElem4.setAttribute("country", "usa");
personElem2.appendChild(addressElem4);

const addressElem5 = doc.createElement("address");
addressElem5.setAttribute("street", "321 south avenue");
addressElem5.setAttribute("city", "denver");
addressElem5.setAttribute("state", "co");
addressElem5.setAttribute("country", "usa");
personElem2.appendChild(addressElem5);

peopleElem.appendChild(personElem1);
peopleElem.appendChild(personElem2);
doc.appendChild(peopleElem);
```


DOM 树可以：

* 使用 XPath 表达式查询
* 使用 XMLSerializer 转换为字符串
* 使用 `XMLHttpRequest` 发布到 web 服务器上
* 使用 XSLT 或 XLink (en-US) 转换
参见
--

* XML
* XPath
* 解析和序列化 XML
* XMLHttpRequest
自定义时间测量 API
===========

\*\*`User Timing`\*\*接口允许开发者在浏览器性能时间线中创建针对特定应用的 `时间戳`。有两种自定义时间测量事件类型："`mark`" `事件类型`和"`measure`" `事件类型`。

`mark` 事件可以指定任意的名字并且可以在放在应用的任何位置，`measure` 事件也可以指定为任意的名字，但是需要放在两个 mark 之间，所以它实际上是两个 mark 的中间点。

此文档提供了对 `mark` 和 `measure` `性能事件类型`的概览，包括四个拓展了 `Performance` 接口的 `User Timing` 方法。

性能`标记`
------

性能 **`标记`** 是一个由应用创建并指定名称的`性能条目`。这个标记是浏览器性能时间线上的一个`时间戳`。

### 创建一个性能`标记`

`performance.mark()`方法被用来创建一个性能标记。这个方法需要一个参数，标记的名称（例如`performance.mark("mark-1")`）。

`标记的``性能入口`包含以下属性值：

* `entryType` - 设置为"`mark`".
* `name` - 设置为创建该标记时"`name`"参数传入的值
* `startTime` (en-US) - 设置为`标记`被取消时的`时间戳`。
* `duration` (en-US) - 设置为"`0`"（一个没有时间间隔的标记）
### 检索一个性能`标记`

`Performance`接口有三个方法可以用来检索标记：

`performance.getEntries()`

返回性能时间线上的所有`性能条目`。通过筛选`entryType`属性为"`mark`"的条目来获取所有`标记`条目。

`performance.getEntriesByType(entryType)` (en-US)

返回性能事件线上具有指定`entryType`的`性能条目`，通过将`entryType`设置为"`mark`"来获取所有标记条目。

`performance.getEntriesByName(name, entryType)`

返回性能时间线上具有指定`name`和`entryType`的`性能条目` 。将`entryType`设置为"`mark`"来获得所有的标记条目（通过指定`name`来检索更具体的条目)。

### 移除性能`标记`

想要从性能事件线上移除一个特定标记，调用`performance.clearMarks(name)`，`name`是想要移除的标记的名称。如果这个方法被调用时没有传入任何参数，那么性能时间线上所有标记类型的条目都会被移除。

性能`测量`
------

\*\*`measure`\*\*事件同样由程序指定名称，但是它被放在两个标记之间因此实际上是两个标记间的中间点。

### 创建一个性能`测量`

`测量`通过调用`performance.measure(measureName, startMarkName, endMarkName)`来创建，`measureName`指定了该测量的名称，`startMarkName`和`endMarkName`分别指定了性能时间线上该测量前后的两个标记的名称。

`测量``性能条目`包含以下属性值：

* `entryType` - 设置为"`measure`".
* `name` - 设置为测量被创建时"`name`"参数给定的值
* `startTime` (en-US) - 设置为`measure()`被调用时的 `时间戳`。
* `duration` (en-US) - 设置为该测量间隔`DOMHighResTimeStamp`（即结束标记时间戳减去开始标记时间戳的差值)。
### 检索性能`测量`

`Performance`接口有三个方法可以检索一个测量：

`performance.getEntries()`

返回性能时间线上所有的`性能条目`。通过筛选`entryType`属性为"`measure`"的条目来获取所有`测量`条目。

`performance.getEntriesByType(entryType)` (en-US)

返回性能事件线上指定`entryType`的`性能条目`，通过将`entryType`设置为"`measure`"来获取所有的测量条目。

`performance.getEntriesByName(name, entryType)`

返回性能时间线上具有指定 `name`和`entryType`的`性能项目`，将`entryType`设置为"`measure`"来获取所有测量条目（通过指定`name`参数来检索更具体的条目)。

### 移除性能`测量`

想要从性能时间线上移除一个测量，调用`performance.clearMeasures(name)`，`name` 是要移除的测量的名称。如果该方法被调用时没有传入任何参数，那么性能时间线上所有的测量都会被移除。

互操作性
----

如`Performance`接口的浏览器兼容性表所示，`User Timing` 方法被大多数桌面和移动浏览器（唯一的例外是桌面 Safari 和移动版 Safari，Safari Technology Preview 24 已经支持该方法)。

想要测试你的浏览器是否支持该 API，运行`perf-api-support`程序。

相关内容
----

* User Timing Standard; W3C Editor's Draft
* CanIUse data
* A Primer for Web Performance Timing APIs; Xiaoqian Wu; W3C Editor's Draft
Navigation Timing API
=====================

**Navigation Timing API** 提供了可用于衡量一个网站性能的数据。与用于相同目的的其他基于 JavaScript 的机制不同，该 API 可以提供可以更有用和更准确的端到端延迟数据。

Concepts and usage
------------------

你可以使用 Navigation Timing API 在客户端收集性能数据，并用 `XMLHttpRequest` 或其他技术传送到服务端。同时，该 API 使你可以衡量之前难以获取的数据，如卸载前一个页面的时间，在域名解析上的时间，在执行 `load` 事件处理器上花费的总时间等。

Interfaces
----------

`Performance`
返回一个 Performance 对象。该对象由 High Resolution Time API 定义，Navigation Timing API 在此基础上增加了两个属性：`timing` 和 `navigation`

`PerformanceNavigationTiming`
提供了方法和属性来存取关于游览器文档 navigation 事件的相关数据。如文档实际加载/卸载的时间。

已弃用
 `PerformanceTiming`
曾被用来获取 `timing` 的值，用来衡量页面性能。

已弃用
 `PerformanceNavigation`
曾被用来获取 `navigation` 的值，用来描述加载相关的操作。

以下示例显示了如何测量感知加载时间：
```

function onLoad() {
  var now = new Date().getTime();
  var page_load_time = now - performance.timing.navigationStart;
  console.log("User-perceived page loading time: " + page_load_time);
}
```


还有很多以毫秒为单位呈现的测量事件，你可以通过 `PerformanceTiming` 接口得到它们。按照事件发生的先后顺序，这些事件的列表如下：

* navigationStart
* unloadEventStart
* unloadEventEnd
* redirectStart
* redirectEnd
* fetchStart
* domainLookupStart
* domainLookupEnd
* connectStart
* connectEnd
* secureConnectionStart
* requestStart
* responseStart
* responseEnd
* domLoading
* domInteractive
* domContentLoadedEventStart
* domContentLoadedEventEnd
* domComplete
* loadEventStart
* loadEventEnd

`window.performance.navigation` 对象存储了两个属性，它们表示触发页面加载的原因。这些原因可能是页面重定向、前进后退按钮或者普通的 `URL` 加载。

window.performance.navigation.type:

| Constant | Value | Description |
| --- | --- | --- |
| `TYPE_NAVIGATE` | 0 | 导航开始于点击链接、或者在用户代理中输入 URL、或者表单提交、或者通过除下表中 TYPE\_RELOAD 和 TYPE\_BACK\_FORWARD 的脚本初始化操作。 |
| `TYPE_RELOAD` | 1 | 通过刷新操作或者 location.reload() 方法导航。 |
| `TYPE_BACK_FORWARD` | 2 | 通过历史遍历操作导航。 |
| `TYPE_UNDEFINED` | 255 | 其他非以上类型的导航。 |

`window.performance.navigation.redirectCount` 表示到达最终页面前，重定向的次数（如果有的话）。

Navigation Timing API 可以用于收集客户端性能数据，然后通过 XHR 发送给服务端。还可以计算那些其他方法难以计算的数据，如卸载 (unload) 上一个页面的时间、域名查找时间、window.onload 的总时间等等。

示例
--

计算页面加载所需的总时长：
```

var perfData = window.performance.timing;
var pageLoadTime = perfData.loadEventEnd - perfData.navigationStart;
```


计算请求返回时长：
```

var connectTime = perfData.responseEnd - perfData.requestStart;
```