Element.tagName - Web API 接口参考

Element.tagName
===============

概述
--

返回当前元素的标签名

语法
--
```

elementName = element.tagName
```

* `elementName` 是一个字符串，包含了 element 元素的标签名。
备注
--

在 XML (或者其他基于 XML 的语言，比如 XHTML,xul) 文档中，`tagName 的值会`保留原始的大小写。在 HTML 文档中，`tagName`会返回其大写形式。对于元素节点来说，`tagName 属性`的值和nodeName属性的值是相同的。

例子
--

假设给定下面的源码
```

<span id="born">When I was born...</span>
```

然后运行下面的脚本
```

var span = document.getElementById("born");
alert(span.tagName);
```

在 XHTML 中 (或者其他的 XML 格式文件中), 会弹出小写的"span".而在 HTML 中，会弹出大写的"SPAN".

规范
--

* DOM Level 2 Core: tagName
* HTML 5: APIs in HTML documents


Element.before() - Web API 接口参考

Element.before()
================

**`ChildNode.before`** 方法可以在 `ChildNode` 这个节点的父节点中插入一系列的 `Node` 或者字符串对象，位置就是在 `ChildNode` 节点的前面，字符串对象其实和 `Text` (en-US) 节点一样的方式来完成插入的。

语法
--

```js
before(param1)
before(param1, param2)
before(param1, param2, /\* …, \*/ paramN)
```

### 参数

`param1`、…、`paramN`

一系列的 `Node` 或者字符串对象。

### 异常

`HierarchyRequestError` `DOMException`

无法在层次结构中的指定节点处插入节点时抛出。

示例
--

### 插入元素节点

```js
let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);
let span = document.createElement("span");

p.before(span);

console.log(container.outerHTML);
// "<div><span></span><p></p></div>"
```

### 插入文本节点

```js
let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);

p.before("Text");

console.log(container.outerHTML);
// "<div>Text<p></p></div>"
```

### 同时插入元素和文本

```js
let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);
let span = document.createElement("span");

p.before(span, "Text");

console.log(container.outerHTML);
// "<div><span></span>Text<p></p></div>"
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-before① |

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

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

参见
--

* `Element.after()`
* `Element.append()`
* `Node.appendChild()`
* `Node.insertBefore()`
* `Element.insertAdjacentElement()`
* `NodeList`


focusout - Web API 接口参考

focusout
========

当元素即将失去焦点时，focusout 事件被触发。focusout 事件和 blur 事件之间的主要区别在于后者不会冒泡。

基本信息
----

Specification

DOM L3

Interface
`FocusEvent`
Bubbles

Yes

Cancelable

No

Target

Element

Default Action

None.

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | Event target losing focus. |
| `type` 只读  | `DOMString` | The type of event. |
| `bubbles` 只读  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` 只读  | `Boolean` | Whether the event is cancellable or not. |
| `relatedTarget` 只读  | `EventTarget` (DOM element) | Event target receiving focus. |

规范
--

| Specification |
| --- |
| UI Events # event-type-focusout |

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

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

相关事件
----

* `focus`
* `blur`
* `focusin` (en-US)
* `focusout`


Element.localName - Web API 接口参考

Element.localName
=================

**`Element.localName`** 只读属性，返回本地名称的。

**备注：** 在 DOM4 之前这个 API 定义在`Node`接口。

语法
--
```

name = element.localName
```

### 返回值

`DOMString` 返回元素限定名的本地部分。

示例
--

(必须配合 XML 文档类型，如 `text/xml` 或 `application/xhtml+xml`.)

```xml
<html xmlns="http://www.w3.org/1999/xhtml"
 xmlns:svg="http://www.w3.org/2000/svg">
<head>
  <script type="application/javascript"><![CDATA[
 function test() {
 var text = document.getElementById('text');
 var circle = document.getElementById('circle');

 text.value = "<svg:circle> has:\n" +
 "localName = '" + circle.localName + "'\n" +
 "namespaceURI = '" + circle.namespaceURI + "'";
 }
 ]]></script>
</head>
<body onload="test()">
  <svg:svg version="1.1"
 width="100px" height="100px"
 viewBox="0 0 100 100">
    <svg:circle cx="50" cy="50" r="30" style="fill:#aaa" id="circle"/>
  </svg:svg>
  <textarea id="text" rows="4" cols="55"/>
</body>
</html>
```

说明
--

节点的本地名称是节点限定名的一部分出现在冒号之后。限定名通常当作特定 XML 文档命名空间的一部分。例如在限定名 `ecomm:partners` 中 `partners` 是本地名，`ecomm` 是前缀。

```xml
<ecomm:business id="soda\_shop" type="brick\_n\_mortar" xmlns:ecomm="http://example.com/ecomm">
  <ecomm:partners>
    <ecomm:partner id="1001">Tony's Syrup Warehouse
    </ecomm:partner>
  </ecomm:partner>
</ecomm:business>
```

**备注：** 在 Gecko 1.9.2 之前，此属性返回 HTML DOM 的 HTML 元素本地名称的大写版本 (而不是 XML DOM 的 HTML 元素). 在最后一个版本，符合 HTML5 规范下，当 HTML DOM 的 HTML 或 XML DOMs 的 XHTML 的小写元素时此属性返回内部 DOM storage。`tagName` 属性仍然返回 HTML DOM 的 HTML 元素本地名称的大写版本。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-localname① |

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

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

参见
--

* `Element.namespaceURI`
* `Element.prefix`
* `Attr.localName`
* `Node.localName` (en-US)


Element.scrollBy() - Web API 接口参考

Element.scrollBy()
==================

**`scrollBy()`** 方法是使得元素滚动一段特定距离的 `Element` 接口。

Syntax
------
```

element.scrollBy(x-coord, y-coord);
element.scrollBy(options)
```

### Parameters

* `x-coord` 是元素要在横轴上滚动的距离。
* `y-coord` 是元素要在纵轴上滚动的距离。

- or -

* `options` 是一个 `ScrollToOptions` 字典。
例子
--

```js
// 让元素滚动
element.scrollBy(300, 300);
```

使用 `options`:

```js
element.scrollBy({
  top: 100,
  left: 100,
  behavior: "smooth",
});
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-element-scrollby |

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

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


Element.after() - Web API 接口参考

Element.after()
===============

**`Element.after()`** 方法会在其父节点的子节点列表中插入一些 `Node` 或 `DOMString` 对象。插入位置为该节点之后。`DOMString` 对象会被以 `Text` (en-US) 的形式插入。

语法
--

```js
after(node1)
after(node1, node2)
after(node1, node2, /\* … ,\*/ nodeN)
```

### 参数

`node1`, …, `nodeN`

一组准备插入的 `Node` 或字符串。

### 异常

* `HierarchyRequestError`: 在某些不正确的层级结构进行了插入操作。
示例
--

### 插入元素

```js
let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);
let span = document.createElement("span");

p.after(span);

console.log(container.outerHTML);
// "<div><p></p><span></span></div>"
```

### 插入文本

```js
let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);

p.after("Text");

console.log(container.outerHTML);
// "<div><p></p>Text</div>"
```

### 同时插入元素和文本

```js
let container = document.createElement("div");
let p = document.createElement("p");
container.appendChild(p);
let span = document.createElement("span");

p.after(span, "Text");

console.log(container.outerHTML);
// "<div><p></p><span></span>Text</div>"
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-after① |

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

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

参见
--

* `Element.before()`
* `Element.append()`
* `Node.appendChild()`
* `Element.insertAdjacentElement()`
* `NodeList`


compositionstart - Web API 接口参考

compositionstart
================

文本合成系统如 input method editor（即输入法编辑器）开始新的输入合成时会触发 **`compositionstart`** 事件。

例如，当用户使用拼音输入法开始输入汉字时，这个事件就会被触发。

|  |  |
| --- | --- |
| **Bubbles** | Yes |
| **Cancelable** | Yes |
| **Interface** | `CompositionEvent` |
| **Event handler property** |

|  |
| --- |
| None |

 |

示例
--

```js
const inputElement = document.querySelector('input[type="text"]');

inputElement.addEventListener("compositionstart", (event) => {
  console.log(`generated characters were: ${event.data}`);
});
```

### 动态演示

#### HTML

```html
<div class="control">
  <label for="name"
 >On macOS, click in the textbox below,<br />
    then type <kbd>option</kbd> + <kbd>`</kbd>, then <kbd>a</kbd>:</label
 >
  <input type="text" id="example" name="example" />
</div>

<div class="event-log">
  <label>Event log:</label>
  <textarea readonly class="event-log-contents" rows="8" cols="25"></textarea>
  <button class="clear-log">Clear</button>
</div>
```

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

.control {
  grid-area: control;
}

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

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

label,
button {
  display: block;
}

input[type="text"] {
  margin: 0.5rem 0;
}

kbd {
  border-radius: 3px;
  padding: 1px 2px 0;
  border: 1px solid black;
}
```

#### JS

```js
const inputElement = document.querySelector('input[type="text"]');
const log = document.querySelector(".event-log-contents");
const clearLog = document.querySelector(".clear-log");

clearLog.addEventListener("click", () => {
  log.textContent = "";
});

function handleEvent(event) {
  log.textContent = log.textContent + `${event.type}: ${event.data}\n`;
}

inputElement.addEventListener("compositionstart", handleEvent);
inputElement.addEventListener("compositionupdate", handleEvent);
inputElement.addEventListener("compositionend", handleEvent);
```

#### 结果

规范
--

| Specification |
| --- |
| UI Events # event-type-compositionstart |

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

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

参见
--

* 相关事件：`compositionend`, `compositionupdate`.


Element：gotpointercapture 事件 - Web API 接口参考

Element：gotpointercapture 事件
============================

**`gotpointercapture`** 事件是 GlobalEventHandlers 的属性，这个事件返回 gotpointercapture 类型的事件操作。

语法
--
```

window.ongotpointercapture = functionReference
```

示例
--

```js
<html>
<script>
function overHandler(ev) {
 // Determine the target event's gotpointercapture handler
 var gotCaptureHandler = ev.target.ongotpointercapture;
}
function init() {
 var el=document.getElementById("target");
 el.ongotpointercapture = overHandler;
}
</script>
<body onload="init();">
<div id="target"> Touch me ... </div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| Pointer Events # the-gotpointercapture-event |
| Pointer Events # dom-globaleventhandlers-ongotpointercapture |

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

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

参见
--

* 相关事件
    + `lostpointercapture`
    + `pointerover`
    + `pointerenter`
    + `pointerdown`
    + `pointermove`
    + `pointerup`
    + `pointercancel`
    + `pointerout`
    + `pointerleave`


Element.children - Web API 接口参考

Element.children
================

**`Element.children`** 是一个只读属性，返回 一个 Node 的子`elements` ，是一个动态更新的 `HTMLCollection`。

语法
--
```

var children = node.children;
```

```
var elList = elementNodeReference.children;
```

备注
--

`children` 属性为只读属性，对象类型为 `HTMLCollection`，你可以使用 `elementNodeReference.children[1].nodeName` 来获取某个子元素的标签名称。

例子
--

```js
// parg 是一个指向<p>元素的对象引用
if (parg.childElementCount) {
  // 检查这个<p>元素是否有子元素
  // 译者注:childElementCount 有兼容性问题
  var children = parg.children;
  for (var i = 0; i < children.length; i++) {
    // 通过 children[i] 来获取每个子元素
    // 注意:List 是一个 live 的 HTMLCollection 对象，在这里添加或删除 parg 的子元素节点，都会立即改变 List 的值。
  }
}
```

规范
--

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

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

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

参见
--

* The `Element` and `ChildNode` pure interfaces.
* Object types implementing this pure interface: `Document`, `Element`, and `DocumentFragment`.


Element：pointerover 事件 - Web API 接口参考

Element：pointerover 事件
======================

The `pointerover` event is fired when a pointing device is moved into an element's hit test boundaries.

语法
--
```

var overHandler = targetElement.onpointerover;
```

### 返回值

`overHandler`

pointerover 事件处理器返回目标元素的`overHandler.`

案例
--

这里使用两种方式展示了如何去使用 *onpointerover* 去设置一个元素的 *pointerover* 事件处理器

```js
<html>
<script>
function overHandler(ev) {
 // Process the pointerover event
}
function init() {
 var el=document.getElementById("target1");
 el.onpointerover = overHandler;
}
</script>
<body onload="init();">
<div id="target1"> Touch me ... </div>
<div id="target2" onpointerover="overHandler(event)"> Touch me ... </div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| Pointer Events # the-pointerover-event |
| Pointer Events # dom-globaleventhandlers-onpointerover |

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

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

参见
--

* 相关事件
    + `gotpointercapture`
    + `lostpointercapture`
    + `pointerenter`
    + `pointerdown`
    + `pointermove`
    + `pointerup`
    + `pointercancel`
    + `pointerout`
    + `pointerleave`


Element.onfullscreenchange - Web API 接口参考

Element.onfullscreenchange
==========================

元素接口的 **`onfullscreenchange`** 属性是在元素过渡到或过渡到全屏模式时触发的全屏更改事件的事件处理程序。

语法
--
```

targetDocument.onfullscreenchange = fullscreenChangeHandler;
```

### 值

当事件处理程序处于 `fullscreenchange` 模式的时候，表明游戏元素被改变了或者是退出了全屏模式

Example
-------

本示例建立一个`fullscreenchange` 处理程序，`handleFullscreenChange ()`。此函数通过检查 `event.target` 的值来确定调用它的元素，然后将文档的`fullscreenElement` 值与元素进行比较，以查看它们是否为同一节点。

这给了我们一个值，即 `isFullscreen`, 我们将其传递到一个名为 `adjustMyControls()` 的函数，我们想象它是一个函数，可以对应用的用户界面进行调整，以便在全屏模式下而不是在窗口。

```js
function toggleFullscreen() {
  let elem = document.querySelector("video");

  elem.onfullscreenchange = handleFullscreenChange;
  if (!document.fullscreenElement) {
    elem
      .requestFullscreen()
      .then({})
      .catch((err) => {
        alert(
          `Error attempting to enable full-screen mode: ${err.message} (${err.name})`,
        );
      });
  } else {
    document.exitFullscreen();
  }
}

function handleFullscreenChange(event) {
  let elem = event.target;
  let isFullscreen = document.fullscreenElement === elem;

  adjustMyControls(isFullscreen);
}
```

规范
--

| Specification |
| --- |
| Fullscreen API Standard # handler-document-onfullscreenchange |

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

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

参见
--

* Fullscreen API
* Guide to the Fullscreen API
* `fullscreenchange`
* `Element.onfullscreenerror`
* The `Document` equivalent: `onfullscreenchange`.


GlobalEventHandlers.ontransitionend - Web API 接口参考

GlobalEventHandlers.ontransitionend
===================================

`GlobalEventHandlers` 混入对象的 **`ontransitionend`** 属性是一个处理 `transitionend` 事件的 事件处理函数。

`transitionend` 事件的事件处理函数，在某个 CSS transition 完成时触发。

**备注：** 如果在 transition 完成前，该 transition 已从目标节点上移除，那么 `transitionend` 将不会被触发。一种可能的情况是修改了目标节点的 `transition-property` 属性，另一种可能的情况是 `display` 属性被设为 `"none"`。

语法
--

```js
var transitionEndHandler = target.ontransitionend;

target.ontransitionend = Function
```

### 值

一个 `Global_Objects/Function` 会在 `transitionend` 事件发生时被触发，表示目标节点的 CSS transition 已经完成。目标节点可能是一个 HTML 元素 (`HTMLElement`)，document (`Document`)，或者 window (`Window`)。该函数接受一个参数：一个描述该事件的 `TransitionEvent` 对象；其 `TransitionEvent.elapsedTime` (en-US) 属性值与 `transition-duration` 的值一致。

**备注：** `elapsedTime` 并不包括 transition 效果开始前的时间，也就是说，`transition-delay` 属性并不会影响 `elapsedTime` 的值，其在延迟结束、动画开始之时，值为零。

示例
--

本例中，我们使用了 `transitionrun` (en-US) 和 `transitionend` 事件来监测 transition 的开始和结束，从而在 transition 的过程中更新文本。这也可以被用来触发动画或者其他效果来实现连锁反应。

### HTML

这里简单地创建了一个 `<div>`，我们将使用 CSS 来改变其大小和颜色。

```html
<div class="box"></div>
```

### CSS

以下为 CSS 样式，并添加了 transition 属性。当鼠标悬浮时，盒子大小和颜色会发生变化，而且还会转动。

```css
.box {
  margin-left: 70px;
  margin-top: 30px;
  border-style: solid;
  border-width: 1px;
  display: block;
  width: 100px;
  height: 100px;
  background-color: #0000ff;
  color: #ffffff;
  padding: 20px;
  font:
    bold 1.6em "Helvetica",
    "Arial",
    sans-serif;
  transition:
    width 2s,
    height 2s,
    background-color 2s,
    transform 2s,
    color 2s;
}

.box:hover {
  background-color: #ffcccc;
  color: #000000;
  width: 200px;
  height: 200px;
  transform: rotate(180deg);
}
```

### JavaScript

接下来，我们需要事件处理函数以在 transition 发生和结束时修改文本内容。

```js
let box = document.querySelector(".box");
box.ontransitionrun = function (event) {
  box.textContent = "Zooming...";
};
box.ontransitionend = function (event) {
  box.textContent = "Done!";
};
```

### 效果

最后的效果如下：

注意观察当鼠标悬浮在元素上以及移出时发生的变化。

规范
--

| Specification |
| --- |
| CSS Transitions # transitionend |

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

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

参见
--

* `TransitionEvent` 接口
* CSS 属性：`transition`、`transition-delay`、`transition-duration`、`transition-property`、`transition-timing-function`
* 相关事件：`transitionrun` (en-US)、`transitionstart`、`transitioncancel`
* 以 `Document` 为目标的该事件：`transitionend` (en-US)
* 以 `Window` 为目标的该事件：`transitionend` (en-US)


Element.setAttributeNS() - Web API 接口参考

Element.setAttributeNS()
========================

`setAttributeNS` 添加一个新属性或更改具有给定命名空间和名称的一个属性的值。

句法
--
```

element.setAttributeNS(namespace,name,value)
```

* `namespace` 是指定属性的命名空间的一个字符串。
* `name` 是标识要设置的属性的一个字符串。
* `value` 是新属性的所需字符串值。
范例
--
```

let d = document.getElementById("d1");
d.setAttributeNS("http://www.mozilla.org/ns/specialspace", "align", "center");
```

注释
--

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

规范
--

DOM Level 2 Core: setAttributeNS


GlobalEventHandlers.onanimationcancel - Web API 接口参考

GlobalEventHandlers.onanimationcancel
=====================================

animationcancel 是一个事件处理操作，这个事件在CSS Animation属性意外中断时派发出来 (换句话说，任何时候 animation 停止运行不会发出一个 animationend 事件，比如，当 animation-name 改变以后，animation 就会被移除，或者动画节点隐藏—当前元素或者任何包含的节点隐藏)—使用 css 时。

语法
--
```

var animCancelHandler = target.onanimationcancel;

target.onanimationcancel = `Function`
```

示例
--

### HTML

```html
<div class="main">
  <div id="box">
    <div id="text" onanimationcancel="handleCancelEvent">Box</div>
  </div>
</div>

<div class="button" id="toggleBox">Hide the Box</div>

<pre id="log"></pre>
```

### CSS
```

:root {
  --boxwidth: 50px;
}

.main {
  width: 300px;
  height: 300px;
  border: 1px solid black;
}

.button {
  cursor: pointer;
  width: 300px;
  border: 1px solid black;
  font-size: 16px;
  text-align: center;
  margin-top: 0;
  padding-top: 2px;
  padding-bottom: 4px;
  color: white;
  background-color: darkgreen;
  font:
    14px "Open Sans",
    "Arial",
    sans-serif;
}

#text {
  width: 46px;
  padding: 10px;
  position: relative;
  text-align: center;
  align-self: center;
  color: white;
  font:
    bold 1.4em "Lucida Grande",
    "Open Sans",
    sans-serif;
}
```

Leaving out some bits of the CSS that don't matter for the discussion here, let's take a look at the styles for the box that we're animating. First is the box itself, with all its properties, including `animation`, defined. We go ahead and describe the animation in-place here because the animation is intended to begin as soon as the page loads, rather than based on an event.

```css
#box {
  width: var(--boxwidth);
  height: var(--boxwidth);
  left: 0;
  top: 0;
  border: 1px solid #7788ff;
  margin: 0;
  position: relative;
  background-color: #2233ff;
  display: flex;
  justify-content: center;
  animation: 5s ease-in-out 0s infinite alternate both slideBox;
}
```

The animation's keyframes are described next, plotting a course from the top-left corner of the content box to the bottom-right corner.

```css
@keyframes slideBox {
  from {
    left: 0;
    top: 0;
  }
  to {
    left: calc(100% - var(--boxwidth));
    top: calc(100% - var(--boxwidth));
  }
}
```

Since the animation is described as taking place an infinite number of times, alternating direction each time, the box will glide back and forth between the two corners until stopped or the page is closed.

### JavaScript

Before we get to the animation code, we define a function which logs information to a box on the user's screen. We'll use this to show information about the events we receive. Note the use of `AnimationEvent.animationName` (en-US) and `AnimationEvent.elapsedTime` (en-US) to get information about the event which occurred.

```js
function log(msg, event) {
  let logBox = document.getElementById("log");

  logBox.innerHTML += msg;

  if (event) {
    logBox.innerHTML +=
      " <code>" +
      event.animationName +
      "</code> at time " +
      event.elapsedTime.toFixed(2) +
      " seconds.";
  }

  logBox.innerHTML += "\n";
}
```

Then we set up the `handleCancelEvent()` function, which is called in response to the `animationcancel` event, as set up in the HTML above. All we do here is log information to the console, but you might find other use cases, such as starting a new animation or effect, or terminating some dependent operation.

```js
function handleCancelEvent(event) {
  log("Animation canceled", event);
}
```

Then we add a method to handle toggle `display` between `"flex"` and `"none"` and establish it as the handler for a `click` event on the "Hide/Show" the Box button:

```js
function toggleBox() {
  if (box.style.display == "none") {
    box.style.display = "flex";
    document.getElementById("toggleBox").innerHTML = "Hide the box";
  } else {
    box.style.display = "none";
    document.getElementById("toggleBox").innerHTML = "Show the box";
  }
}
```

Toggling the box to `display: none` has the effect of aborting its animation. In browsers that support `animationcancel`, the event is fired and this handler is called.

**备注：** At this time, no major browser supports `animationcancel`.

### 结果

Assembled together, you get this:

If your browser supports `animationcancel`, hiding the box using the button will cause a message to be displayed about the event.

规范
--

| Specification |
| --- |
| CSS Animations Level 1 # eventdef-globaleventhandlers-animationcancel |

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

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

参见
--

* `AnimationEvent` (en-US)


Element.getElementsByTagNameNS() - Web API 接口参考

Element.getElementsByTagNameNS()
================================

**`Element.getElementsByTagNameNS()`** 方法返回在指定命名空间内带有指定名称的动态 HTML 元素集合（而不是快照），搜索范围限定于指定元素的后代，类似于`Document.getElementsByTagNameNS`。

语法
--
```

elements = element.getElementsByTagNameNS(namespaceURI, localName)
```

* `elements` 是匹配元素的动态 HTML 元素集合`HTMLCollection`，其顺序为遍历树时匹配元素出现的先后。
* `element` 是查找的起始结点，查找范围为该元素的后代，并且不包含该元素自身。
* `namespaceURI` 是所要查询的元素的命名空间 URL (参考 `Node.namespaceURI` (en-US)). 举个例子，如果你想查找的是 XHTML 元素，你应该使用 XHTML 的命名空间 URL，`http://www.w3.org/1999/xhtml`。
* `localName` 是所要查询的元素的名称。其中特殊字符 "\*" 代表所有元素 (参考 `Node.localName` (en-US)).
示例
--

```js
// 检查一个 XHTML 文档中表格的单元格的对齐方式。
var table = document.getElementById("forecast-table");
var cells = table.getElementsByTagNameNS("http://www.w3.org/1999/xhtml", "td");

for (var i = 0; i < cells.length; i++) {
  var axis = cells[i].getAttribute("axis");
  if (axis == "year") {
    // grab the data
  }
}
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-element-getelementsbytagnamens |

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

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


element.insertAdjacentHTML - Web API 接口参考

element.insertAdjacentHTML
==========================

**`insertAdjacentHTML()`** 方法将指定的文本解析为 `Element` 元素，并将结果节点插入到 DOM 树中的指定位置。它不会重新解析它正在使用的元素，因此它不会破坏元素内的现有元素。这避免了额外的序列化步骤，使其比直接使用 innerHTML 操作更快。

语法
--
```

element.insertAdjacentHTML(position, text);
```

`position`

一个 `DOMString`，表示插入内容相对于元素的位置，并且必须是以下字符串之一：

* `'beforebegin'`：元素自身的前面。
* `'afterbegin'`：插入元素内部的第一个子节点之前。
* `'beforeend'`：插入元素内部的最后一个子节点之后。
* `'afterend'`：元素自身的后面。

`text`

是要被解析为 HTML 或 XML 元素，并插入到 DOM 树中的 `DOMString`。

### 位置名称的可视化

```html
<!-- beforebegin -->
<p>
  <!-- afterbegin -->
  foo
  <!-- beforeend -->
</p>
<!-- afterend -->
```

**备注：** beforebegin 和 afterend 位置，仅在节点在树中且节点具有一个 parent 元素时工作。

示例
--

```js
// 原为 <div id="one">one</div>
var d1 = document.getElementById("one");
d1.insertAdjacentHTML("afterend", '<div id="two">two</div>');

// 此时，新结构变成：
// <div id="one">one</div><div id="two">two</div>
```

注意
--

### 安全问题

使用 `insertAdjacentHTML` 插入用户输入的 HTML 内容的时候，需要转义之后才能使用。

如果只是为了插入文本内容（而不是 HTML 节点），不建议使用这个方法，建议使用`node.textContent` 或者 `node.insertAdjacentText()`。因为这样不需要经过 HTML 解释器的转换，性能会好一点。

规范
--

| Specification |
| --- |
| DOM Parsing and Serialization # dom-element-insertadjacenthtml |

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

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

参见
--

* 包括 Henri Sivonen 在内的某些 hacks.mozilla.org 客座文章 显示，`insertAdjacentHTML` 在某些情况下可以更快。
* `Element.insertAdjacentElement()`
* `Element.insertAdjacentText()`


元素：animationend 事件 - Web API 接口参考

元素：animationend 事件
==================

**`animationend`**（**动画结束**）事件在 CSS 动画完成时触发。如果在动画完成前中止了动画，例如将元素从 DOM 中移除，或将动画从元素上移除，`animationend` 事件不会触发。

语法
--

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

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

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

事件类型
----

`AnimationEvent` (en-US)。继承自 `Event`。

Event

AnimationEvent

(en-US)事件属性
----

*也从其父接口 `Event` 继承属性*。

`AnimationEvent.animationName` (en-US) 只读

一个字符串，包含了生成动画的 `animation-name` 的值。

`AnimationEvent.elapsedTime` (en-US) 只读

一个浮点数（`float`），表示动画运行的时间（以秒为单位）。此事件的这个属性并不包括动画暂停的时间。对于 `animationstart` 事件，`elapsedTime` 的值为 `0.0`（除非将 `animation-delay` 设置成了一个负值，在这种情况下，`elapsedTime` 为 `(-1 * delay)`）。

`AnimationEvent.pseudoElement` (en-US) 只读

一个字符串，以 `'::'` 开头，包含了动画运行时所在的伪元素的名称。如果动画不是在伪元素而是在元素上运行，则为空字符串：`''`。

示例
--

该实例获取一个正在绘制动画的元素，并监听 `animationend` 事件。

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

animated.addEventListener("animationend", () => {
  console.log("Animation ended");
});
```

同上，但使用 `onanimationend` 事件处理器属性：

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

animated.onanimationend = () => {
  console.log("Animation ended");
};
```

### 运行实例

#### HTML

```html
<div class="animation-example">
  <div class="container">
    <p class="animation">你选择了一个寒冷的夜晚到访我们的星球。</p>
  </div>
  <button class="activate" type="button">激活动画</button>
  <div class="event-log"></div>
</div>
```

#### CSS

```css
.container {
  height: 3rem;
}

.event-log {
  width: 25rem;
  height: 2rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
}

.animation.active {
  animation-duration: 2s;
  animation-name: slidein;
  animation-iteration-count: 2;
}

@keyframes slidein {
  from {
    margin-left: 100%;
    width: 300%;
  }

  to {
    margin-left: 0%;
    width: 100%;
  }
}
```

#### JavaScript

```js
const animation = document.querySelector("p.animation");
const animationEventLog = document.querySelector(
  ".animation-example>.event-log",
);
const applyAnimation = document.querySelector(
  ".animation-example>button.activate",
);
let iterationCount = 0;

animation.addEventListener("animationstart", () => {
  animationEventLog.textContent = `${animationEventLog.textContent}'动画开始' `;
});

animation.addEventListener("animationiteration", () => {
  iterationCount++;
  animationEventLog.textContent = `${animationEventLog.textContent}'动画迭代轮次：${iterationCount}' `;
});

animation.addEventListener("animationend", () => {
  animationEventLog.textContent = `${animationEventLog.textContent}'动画结束'`;
  animation.classList.remove("active");
  applyAnimation.textContent = "激活动画";
});

animation.addEventListener("animationcancel", () => {
  animationEventLog.textContent = `${animationEventLog.textContent}'动画已被取消'`;
});

applyAnimation.addEventListener("click", () => {
  animation.classList.toggle("active");
  animationEventLog.textContent = "";
  iterationCount = 0;
  const active = animation.classList.contains("active");
  applyAnimation.textContent = active ? "取消动画" : "激活动画";
});
```

#### 结果

规范
--

| Specification |
| --- |
| CSS Animations Level 1 # eventdef-globaleventhandlers-animationend |

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

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

参见
--

* CSS 动画
* 使用 CSS 动画
* `AnimationEvent` (en-US)
* 相关事件：`animationstart`, `animationcancel`, `animationiteration`
* 以 `Document` 为目标的此事件：`animationend` (en-US)
* 以 `Window` 为目标的此事件：`animationend` (en-US)


GlobalEventHandlers.onauxclick - Web API 接口参考

GlobalEventHandlers.onauxclick
==============================

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

**`auxclick`** 事件在输入设备的非主按钮（除主按钮——通常是左键外的任何按钮）在同一个 `Element` 上按下并释放时触发。

实现该属性的一个目标是，提高浏览器与按钮行为之间的兼容性 - 事件行为正在更新，以便 `click` 只触发主按钮点击（例如，鼠标左键）。然后开发人员可以使用 `auxclick` 事件来为非主按钮点击提供明确的行为。在此之前，`click` 通常会针对所有输入设备按钮点击，浏览器行为有些不一致。

语法
--
```

element.onauxclick = functionRef(e);
```

事件处理函数是一个 `MouseEvent` 对象。只有事件被触发的按钮不同，该事件和普通点击事件的行为是完全相同的。

示例
--

在这个例子中我们定义了两个事件处理函数：`onclick` 和 `onauxclick`。前者改变按钮背景的颜色，而后者改变按钮前景（文本）的颜色。你可以通过使用多按钮鼠标尝试演示来查看这两种功能 (see it live on GitHub; also see the source code)。

```js
var button = document.querySelector("button");
var html = document.querySelector("html");

function random(number) {
  return Math.floor(Math.random() \* number);
}

button.onclick = function () {
  var rndCol =
    "rgb(" + random(255) + "," + random(255) + "," + random(255) + ")";
  button.style.backgroundColor = rndCol;
};

button.onauxclick = function () {
  var rndCol =
    "rgb(" + random(255) + "," + random(255) + "," + random(255) + ")";
  button.style.color = rndCol;
};
```

**备注：** 如果你使用的是三键鼠标，你会注意到在单击任一非鼠标左键时该 `onauxclick` 处理程序会运行。

Notes
-----

当用户点击一个元素时，将引发该 `click` 事件。之后的 click 事件将发生在 `mousedown` 和 `mouseup` 事件之后。

每次只有一个 `click` 处理程序可以通过此属性分配给一个对象。你可能倾向于使用`EventTarget.addEventListener()` 方法，因为它更灵活并且是 DOM Events 规范的一部分。

规范
--

`onauxclick` 不是任何官方规范的一部分，它被定义在 auxclick Draft Community Group Report.

Browser Compatibility
---------------------

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


Element.namespaceURI - Web API 接口参考

Element.namespaceURI
====================

**`Element.namespaceURI`** 是一个只读属性，它返回元素的命名空间，若该元素不在命名空间中则返回`null` .

**备注：** 在 DOM4 之前，这个 API 在接口 `Node` 中定义 .

语法
--
```

namespace = element.namespaceURI
```

例子
--

在这段代码中，我们检查了元素的`localName`和`namespaceURI`。如果 `namespaceURI` 返回 XUL 命名空间， `localName` 返回"browser"，于是这个节点被理解为是一个 XUL `<browser/>`。

```js
if (
  element.localName == "browser" &&
  element.namespaceURI ==
    "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
) {
  // this is a XUL browser
}
```

注意
--

这不是一个计算值，它是基于范围内的名称空间声明检查的名称空间查找的结果。节点命名空间在节点创建时被冻结。

在 Firefox 3.5 以及之前的版本，HTML 文档中的 HTML 元素的名称空间 URI 为 `null`。在更早的版本中，符合 HTML5，它是`http://www.w3.org/1999/xhtml` 如 XHTML。

你可以使用 DOM Level 2 方法指定的`namespaceURI`创建一个元素 document.createElementNS。

DOM 本身不处理或执行名称空间验证。它由 DOM 应用程序完成，以执行任何必要的验证。注意，名称空间前缀一旦与某个特定元素相关联，就不能更改。

说明
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-namespaceuri① |

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

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

See also
--------

* `Element.localName`
* `Element.prefix`
* `Attr.namespaceURI`
* `Node.namespaceURI` (en-US)


Element.setAttributeNodeNS() - Web API 接口参考

Element.setAttributeNodeNS()
============================

`setAttributeNodeNS` 可以给一个元素添加一个新的命名空间的属性节点。

（如果对中文有疑惑，请直接阅读原文）

Syntax
------
```

replacedAttr = element.setAttributeNodeNS(attributeNode)
```

* `replacedAttr` 是被替换的节点，如果存在，由此函数返回。
* `attributeNode` 是一个属性节点。
Example
-------
```

// <div id="one" xmlns:myNS="http://www.mozilla.org/ns/specialspace"
            myNS:special-align="utterleft">one</div>
// <div id="two">two</div>

var myns = "http://www.mozilla.org/ns/specialspace";
var d1 = document.getElementById("one");
var d2 = document.getElementById("two");
var a = d1.getAttributeNodeNS(myns, "special-align");
d2.setAttributeNodeNS(a.cloneNode(true));
alert(d2.attributes[1].value) // returns: `utterleft'
```

Notes
-----

如果指定的属性在元素上存在，接着此属性被新的属性替换的话被替换的属性会被返回。

注意：如果你尝试设置的时候没有克隆那个节点，Mozia 会抛出一个 NS\_ERROR\_DOM\_INUSE\_ATTRIBUTE\_ERR："Attribute already in use" 错误，因为 DOM 需要克隆属性之后才能重复使用（不像其他节点一样可以被删除）。

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

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

DOM Level 2 Core: setAttributeNodeNS


Element.setAttribute() - Web API 接口参考

Element.setAttribute()
======================

设置指定元素上的某个属性值。如果属性已经存在，则更新该值；否则，使用指定的名称和值添加一个新的属性。

要获取某个属性当前的值，可使用 `getAttribute()`；要删除某个属性，可使用 `removeAttribute()`。

语法
--
```

element.setAttribute(name, value);
```

### 参数

`name`

表示属性名称的字符串。A `DOMString` specifying the name of the attribute whose value is to be set. The attribute name is automatically converted to all lower-case when `setAttribute()` is called on an HTML element in an HTML document.

`value`

属性的值/新值。A `DOMString` 包含了分配给这个属性的值。任何非字符串的值都会被自动转换为字符串。

当在 HTML 文档中的 HTML 元素上调用 `setAttribute()` 方法时，该方法会将其属性名称（attribute name）参数小写化。

如果指定的属性已经存在，则其值变为传递的值。如果不存在，则创建指定的属性。

尽管对于不存在的属性，`getAttribute()` (en-US) 返回 `null`，你还是应该使用 `removeAttribute()` 代替 `elt.setAttribute(attr, null)` 来删除属性。

布尔属性（原文是 Boolean attributes）只要出现在元素上就会被认为是 `true` ，无论它的值是什么; 一般来说，你应该将 `value` 设置为空字符串 (`""`) 。(一些人使用这个属性的名称作为值; 这不会出现什么问题，但这是不规范的). See the example below for a practical demonstration.

由于将指定的值转换为字符串，因此指定 null 不一定能达到你的期望。而不是删除属性或将其值设置为`null`，而是将属性的值设置为字符串“null”。如果要删除属性，请调用`removeAttribute()`。

### 返回值

`undefined`### 例外

`无效字符错误`

指定的属性名称包含一个或多个在属性名称中无效的字符。

示例
--

在下面的例子中，`setAttribute()` 被用于设置 `<button>` 上的属性。

### HTML

```html
<button>Hello World</button>
```

### JavaScript

```js
var b = document.querySelector("button");

b.setAttribute("name", "helloButton");
b.setAttribute("disabled", "");
```

这说明了两件事：

* 上面对 setAttribute() 的第一次调用显示了将 name 属性的值更改为“helloButton”。你可以使用浏览器的页面检查器（Chrome，Edge，Firefox，Safari）查看此内容。
* 要设置布尔属性的值（例如禁用），可以指定任何值。建议使用空字符串或属性名称。重要的是，如果根本不存在该属性，则不管其实际值如何，都将其值视为真实。该属性的缺失表示其值是 false。通过将 Disabled 属性的值设置为空字符串（“”），我们将 disable 设置为 true，这将导致按钮被禁用。

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

规范
--

* DOM Level 2 Core: setAttribute (introduced in DOM Level 1 Core)
* HTML5: APIs in HTML documents
浏览器兼容性
------

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

### Gecko 备注

使用 `setAttribute()` 修改某些属性值时，尤其是 XUL 中的 `value`，可能得不到期望结果。这是由于 `attribute` 指定的是默认值。要访问或修改当前值，应该使用 `property` 属性。例如，使用 `Element.value` 代替 `Element.setAttribute()`。


Element.removeAttributeNS() - Web API 接口参考

Element.removeAttributeNS()
===========================

`removeAttributeNS` 移除元素的指定属性

在 Firefox 3 及更高版本中，此方法会将 DOM 值重置为其默认值。

用法
--
```

element.removeAttributeNS(namespace,attrName);
```

* `namespace` 包含当前属性的 namespace 字符串
* `attrName` 当前移除的属性名字符串
例子
--
```

// <div id="div1" xmlns:special="http://www.mozilla.org/ns/specialspace"
//      special:specialAlign="utterleft" width="200px" />
d = document.getElementById("div1");
d.removeAttributeNS("http://www.mozilla.org/ns/specialspace", "specialAlign");
// now: <div id="div1" width="200px" />
```

Notes
-----

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

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

DOM Level 2 Core: removeAttributeNS


Element.prefix - Web API 接口参考

Element.prefix
==============

**`Element.prefix`** 只读属性返回指定元素的命名空间前缀，如果未指定前缀，则返回 null。

**备注：** 在 DOM4 之前，该 API 是在 `Node` interface 中定义的。

Syntax
------
```

string = element.prefix
```

Examples
--------

The following logs "x" to the console.

```xml
<x:div onclick="console.log(this.prefix)"/>
```

Notes
-----

This will only work when a namespace-aware parser is used, i.e. when a document is served with an XML MIME type. This will not work for HTML documents.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-prefix① |

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

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

See also
--------

* `Element.namespaceURI`
* `Element.localName`
* `Attr.prefix`
* `Node.prefix` (en-US)


Element.slot - Web API 接口参考

Element.slot
============

`Element`接口的 **`slot`** 属性会返回已插入元素所在的 Shadow DOM slot 的名称。

Slot 是存在于web component内部的占位符，用户可以通过 slot 属性在 web component 的内部插入自定义的标记文本。（详见 Using template and slot）

语法
--
```

var aString = element.slot
element.slot = aString
```

### 值

`DOMString`.

示例
--

在示例 simple-template example (在线查看) 中，我们创建了一个简单的自定义元素叫做 `<my-paragraph>` ，并为它添加了 shadow root，然后使用一个包含以 `my-text`为名称的 slot 的 template 来填充它。

当 `<my-paragraph>` 在文档中被使用时，slot 标签中的内容会被填充到拥有`slot="my-text"`属性的元素之中，我们称这种元素为 slotable element。（事实上可以看作是拥有 slot 属性的元素被填充到了 template 中有`<slot>`标签存在的地方）请看下面的示例：

```js
<my-paragraph>
  <span slot="my-text">Let's have some different text!</span>
</my-paragraph>
```

在 Javascript 代码中我们获取到上面代码中的 span 的引用，然后将对应的 `<slot>` 元素的引用的名称打印在控制台中。

```js
let slottedSpan = document.querySelector("my-paragraph span");
console.log(slottedSpan.slot); // logs 'my-text'
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-slot① |

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

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


Element.removeAttributeNode() - Web API 接口参考

Element.removeAttributeNode()
=============================

`removeAttributeNode` 从当前的 element(元素节点) 删除指定的属性

Syntax
------
```

removedAttr = element.removeAttributeNode(attributeNode)
```

* `attributeNode` 是需要被删除的 Attr 节点。
* `removedAttr` 是被删除了的 Attr 节点。
例如
--
```

// <div id="top" align="center" />
var d = document.getElementById("top");
// getAttributeNode 返回指定元素的指定属性，返回值是 Attr 节点类型
var d_align = d.getAttributeNode("align");
d.removeAttributeNode(d_align);
//  现在 align 被删除了：<div id="top" />
```

注意
--

如果删除有默认值的属性，相当于将属性值替换为默认值。属性只有在具有同样的命名空间、本地名称以及原始前缀时，才会在被删除的时候替换为默认值。

不像 setAttributeNode 和 setAttributeNodeNS 配对使用那样，需要知道要替换哪个现有属性。removeAttributeNode 没有那样的要求，也没有 removeAttributeNodeNS。removeAttributeNode 可以删除命名空间以及非命名空间的属性。

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

规范
--

DOM Level 2 Core: removeAttributeNode (DOM Level 1 Core 里面的介绍)


element.innerHTML - Web API 接口参考

element.innerHTML
=================

**`Element.innerHTML`** 属性设置或获取 HTML 语法表示的元素的后代。

**备注：** 如果一个 `<div>`, `<span>`, 或 `<noembed>` 节点有一个文本子节点，该节点包含字符 `(&)`, `(<)`, 或 `(>)`, `innerHTML` 将这些字符分别返回为 &, < 和 >。使用`Node.textContent` 可获取一个这些文本节点内容的正确副本。

如果要向一个元素中插入一段 HTML，而不是替换它的内容，那么请使用 `insertAdjacentHTML()` 方法。

语法
--

```js
const content = element.innerHTML;
element.innerHTML = htmlString;
```

### 值

`DOMString` 包含元素后代的 HTML 序列。设置元素的 `innerHTML` 将会删除所有该元素的后代并以上面给出的 htmlString 替代。

### 例外

**`SyntaxError`**

当 HTML 没有被正确标记时，设置 `innerHTML` 将会抛出语法错误。

**`NoModificationAllowedError`**

当父元素是 `Document` 时，设置 `innerHTML` 将会提示不允许修改。

使用说明
----

`innerHTML` 属性可以用来检查当前页面自最初加载到当前的 HTML 源码的变化。

### 获取元素的 HTML

获取 `innerHTML` 会导致用户代理序列化 由元素后代组成的 HTML 或者 XML。返回结果字符串。

```js
let contents = myElement.innerHTML;
```

查看元素内容节点的 HTML 标记。

**备注：** 返回的 HTML 或者 XML 片段是基于当前元素的内容生成的，所以返回的标记和格式可能与原始页面的标记不匹配。

### 替换元素的内容

设置 `innerHTML` 的值可以让你轻松地将当前元素的内容替换为新的内容。

举个例子来说，你可以通过文档 `body` 属性删除 body 的全部内容。

```js
document.body.innerHTML = "";
```

下面这个例子，首先获取文档当前的 HTML 标记并替换 `"<"` 字符为 HTML 实体 `"<"`，从本质上来看，它是将 HTML 转换成原始文本，将其包裹在 `<pre>` 元素中。然后 `innerHTML` 的值被替换成新的字符串。最后，文档的内容被替换为页面显示源码。

```js
document.documentElement.innerHTML =
  "<pre>" + document.documentElement.innerHTML.replace(/</g, "<") + "</pre>";
```

#### 其他：

当给 `innerHTML` 设置一个值的时候到底发生了什么？用户代理按照以下步骤：

1. 给定的值被解析为 HTML 或者 XML（取决于文档类型），结果就是 `DocumentFragment` 对象代表元素新设置的 DOM 节点。
2. 如果元素内容被替换成 `<template>` 元素，`<template>` 元素的 `content` 属性会被替换为步骤 1 中创建的新的 `DocumentFragment`。
3. 对于其他所有元素，元素的内容都被替换为新的 `DocumentFragment` 节点。
### 安全问题

用 `innerHTML` 插入文本到网页中并不罕见。但这有可能成为网站攻击的媒介，从而产生潜在的安全风险问题。

```js
const name = "John";
// assuming 'el' is an HTML DOM element
el.innerHTML = name; // harmless in this case

// ...

name = "<script>alert('I am John in an annoying alert!')</script>";
el.innerHTML = name; // harmless in this case
```

尽管这看上去像 cross-site scripting 攻击，结果并不会导致什么。HTML 5 中指定不执行由 `innerHTML` 插入的 `<script>` 标签。

然而，有很多不依赖 `<script>` 标签去执行 JavaScript 的方式。所以当你使用`innerHTML` 去设置你无法控制的字符串时，这仍然是一个安全问题。例如：

```js
const name = "<img src='x' onerror='alert(1)'>";
el.innerHTML = name; // shows the alert
```

基于这个原因，当插入纯文本时，建议不要使用 `innerHTML` 。取而代之的是使用 `Node.textContent` ，它不会把给定的内容解析为 HTML，它仅仅是将原始文本插入给定的位置。

**警告：** 如果你的项目将要经过各种形式的安全检查的话，使用 `innerHTML` 可能导致代码被拒绝。例如，如果你在浏览器扩展中使用 `innerHTML` 并将扩展提交到 addons.mozilla.org 的话，它将会在自动审核过程中被拒绝。

示例
--

这个例子使用 `innerHTML` 创建一种机制用于将消息记录到网页上的框中。

### JavaScript

```js
function log(msg) {
  var logElem = document.querySelector(".log");

  var time = new Date();
  var timeStr = time.toLocaleTimeString();
  logElem.innerHTML += timeStr + ": " + msg + "<br/>";
}

log("Logging mouse events inside this container...");
```

log() 函数通过 `Date` 对象的 `toLocaleTimeString()` 方法获取当前时间，然后将消息文本和时间戳放一起构建一个字符串，最后将其追加到具有“log”类的框上。

现在添加第二个方法：记录基于事件 (比如 `mousedown`, `click`, 和 `mouseenter`) 的 `MouseEvent` 的信息。

```js
function logEvent(event) {
  var msg =
    "Event <strong>" +
    event.type +
    "</strong> at <em>" +
    event.clientX +
    ", " +
    event.clientY +
    "</em>";
  log(msg);
}
```

然后我们使用它作为包含我们消息的框上的鼠标事件的事件处理程序：

```js
var boxElem = document.querySelector(".box");

boxElem.addEventListener("mousedown", logEvent);
boxElem.addEventListener("mouseup", logEvent);
boxElem.addEventListener("click", logEvent);
boxElem.addEventListener("mouseenter", logEvent);
boxElem.addEventListener("mouseleave", logEvent);
```

### HTML

这个例子的 HTML 代码就相当简洁了：

```html
<div class="box">
  <div><strong>Log:</strong></div>
  <div class="log"></div>
</div>
```

具有“box”类的 `<div>` 容器仅仅是出于布局考虑，用一个框来展示其内容。具有“log”类的 <div> 元素是作为消息本身的内容框。

### CSS

下面是这个例子的 CSS：

```css
.box {
  width: 600px;
  height: 300px;
  border: 1px solid black;
  padding: 2px 4px;
  overflow-y: scroll;
  overflow-x: auto;
}

.log {
  margin-top: 8px;
  font-family: monospace;
}
```

### 结果

结果就像下面展示的那样。你可以通过移动鼠标进出盒子，点击盒子等等来查看记录输出。

规范
--

| Specification |
| --- |
| DOM Parsing and Serialization # dom-innerhtml-innerhtml |

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

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

参见
--

* `Node.textContent` and `Node.innerText`
* `Element.insertAdjacentHTML()`
* Parsing HTML into a DOM tree: `DOMParser`
* Serializing XML or HTML into a DOM tree: `XMLSerializer`


Element：contentvisibilityautostatechange 事件 - Web API 接口参考

Element：contentvisibilityautostatechange 事件
===========================================

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

**`contentvisibilityautostatechange`** 事件会在设置了 `content-visibility: auto` 的元素开始或不再与用户相关，且正在跳过其内容时触发。

在元素不再与用户相关时（在开始和结束事件之间），用户代理会跳过元素的渲染（包括布局和绘制），这可以显著提高页面渲染速度。`contentvisibilityautostatechange` 事件为应用代码在不需要时开始或停止渲染过程（如在 `<canvas>` 上绘画）提供了便利，进而节约了处理能力。

注意因为元素内容即使被隐藏不可见也仍将保持语义相关性（例如使用辅助技术的用户），所以不应使用此事件跳过重要的 DOM 语义更新。

语法
--

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

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

**备注：** 事件的类型为 `ContentVisibilityAutoStateChangeEvent`。

示例
--

```js
const canvasElem = document.querySelector("canvas");

canvasElem.addEventListener("contentvisibilityautostatechange", stateChanged);
canvasElem.style.contentVisibility = "auto";

function stateChanged(event) {
  if (event.skipped) {
    stopCanvasUpdates(canvasElem);
  } else {
    startCanvasUpdates(canvasElem);
  }
}

// 在画布需要开始更新时调用此方法。
function startCanvasUpdates(canvas) {
  // …
}

// 在画布需要停止更新时调用此方法。
function stopCanvasUpdates(canvas) {
  // …
}
```

规范
--

| Specification |
| --- |
| CSS Containment Module Level 2 # content-visibility-auto-state-change |

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

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

参见
--

* `ContentVisibilityAutoStateChangeEvent`
* CSS 局限
* `content-visibility` 属性
* `contain` 属性


NonDocumentTypeChildNode.previousElementSibling - Web API 接口参考

NonDocumentTypeChildNode.previousElementSibling
===============================================

### 概述

**`previousElementSibling`** 返回当前元素在其父元素的子元素节点中的前一个元素节点，如果该元素已经是第一个元素节点，则返回 `null`, 该属性是只读的。

### 语法
```

var prevNode = elementNodeReference.previousElementSibling;
```

### 例子

```html
<div id="div-01">Here is div-01</div>
<div id="div-02">Here is div-02</div>
<li>This is a list item</li>
<li>This is another list item</li>
<div id="div-03">Here is div-03</div>

<script type="text/javascript">
 var el = document.getElementById("div-03").previousElementSibling;
 document.write("<p>Siblings of div-03</p><ol>");
 while (el) {
 document.write("<li>" + el.nodeName + "</li>");
 el = el.previousElementSibling;
 }
 document.write("</ol>");
</script>
```

上面的例子会输出以下内容：
```

Siblings of div-03

   1. LI
   2. LI
   3. DIV
   4. DIV
```

### 浏览器兼容性

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


Element.attributes - Web API 接口参考

Element.attributes
==================

**`Element.attributes`** 属性返回一个注册到指定节点的所有属性节点的实时集合。该集合是一个 `NamedNodeMap` 对象，不是 `Array`，所以它没有 `Array` 的方法，其包含的 `Attr` 节点的索引顺序随浏览器不同而不同。更确切地说，`attributes` 是字符串形式的键值对，代表了那个属性的任何信息。

值
-

一个 `NamedNodeMap` 对象。

示例
--

### 基本示例

```js
// 获取文档中的第一个 <p> 元素
const paragraph = document.querySelector("p");
const attributes = paragraph.attributes;
```

### 遍历元素的属性

你可以使用 `for...of` 枚举一个元素的所有属性。

在以下例子中会遍历文档中 id 为“paragraph”的元素的属性节点，并打印出来。

```html
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <title>属性示例</title>
    <script>
 function listAttributes() {
 const paragraph = document.getElementById("paragraph");
 const result = document.getElementById("result");
 // 首先，确定那个段落有一些属性
 if (paragraph.hasAttributes()) {
 let output = "Attributes of first paragraph:\n";
 for (const attr of paragraph.attributes) {
 output += `${attr.name} -> ${attr.value}\n`;
 }
 result.textContent = output;
 } else {
 result.textContent = "没有可显示的属性";
 }
 }
 </script>
  </head>

  <body>
    <p id="paragraph" style="color: green;">示例段落</p>
    <form action="">
      <p>
        <input type="button" value="显示第一个属性名及其值"
 onclick="listAttributes();">
        <pre id="result"></pre>
      </p>
    </form>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-element-attributes |

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

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

参见
--

* `NamedNodeMap`，返回对象的接口
* 跨浏览器兼容性问题可参考：quirksmode


Element.scroll() - Web API 接口参考

Element.scroll()
================

**`scroll()`** 方法是用于在给定的元素中滚动到某个特定坐标的 `Element` 接口。

语法
--

```js
scroll(x-coord, y-coord)
scroll(options)
```

### 参数

`x-coord`

你想要显示在左上角的元素沿水平轴的像素。

`y-coord`

你想要显示在左上角的元素沿垂直轴的像素。

- 或者 -

`options`

包含以下参数的对象：

`top`

指定沿 Y 轴滚动窗口或元素的像素数。

`left`

指定沿 X 轴滚动窗口或元素的像素数。

`behavior`

`smooth` 表示平滑滚动并产生过渡效果，`auto` 或缺省值会直接跳转到目标位置，没有过渡效果。

### 返回值

无 (`undefined`)。

示例
--

```js
// 将元素沿垂直方向向下滚动 1000 个像素
element.scroll(0, 1000);
```

使用 `options`:

```js
element.scroll({
  top: 100,
  left: 100,
  behavior: "smooth",
});
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-element-scroll |

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

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


Element：id 属性 - Web API 接口参考

Element：id 属性
=============

`Element` 接口的 **`id`** 属性表示元素的标识符，反映了全局属性 **`id`** 的值。

如果 `id` 的值不为空字符串，则在同一文档中必须唯一。

这有助于让常用的 `getElementById()` 方法通过 `id` 的值找到对应的单个元素。另外，在使用 CSS 为文档添加样式时，ID 可作为选择器使用。

**备注：** 虽然 ID 是区分大小写的，但是不应该同时使用仅大小写不同的 ID 值。

值
-

一个字符串。

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-id① |

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

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

参见
--

* DOM 全局属性 **id**。


Element: contextmenu event - Web API 接口参考

Element: contextmenu event
==========================

**`contextmenu`** 事件会在用户尝试打开上下文菜单时被触发。该事件通常在鼠标点击右键或者按下键盘上的菜单键时被触发，如果使用菜单键，该上下文菜单会被展示 到所聚焦元素的左下角，但是如果该元素是一棵 DOM 树的话，上下文菜单便会展示在当前这一行的左下角。

任何没有被禁用的鼠标右击事件 (通过调用事件的 `preventDefault()` 方法) 将会使得 `contextmenu` 事件在目标元素上被触发。

|  |  |
| --- | --- |
| Bubbles（冒泡） | Yes |
| Cancelable（可撤销） | Yes |
| Interface（接口） | `MouseEvent` |
| Event handler property（事件处理器） | `oncontextmenu` |

示例
--

在下面的例子中，第一段内容被触发的 `contextmenu` 事件的默认行为被 `preventDefault()` 取消了，因此，在第一段右击鼠标时什么也不会发生，但是右键单击第二段内容时，则会出现标准的菜单内容，与平时右击普通页面出现的菜单内容一致。

### HTML

```html
<p id="noContextMenu">这个段落右键菜单已被禁用。</p>
<p>但是这个段落没有被禁用。</p>
```

### JavaScript

```js
noContext = document.getElementById("noContextMenu");

noContext.addEventListener("contextmenu", (e) => {
  e.preventDefault();
});
```

### 结果

规范
--

| Specification |
| --- |
| UI Events # event-type-contextmenu |

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

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

参见
--

* 事件介绍
* `click`
* `contextmenu`
* `dblclick`
* `mousedown`
* `mouseup`
* `pointerdown`
* `pointerup`


Element.closest() - Web API 接口参考

Element.closest()
=================

**`Element.closest()`** 方法用来获取：匹配特定选择器且离当前元素最近的祖先元素（也可以是当前元素本身）。如果匹配不到，则返回 `null`。

语法
--
```

var closestElement = targetElement.closest(selectors);
```

### 参数

* *selectors* 是指定的选择器，比如 `"p:hover, .toto + q"`。
### 返回值

* *elt* 是查询到的祖先元素，也可能是 `null`。
### 异常

`SyntaxError` `DOMException`

如果选择器不合法，则抛出该异常。

示例
--

### HTML

```html
<article>
  <div id="div-01">
    Here is div-01
    <div id="div-02">
      Here is div-02
      <div id="div-03">Here is div-03</div>
    </div>
  </div>
</article>
```

### JavaScript

```js
var el = document.getElementById("div-03");

var r1 = el.closest("#div-02");
// 返回 id 为 div-02 的那个元素

var r2 = el.closest("div div");
// 返回最近的拥有 div 祖先元素的 div 祖先元素，这里的话就是 div-03 元素本身

var r3 = el.closest("article > div");
// 返回最近的拥有父元素 article 的 div 祖先元素，这里的话就是 div-01

var r4 = el.closest(":not(div)");
// 返回最近的非 div 的祖先元素，这里的话就是最外层的 article
```

兼容
--

部分浏览器并不支持`Element.closest()`，但却支持了`element.matches()`（或拥有私有前缀，如 IE9+），一个 polyfill 案例：

```js
if (!Element.prototype.matches)
  Element.prototype.matches =
    Element.prototype.msMatchesSelector ||
    Element.prototype.webkitMatchesSelector;

if (!Element.prototype.closest)
  Element.prototype.closest = function (s) {
    var el = this;
    if (!document.documentElement.contains(el)) return null;
    do {
      if (el.matches(s)) return el;
      el = el.parentElement;
    } while (el !== null);
    return null;
  };
```

然而，如果你需要兼容到 IE8，那么随后这个 polyfill 将会非常缓慢地运行到结束。并且，IE8 只支持 CSS2.1 的选择器，并且使网页运行非常缓慢。

```js
if (window.Element && !Element.prototype.closest) {
  Element.prototype.closest = function (s) {
    var matches = (this.document || this.ownerDocument).querySelectorAll(s),
      i,
      el = this;
    do {
      i = matches.length;
      while (--i >= 0 && matches.item(i) !== el) {}
    } while (i < 0 && (el = el.parentElement));
    return el;
  };
}
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-closest① |

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

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

### 兼容性说明

* 当在 Edge 15-18 里使用 `document.createElement(tagName).closest(tagName)` ，如果元素不是第一个（直接地或间接地）连接到上下文对象的话将会返回 `null` ，例如在一般情况下 DOM 中的 `Document` 对象。
参见
--

* `Element` 接口。
* 选择器语法 (en-US)
* 其他相关选择器方法：`element.querySelector()` and `element.matches()`.


Element: keyup event - Web API 接口参考

Element: keyup event
====================

**`keyup`** 事件在按键被松开时触发。

| 冒泡 | 是 |
| 可取消 | 是 |
| 接口 | `KeyboardEvent` |
| 事件处理函数属性 | `onkeyup` |

`keydown` 和 `keyup` 事件提供指出哪个键被按下的代码，而 `keypress` 指出哪些字符被输入。例如，小写字母“a”在 `keydown` 和 `keyup` 时会被报告为 65，但在 `keypress` 时为 97。所有事件均将大写字母“A”报告为 65。

从 Firefox 65 开始，`keyup` 和 `keydown` 事件在 IME 编辑时也会被触发，以提升 CJKT 用户的跨浏览器兼容性（Firefox bug 354358）。要忽略 IME 编辑时的所有 `keyup` 事件，请执行以下操作（229 是一个关于被 IME 加工过的事件的 `keyCode` 的特殊值）：

```js
eventTarget.addEventListener("keyup", (event) => {
  if (event.isComposing || event.keyCode === 229) {
    return;
  }
  // do something
});
```

例子
--

### addEventListener keyup 例子

在这个例子中，每当你在 `<input>` 元素里松开一个键，将会打印 `KeyboardEvent.code` 的值。

```html
<input placeholder="Click here, then press and release a key." size="40" />
<p id="log"></p>
```

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

input.addEventListener("keyup", logKey);

function logKey(e) {
  log.textContent += ` ${e.code}`;
}
```

### 等效的 onkeyup

```js
input.onkeyup = logKey;
```

规范
--

| Specification |
| --- |
| UI Events # event-type-keyup |
| HTML Standard # handler-onkeyup |

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

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

参见
--

* `input`
* `keydown`
* `keypress`
* Document `keyup` 事件 (en-US)


Element.hasAttribute() - Web API 接口参考

Element.hasAttribute()
======================

概述
--

`hasAttribute` 返回一个布尔值，指示该元素是否包含有指定的属性（attribute）。

语法
--
```

var result = element.hasAttribute(attName);
```

* `result` 为返回的布尔值：`true` 或 `false`。
* `attName` 是一个字符串，表示属性的名称。
例子
--

```js
// 在为属性设置新值前检测该属性是否存在
var d = document.getElementById("div1");

if (d.hasAttribute("align")) {
  d.setAttribute("align", "center");
}
```

备注
--

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

规范
--

* DOM Level 2 Core: hasAttribute
* DOM Level 3 Core: hasAttribute


Element：touchstart 事件 - Web API 接口参考

Element：touchstart 事件
=====================

`touchstart` 事件在一个或多个触点与触控设备表面接触时被触发。

语法
--

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

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

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

事件类型
----

一个 `TouchEvent`。继承自 `Event`。

Event

UIEvent

TouchEvent事件属性
----

*此接口从其父接口 `UIEvent` 和 `Event` 继承属性。*

`TouchEvent.altKey` (en-US) 只读

一个布尔值，表示在事件触发时 Alt 键是否被按下。

`TouchEvent.changedTouches` 只读

一个包含所有的 `Touch` 对象的 `TouchList`，这些 `Touch` 对象表示在前一个 touch 事件和当前的事件之间，状态发生变化的独立触点。

`TouchEvent.ctrlKey` (en-US) 只读

一个布尔值，表示在事件触发时控制键是否被按下。

`TouchEvent.metaKey` (en-US) 只读

一个布尔值，表示在事件触发时 Meta 键是否被按下。

`TouchEvent.shiftKey` (en-US) 只读

一个布尔值，表示在事件触发时 Shift 键是否被按下。

`TouchEvent.targetTouches` 只读

一个包含所有的 `Touch` 对象的 `TouchList`，这些 `Touch` 对象表示当前与触摸表面接触的触点，且触点起始于事件发生的目标元素。

`TouchEvent.touches` 只读

一个包含所有的 `Touch` 对象的 `TouchList`，这些 `Touch` 对象表示当前与表面接触的触点（不论事件目标或状态变化）。

`TouchEvent.rotation`
非标准
 只读

自事件开始以来的旋转角度变化（以度为单位）。正值表示顺时针旋转；负值表示逆时针旋转。初始值为 `0.0`。

`TouchEvent.scale`
非标准
 只读

自事件开始以来，两个数值之间的距离（缩放倍数）。表示事件开始至现在，触点距离的缩放倍数（浮点数）。小于 1.0 表示向内收缩（缩小），大于 1.0 表示向外松开（放大）。初始值为 `1.0`。

示例
--

这些事件的代码示例可在这个专用页面查看：Touch 事件。

规范
--

| Specification |
| --- |
| Touch Events # event-touchstart |
| Touch Events # dom-globaleventhandlers-ontouchstart |

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

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

参见
--

* Touch 事件
* 以 `Document` 为目标的相同事件：`touchstart`


Element.getAttributeNodeNS() - Web API 接口参考

Element.getAttributeNodeNS()
============================

概要
--

通过命名空间 URI 和名称来获取属性节点。

语法
--
```

attributeNode = element.getAttributeNodeNS(namespace,nodeName)
```

* `attributeNode` 获取的属性节点。
* `namespace` 命名空间字符串
* `nodeName` 属性节点的名称。

== Example == TBD The example needs to be fixed pre> // html: <div id="top" /> t = document.getElementById("top"); specialNode = t.getAttributeNodeNS( "http://www.mozilla.org/ns/specialspace", "id"); // iNode.value = "full-top" </pre

笔记
--

`getAttributeNodeNS` 相比 getAttributeNode 更加具体，允许你在特定的命名空间里获取属性。对应的 setter 方法是 setAttributeNodeNS.

DOM methods dealing with element's attributes:

| Not namespace-aware, most commonly used methods | Namespace-aware variants (DOM Level 2) | DOM Level 1 methods for dealing with `Attr` nodes directly (seldom used) | DOM Level 2 namespace-aware methods for dealing with `Attr` nodes directly (seldom used) |
| --- | --- | --- | --- |
| `setAttribute` (DOM 1) | `setAttributeNS` | `setAttributeNode` | `setAttributeNodeNS` |
| `getAttribute` (DOM 1) | `getAttributeNS` (en-US) | `getAttributeNode` | `getAttributeNodeNS` |
| `hasAttribute` (DOM 2) | `hasAttributeNS` | - | - |
| `removeAttribute` (DOM 1) | `removeAttributeNS` | `removeAttributeNode` | - |

规格
--

DOM Level 2 Core: getAttributeNodeNS


Element：copy 事件 - Web API 接口参考

Element：copy 事件
===============

当用户通过浏览器的用户界面发起复制动作时，将触发 **`copy`** 事件。

该事件的默认行为是将当前选中的内容（如有）复制到系统剪贴板。

事件处理器可以通过调用 `ClipboardEvent.clipboardData` 属性上的 `setData(format, data)` *修改*剪贴板内容，并通过 `event.preventDefault()` 取消默认行为。

然而，事件处理器不可以*读取*剪贴板数据。

可以构建和派发一个合成 `copy` 事件，但这不会影响系统剪贴板。

语法
--

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

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

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

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent示例
--

### 实时示例

#### HTML

```html
<div class="source" contenteditable="true">从这个盒子复制文字</div>
<div class="target" contenteditable="true">在这里粘贴</div>
```

```
div.source,
div.target {
  border: 1px solid gray;
  margin: 0.5rem;
  padding: 0.5rem;
  height: 1rem;
  background-color: #e9eef1;
}
```

#### JavaScript

```js
const source = document.querySelector("div.source");

source.addEventListener("copy", (event) => {
  const selection = document.getSelection();
  event.clipboardData.setData("text/plain", selection.toString().toUpperCase());
  event.preventDefault();
});
```

#### 结果

规范
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-copy |
| HTML Standard # handler-oncopy |

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

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

参见
--

* 相关联事件：`cut`、`paste`
* `Document` 目标上的这个事件：`copy` (en-US)
* `Window` 目标上的这个事件：`copy`


Element：append() 方法 - Web API 接口参考

Element：append() 方法
===================

**`Element.append()`** 方法在当前 `Element` 的最后一个子节点之后插入一组 `Node` 对象或字符串对象。被插入的字符串对象等价为 `Text` (en-US) 节点。

其与 `Node.appendChild()` 的差异：

* `Element.append()` 允许附加字符串对象，而 `Node.appendChild()` 只接受 `Node` 对象。
* `Element.append()` 没有返回值，而 `Node.appendChild()` 返回附加的 `Node` 对象。
* `Element.append()` 可以附加多个节点和字符串，而 `Node.appendChild()` 只能附加一个节点。
语法
--

```js
append(param1)
append(param1, param2)
append(param1, param2, /\* …, \*/ paramN)
```

### 参数

`param1`、…、`paramN`

一组要插入的 `Node` 或字符串对象。

### 返回值

无（`undefined`）。

### 异常

`HierarchyRequestError` `DOMException`

当层次结构中的指定位置不能插入节点时抛出该异常。

示例
--

### 附加元素

```js
let div = document.createElement("div");
let p = document.createElement("p");
div.append(p);

console.log(div.childNodes); // NodeList [ <p> ]
```

### 附加文本

```js
let div = document.createElement("div");
div.append("一些文本");

console.log(div.textContent); // "一些文本"
```

### 附加元素和文本

```js
let div = document.createElement("div");
let p = document.createElement("p");
div.append("一些文本", p);

console.log(div.childNodes); // NodeList [ #text "一些文本", <p> ]
```

### append 是非作用域方法

`append()` 方法无法被绑定到 `with` 语句的作用域中。参见 `Symbol.unscopables` 以了解更多信息。

```js
let div = document.createElement("div");

with (div) {
  append("foo");
}
// ReferenceError: append is not defined
```

规范
--

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

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

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

参见
--

* `Element.prepend()`
* `Node.appendChild()`
* `Element.after()`
* `Element.insertAdjacentElement()`
* `NodeList`


Element.scrollTop - Web API 接口参考

Element.scrollTop
=================

**`Element.scrollTop`** 属性可以获取或设置一个元素的内容垂直滚动的像素数。

一个元素的 `scrollTop` 值是这个元素的**内容顶部**（卷起来的）到它的视口可见内容（的顶部）的距离的度量。当一个元素的内容没有产生垂直方向的滚动条，那么它的 `scrollTop` 值为`0`。

**警告：** 在使用显示比例缩放的系统上，`scrollTop`可能会提供一个小数。

语法
--
```

// 获得滚动的像素数
var  intElemScrollTop = someElement.scrollTop;
```

运行此代码后， `intElemScrollTop` 是一个整数，即`element`的内容向上滚动的像素数。
```

// 设置滚动的距离
element.scrollTop = intValue;
```

`scrollTop` 可以被设置为任何整数值，同时注意：

* 如果一个元素不能被滚动（例如，它没有溢出，或者这个元素有一个"\*\*non-scrollable"\*\*属性）， `scrollTop`将被设置为`0`。
* 设置`scrollTop`的值小于 0，`scrollTop` 被设为`0`
* 如果设置了超出这个容器可滚动的值，`scrollTop` 会被设为最大值。
例子
--

padding-top

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

padding-bottom

**Left** **Top** **Right** **Bottom** *margin-top* *margin-bottom* *border-top* *border-bottom*

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-element-scrolltop |

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

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

参考
--

* MSDN's Measuring Element Dimension and Location
* `Element.scrollLeft`
* `Element.scrollTo()`


GlobalEventHandlers.onpointerdown - Web API 接口参考

GlobalEventHandlers.onpointerdown
=================================

**`pointerdown`** 事件的 `全局事件处理程序`

语法
--
```

var downHandler = targetElement.onpointerdown;
```

### 返回值

`downHandler`

*pointerdown* 事件触发对象的事件处理程序。

示例
--

当前示例展示两种方式使用 *onpointerdown* 去设置元素的 pointerdown 事件处理程序。

```js
<html>
<script>
function downHandler(ev) {
 // Process the pointerdown event
}
function init() {
 var el=document.getElementById("target1");
 el.onpointerdown = downHandler;
}
</script>
<body onload="init();">
<div id="target1"> Touch me ... </div>
<div id="target2" onpointerdown="downHandler(event)"> Touch me ... </div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| Pointer Events # the-pointerdown-event |
| Pointer Events # dom-globaleventhandlers-onpointerdown |

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

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

参见
--

* 相关事件
    + `gotpointercapture`
    + `lostpointercapture`
    + `pointerover`
    + `pointerenter`
    + `pointermove`
    + `pointercancel`
    + `pointerup`
    + `pointerout`
    + `pointerleave`


Element：scrollIntoViewIfNeeded() 方法 - Web API 接口参考

Element：scrollIntoViewIfNeeded() 方法
===================================

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

**`Element.scrollIntoViewIfNeeded()`** 方法将不在浏览器窗口的可见区域内的元素滚动到浏览器窗口的可见区域。如果该元素已经在浏览器窗口的可见区域内，则不会发生滚动。此方法是标准的 `Element.scrollIntoView()` 方法的专有变体。

语法
--

```js
scrollIntoViewIfNeeded()
scrollIntoViewIfNeeded(centerIfNeeded)
```

### 参数

`centerIfNeeded` 可选

一个可选的布尔值，默认为`true`：

* 如果为 `true`，则元素将在其所在滚动区的可视区域中居中对齐。
* 如果为 `false`，则元素将与其所在滚动区的可视区域最近的边缘对齐。根据可见区域最靠近元素的哪个边缘，元素的顶部将与可见区域的顶部边缘对准，或者元素的底部边缘将与可见区域的底部边缘对准。

### 返回值

无（`undefined`）。

示例
--

```js
const element = document.getElementById("my-el");

element.scrollIntoViewIfNeeded(); // 将元素置于可见区域的中心
element.scrollIntoViewIfNeeded(false); // 将元素与可见区域中最近的边缘对齐
```

规范
--

不属于任何规范。这是一种 WebKit 专有的方法。

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

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

参见
--

* W3C CSSOM bug 17152：支持在元素滚动入视图时将其居中。（等同于 `scrollIntoViewIfNeeded` 的标准特性的请求）


Element.querySelectorAll() - Web API 接口参考

Element.querySelectorAll()
==========================

返回一个 non-live 的`NodeList`, 它包含所有元素的非活动节点，该元素来自与其匹配指定的 CSS 选择器组的元素。(基础元素本身不包括，即使它匹配。)

**备注：** 该 API 的定义已被移动到 `ParentNode` 接口。

语法
--

```js
elementList = baseElement.querySelectorAll(selectors);
```

其中

* `elementList`会是一个 non-live 的`NodeList`对象。
* `baseElement 是一个`元素对象。
* `selectors`是一组 CSS 选择器。
示例
--

### dataset selector & attribute selectors

```html
<section class="box" id="sect1">
  <div class="funnel-chart-percent1">10.900%</div>
  <div class="funnel-chart-percent2">3700.00%</div>
  <div class="funnel-chart-percent3">0.00%</div>
</section>
```

```js
// dataset selectors
const refs = [
  ...document.querySelectorAll(`[data-name\*="funnel-chart-percent"]`),
];

// attribute selectors
// const refs = [...document.querySelectorAll(`[class\*="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class^="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class$="funnel-chart-percent"]`)];
// const refs = [...document.querySelectorAll(`[class~="funnel-chart-percent"]`)];
```

下面的例子返回了 HTML 文档中的 `body` 元素的所有 `p` 后代元素：

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

下面的例子返回了`id`为`'test`'的元素的所有`class 属性`为'`highlighted`'的所有 div 后代元素的`p`子元素：

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

下面的例子返回了 el 元素的后代元素中所有拥有`data-src`属性的`iframe`元素：

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

附注
--

如果指定的 CSS 选择器不合法，则会抛出一个`SYNTAX_ERR` 异常。

返回值是一个`NodeList`对象，所以不推荐使用 for...in 去遍历它 (会遍历出其他无关属性)

想要在它身上使用数组方法，必须先把它转换为真正的数组。

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

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

规范
--

* 选择器 API
参见
--

* `Element.querySelector`
* `document.querySelectorAll`
* `document.querySelector`
* Code snippets for `querySelector`


Element：mouseout 事件 - Web API 接口参考

Element：mouseout 事件
===================

**`mouseout`** 事件在定点设备（通常是鼠标）移动至元素或其子元素之外时，会在该元素上触发。

当指针从一个元素移入其子元素时，因为子元素遮盖了父元素的可视区域，所以 `mouseout` 也会被触发。

语法
--

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

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

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

事件类型
----

一个 `MouseEvent`。继承自 `Event`。

Event

UIEvent

MouseEvent事件属性
----

*这个接口也继承其父接口 `UIEvent` 和 `Event` 的属性。*

`MouseEvent.altKey` 只读

当鼠标事件被触发时，如果 `alt` 键已被按下，返回 `true`。

`MouseEvent.button` 只读

触发鼠标事件时，按下按钮的编号（如果适用）。

`MouseEvent.buttons` 只读

触发鼠标事件时，按下的按钮（如果存在）。

`MouseEvent.clientX` 只读

鼠标指针相对于局部 DOM 元素的 X 轴坐标。

`MouseEvent.clientY` 只读

鼠标指针相对于局部 DOM 元素的 Y 轴坐标。

`MouseEvent.ctrlKey` 只读

当鼠标事件被触发时，如果 `control` 键已被按下，返回 `true`。

`MouseEvent.layerX` (en-US)
非标准
 只读

返回事件相对于当前层的水平坐标。

`MouseEvent.layerY` (en-US)
非标准
 只读

返回事件相对于当前层的垂直坐标。

`MouseEvent.metaKey` 只读

当鼠标事件被触发时，如果 `meta` 键已被按下，返回 `true`。

`MouseEvent.movementX` 只读

鼠标指针相对于最后一次 `mousemove` 事件位置的 X 轴坐标。

`MouseEvent.movementY` 只读

鼠标指针相对于最后一次 `mousemove` 事件位置的 Y 轴坐标。

`MouseEvent.offsetX` 只读

鼠标指针相对于目标节点的内填充边的 X 轴坐标。

`MouseEvent.offsetY` 只读

鼠标指针相对于目标节点的内填充边的 Y 轴坐标。

`MouseEvent.pageX` 只读

鼠标指针相对于整个文档的 X 轴坐标。

`MouseEvent.pageY` 只读

鼠标指针相对于整个文档的 Y 轴坐标。

`MouseEvent.relatedTarget` 只读

事件的次要目标（如果存在）。

`MouseEvent.screenX` 只读

鼠标指针相对于屏幕的 X 轴坐标。

`MouseEvent.screenY` 只读

鼠标指针相对于屏幕的 Y 轴坐标。

`MouseEvent.shiftKey` 只读

当鼠标事件被触发时，如果 `shift` 键已被按下，返回 `true`。

`MouseEvent.mozInputSource`
非标准
 只读

生成事件的设备类型（`MOZ_SOURCE_*` 常量之一）。例如，这允许你决定鼠标事件是否由实际的鼠标还是触摸事件生成（这可能会在一定程度影响你对事件相关坐标判断的准确性）。

`MouseEvent.webkitForce` (en-US)
非标准
 只读

单击时施加的压力大小。

`MouseEvent.x` 只读

`MouseEvent.clientX` 的别名。

`MouseEvent.y` 只读

`MouseEvent.clientY` 的别名。

示例
--

以下示例将说明如何使用 `mouseout` 事件。

### mouseout 和 mouseleave

以下示例说明了 `mouseout` 和 `mouseleave` 事件的区别。为 `<ul>` 添加 `mouseleave` 事件，以在鼠标离开 `<ul>` 元素时将列表变成紫色。添加 `mouseout` 事件，以在鼠标移出目标元素时将目标元素变成橙色。

当你尝试的时候，你会发现 `mouseout` 被添加到单个列表项目上，而 `mouseleave` 则应用于整个列表，这取决于列表项目的层次关系，而列表项目遮盖了底层的 `<ul>`。

#### HTML

```html
<ul id="test">
  <li>item 1</li>
  <li>item 2</li>
  <li>item 3</li>
</ul>
```

#### JavaScript

```js
const test = document.getElementById("test");

// 当鼠标移出 <ul> 元素时，短暂地将列表变成紫色
test.addEventListener(
  "mouseleave",
  (event) => {
    // 高亮 mouseleave 的目标
    event.target.style.color = "purple";

    // 延迟一秒后重置颜色
    setTimeout(() => {
      event.target.style.color = "";
    }, 1000);
  },
  false,
);

// 当鼠标离开 <li> 元素时，短暂地将其变成橙色
test.addEventListener(
  "mouseout",
  (event) => {
    // 高亮 mouseout 的目标
    event.target.style.color = "orange";

    // 延迟 500ms 后重置颜色
    setTimeout(() => {
      event.target.style.color = "";
    }, 500);
  },
  false,
);
```

#### 结果

规范
--

| Specification |
| --- |
| UI Events # event-type-mouseout |
| HTML Standard # handler-onmouseout |

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

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

参见
--

* 事件介绍
* `mousedown`
* `mouseup`
* `mousemove`
* `click`
* `dblclick`
* `mouseover`
* `mouseenter`
* `mouseleave`
* `contextmenu`


Element.clientWidth - Web API 接口参考

Element.clientWidth
===================

只读属性 **`Element.clientWidth`** 对于内联元素以及没有 CSS 样式的元素为 0；否则，它是元素内部的宽度（以像素为单位）。该属性包括内边距（padding），但不包括边框（border）、外边距（margin）和垂直滚动条（如果存在）。

在根元素（`<html>` 元素）或怪异模式下的 `<body>` 元素上使用 `clientWidth` 时，该属性将返回视口宽度（不包含任何滚动条）。这是一个 `clientWidth` 的特例。

**备注：** 该属性值会被四舍五入为一个整数。如果你需要一个小数值，可使用 `element.getBoundingClientRect()`。

值
-

一个数字。

示例
--

![](/zh-CN/docs/Web/API/Element/clientWidth/dimensions-client.png)

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-element-clientwidth |

### 备注

`clientWidth` 首次出现于微软 IE 浏览器的 DHTML 对象模型中。

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

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

参见
--

* `HTMLElement.offsetWidth`
* `Element.scrollWidth`
* 确定元素的宽高


Element.clientLeft - Web API 接口参考

Element.clientLeft
==================

表示一个元素的左边框的宽度，以像素表示。如果元素的文本方向是从右向左（RTL, right-to-left），并且由于内容溢出导致左边出现了一个垂直滚动条，则该属性包括滚动条的宽度。`clientLeft` 不包括左外边距和左内边距。`clientLeft` 是只读的。

从 Gecko 1.9（Firefox 3 Firefox bug 111207）开始，基于 Gecko 的应用支持 `clientLeft` 属性。该属性在 Firefox 2 及更早的版本中不被支持。

当 *layout.scrollbar.side* preference （译注：这个属性好像是只在火狐浏览器中才有）被设为 1 或 3，且文本方向被设为从右到左（RTL），则垂直滚动条位于左边，这会影响到 `clientLeft` 属性值的计算。

语法
--
```

var left = element.clientLeft;
```

示例
--

padding-top

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

padding-bottom

**Left** **Top** **Right** **Bottom** *margin-top* *margin-bottom* *border-top* *border-bottom*

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

| Specification |
| --- |
| CSSOM View Module # dom-element-clientleft |

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

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

备注
--

`clientLeft` 首次出现于 MS IE DHTML 对象模型中。

元素的文本方向被设为从右到左后，其垂直滚动条的位置取决于 *layout.scrollbar.side* preference

当元素设置 `display: inline` 后，无论是否有边框，`clientLeft` 始终返回 `0` 。


Element.replaceWith() - Web API 接口参考

Element.replaceWith()
=====================

**`ChildNode.replaceWith()`** 的方法用一套 `Node` 对象或者字符串对象，替换了该节点父节点下的子节点。字符串对象被当做等效的 `Text` (en-US) 节点插入。

语法
--

```js
replaceWith(param1)
replaceWith(param1, param2)
replaceWith(param1, param2, /\* …, \*/ paramN)
```

### 参数

`param1`、…、`paramN`

一系列用来替换的 `Node` 对象或者字符串对象。

### 异常

`HierarchyRequestError` `DOMException`

无法在层次结构中的指定节点处插入节点时抛出。

示例
--

### 使用 `replaceWith()`

```js
const div = document.createElement("div");
const p = document.createElement("p");
div.appendChild(p);
const span = document.createElement("span");

p.replaceWith(span);

console.log(div.outerHTML);
// "<div><span></span></div>"
```

### `replaceWith()` 是非作用域方法

`replaceWith()` 方法不能作用于 with 语句。参考 `Symbol.unscopables` 获取更多信息。

```js
with (node) {
  replaceWith("foo");
}
// ReferenceError: replaceWith is not defined
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-replacewith① |

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

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

参见
--

* `Node.replaceChild()`
* `NodeList`


Element.scrollHeight - Web API 接口参考

Element.scrollHeight
====================

**`Element.scrollHeight`** 只读属性是一个元素内容高度的度量，包括由于溢出导致的视图中不可见内容。

![](/zh-CN/docs/Web/API/Element/scrollHeight/scrollheight.png)

`scrollHeight` 的值等于该元素在不使用滚动条的情况下为了适应视口中所用内容所需的最小高度。高度的度量方式与 `clientHeight` 相同：包括元素的内边距，但不包括元素的边框、外边距以及水平滚动条（如果存在）。它也包括 `::before` 和 `::after` 这样的伪元素的高度。如果元素的内容不需要垂直滚动条就可以容纳，则其 `scrollHeight` 等于 `clientHeight`。

**备注：** 属性将会对值取整。如果需要小数值，请使用 `Element.getBoundingClientRect()`。

值
-

与元素的滚动高度像素值相对应的整数。

问题与解决方案
-------

### 判断元素是否滚动到底

`scrollTop` 是一个非整数，而 `scrollHeight` 和 `clientHeight` 是四舍五入的，因此确定滚动区域是否滚动到底的唯一方法是查看滚动量是否足够接近某个阈值（在本例中为 `1`）：

```js
Math.abs(element.scrollHeight - element.clientHeight - element.scrollTop) < 1;
```

以下内容*不*会一直有效，因为 `scrollTop` 可能包含小数：

```js
element.scrollHeight - Math.abs(element.scrollTop) === element.clientHeight;
```

### 判断元素是否能滚动

当容器不滚动但有溢出的子容器时，这些检查可以确定容器能否滚动：

```js
window.getComputedStyle(element).overflowY === "visible";
window.getComputedStyle(element).overflowY !== "hidden";
```

示例
--

### 判定用户是否阅读过文本

监听 `onscroll` 事件，这个等价事件可以用来判定用户是否阅读过文本。 (参见 `element.scrollTop` 和 `element.clientHeight` 属性)。

下面演示中的复选框已禁用，文本区域的内容滚动倒底部时，复选框才能被选中表示同意。

#### HTML

```html
<form name="registration">
  <p>
    <textarea id="rules">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum at laoreet magna.
Aliquam erat volutpat. Praesent molestie, dolor ut eleifend aliquam, mi ligula ultrices sapien, quis cursus
neque dui nec risus. Duis tincidunt lobortis purus eu aliquet. Quisque in dignissim magna. Aenean ac lorem at
velit ultrices consequat. Nulla luctus nisi ut libero cursus ultrices. Pellentesque nec dignissim enim. Phasellus
ut quam lacus, sed ultricies diam. Vestibulum convallis rutrum dolor, sit amet egestas velit scelerisque id.
Proin non dignissim nisl. Sed mi odio, ullamcorper eget mattis id, malesuada vitae libero. Integer dolor lorem,
mattis sed dapibus a, faucibus id metus. Duis iaculis dictum pulvinar. In nisi nibh, dapibus ac blandit at, porta
at arcu. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Praesent
dictum ipsum aliquet erat eleifend sit amet sollicitudin felis tempus. Aliquam congue cursus venenatis. Maecenas
luctus pellentesque placerat. Mauris nisl odio, condimentum sed fringilla a, consectetur id ligula. Praesent sem
sem, aliquet non faucibus vitae, iaculis nec elit. Nullam volutpat, lectus et blandit bibendum, nulla lorem congue
turpis, ac pretium tortor sem ut nibh. Donec vel mi in ligula hendrerit sagittis. Donec faucibus viverra fermentum.
Fusce in arcu. Nullam at dignissim massa. Cras nibh est, pretium sit amet faucibus eget, sollicitudin in
ligula. Vivamus vitae urna mauris, eget euismod nunc. Aenean semper gravida enim non feugiat. In hac habitasse
platea dictumst. Cras eleifend nisl volutpat ante condimentum convallis. Donec varius dolor malesuada erat
consequat congue. Donec eu lacus ut sapien venenatis tincidunt. Quisque sit amet tellus et enim bibendum varius et
a orci. Donec aliquet volutpat scelerisque. Proin et tortor dolor. Ut aliquet, dolor a mattis sodales, odio diam
pulvinar sem, egestas pretium magna eros vitae felis. Nam vitae magna lectus, et ornare elit. Morbi feugiat, ipsum
ac mattis congue, quam neque mollis tortor, nec mollis nisl dolor a tortor. Maecenas varius est sit amet elit
interdum quis placerat metus posuere. Duis malesuada justo a diam vestibulum vel aliquam nisi ornare. Integer
laoreet nisi a odio ornare non congue turpis eleifend. Cum sociis natoque penatibus et magnis dis parturient montes,
nascetur ridiculus mus. Cras vulputate libero sed arcu iaculis nec lobortis orci fermentum.
    </textarea>
  </p>
  <p>
    <input type="checkbox" id="agree" name="accept" />
    <label for="agree">I agree</label>
    <input type="submit" id="nextstep" value="Next" />
  </p>
</form>
```

#### CSS

```css
#notice {
  display: inline-block;
  margin-bottom: 12px;
  border-radius: 5px;
  width: 600px;
  padding: 5px;
  border: 2px #7fdf55 solid;
}

#rules {
  width: 600px;
  height: 130px;
  padding: 5px;
  border: #2a9f00 solid 2px;
  border-radius: 5px;
}
```

#### JavaScript

```js
function checkReading() {
  if (checkReading.read) {
    return;
  }
  checkReading.read =
    this.scrollHeight - Math.round(this.scrollTop) === this.clientHeight;
  document.registration.accept.disabled = document.getElementById(
    "nextstep",
  ).disabled = !checkReading.read;
  checkReading.noticeBox.textContent = checkReading.read
    ? "Thank you."
    : "Please, scroll and read the following text.";
}

onload = () => {
  const oToBeRead = document.getElementById("rules");
  checkReading.noticeBox = document.createElement("span");
  document.registration.accept.checked = false;
  checkReading.noticeBox.id = "notice";
  oToBeRead.parentNode.insertBefore(checkReading.noticeBox, oToBeRead);
  oToBeRead.parentNode.insertBefore(document.createElement("br"), oToBeRead);
  oToBeRead.onscroll = checkReading;
  checkReading.call(oToBeRead);
};
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-element-scrollheight |

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

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

参见
--

* `Element.clientHeight`
* `HTMLElement.offsetHeight`
* 确定元素的尺寸


GlobalEventHandlers.onpointerleave - Web API 接口参考

GlobalEventHandlers.onpointerleave
==================================

就像在`Element`或`Window`中点击类似，在某目标区域内，发生触点（鼠标指针，触摸等）行为时会触发源于 `pointerleave` 事件global event handler行为。这个事件本身属于 Pointer Events API 的一部分。

语法
--
```

var leaveHandler = EventTarget.onpointerleave;

EventTarget.onpointerleave = leaveHandler;
```

### 返回值

`leaveHandler`

`pointerleave` 事件会执行`EventListener` 监听器会委托执行用以发送给目标。

样例
--

这个样例展示了两种使用 `onpointerleave` 来设置元素 `pointerleave` 事件处理器的方式。

```js
<html>
<script>
function leaveHandler(ev) {
 // 执行 pointerleave event 事件
}
function init() {
 var el=document.getElementById("target1");
 el.onpointerleave = leaveHandler;
}
</script>
<body onload="init();">
<div id="target1"> Touch me ... </div>
<div id="target2" onpointerleave="leaveHandler(event)"> Touch me ... </div>
</body>
</html>
```

查看 Using Pointer Events (en-US) 以了解更多详情。

规格
--

| Specification |
| --- |
| Pointer Events # the-pointerleave-event |
| Pointer Events # dom-globaleventhandlers-onpointerleave |

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

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

参考
--

* 相关事件
    + `gotpointercapture`
    + `lostpointercapture`
    + `pointerover`
    + `pointerenter`
    + `pointerdown`
    + `pointermove`
    + `pointerup`
    + `pointercancel`
    + `pointerout`


WEBGL_lose_context.loseContext() - Web API 接口参考

WEBGL\_lose\_context.loseContext()
==================================

\*\*WEBGL\_lose\_context.loseContext()\*\*属于 WebGL API，一般用来模拟 `WebGLRenderingContext` 的上下文丢失。

这个方法会触发 WebGL 规范中上下文丢失的相关事件。通过这个方法丢失的上下文可以通过 `WEBGL_lose_context.restoreContext()` 恢复。

语法
--
```

gl.getExtension('WEBGL_lose_context').loseContext();
```

示例
--

你可以用这个方法模拟 `webglcontextlost` 事件：

```js
var canvas = document.getElementById("canvas");
var gl = canvas.getContext("webgl");

canvas.addEventListener(
  "webglcontextlost",
  function (e) {
    console.log(e);
  },
  false,
);

gl.getExtension("WEBGL\_lose\_context").loseContext();

// webglcontextlost 事件被触发。
```

规范
--

| Specification |
| --- |
| WebGL WEBGL\_lose\_context Khronos Ratified Extension Specification  |

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

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

相关链接
----

* `WebGLRenderingContext.isContextLost()`
* 事件： `webglcontextlost`, `webglcontextrestored` (en-US), `webglcontextcreationerror` (en-US)


WEBGL_lose_context.restoreContext() - Web API 接口参考

WEBGL\_lose\_context.restoreContext()
=====================================

**WEBGL\_lose\_context.restoreContext()** 属于 WebGL API，一般用来模拟 `WebGLRenderingContext` 的上下文恢复。

语法
--
```

gl.getExtension('WEBGL_lose_context').restoreContext();
```

### 抛出错误

* `INVALID_OPERATION` 上下文尚未丢失
示例
--

你可以用这个方法模拟 `webglcontextrestored` (en-US) 事件：

```js
var canvas = document.getElementById("canvas");
var gl = canvas.getContext("webgl");

canvas.addEventListener(
  "webglcontextrestored",
  function (e) {
    console.log(e);
  },
  false,
);

gl.getExtension("WEBGL\_lose\_context").restoreContext();
```

规范
--

| Specification |
| --- |
| WebGL WEBGL\_lose\_context Khronos Ratified Extension Specification  |

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

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

相关链接
----

* `WebGLRenderingContext.isContextLost()`
* 事件： `webglcontextlost`, `webglcontextrestored` (en-US), `webglcontextcreationerror` (en-US)


GPU：getPreferredCanvasFormat() 方法 - Web API 接口参考

GPU：getPreferredCanvasFormat() 方法
=================================

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

`GPU` 接口的 **`getPreferredCanvasFormat()`** 方法返回用于当前系统上显示 8 位色深、标准动态范围（SDR）内容的最佳 canvas 纹理格式。

这通常用于为当前系统提供 `GPUCanvasContext.configure()` 调用的最佳 `format` 值。这是推荐的——如果你没有在配置 canvas 上下文时使用最佳的格式，可能会产生开销，例如根据平台而异的额外纹理的复制。

语法
--

```js
getPreferredCanvasFormat()
```

### 参数

无。

### 返回值

一个字符串，表示 canvas 的纹理格式。该值可以是 `rgba8unorm` 或 `bgra8unorm`。

### 异常

无。

示例
--

```js
const canvas = document.querySelector("#gpuCanvas");
const context = canvas.getContext("webgpu");

context.configure({
  device: device,
  format: navigator.gpu.getPreferredCanvasFormat(),
  alphaMode: "premultiplied",
});
```

规范
--

| Specification |
| --- |
| WebGPU # dom-gpu-getpreferredcanvasformat |

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

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

参见
--

* WebGPU API


GPU：requestAdapter() 方法 - Web API 接口参考

GPU：requestAdapter() 方法
=======================

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

`GPU` 接口的 **`requestAdapter()`** 方法返回一个 `Promise`，该 promise 会使用 `GPUAdapter` 对象实例兑现。这时，你可以请求 `GPUDevice`、适配器信息、特性以及配置。

注意，用户代理会选择是否返回一个适配器。如果可以，它会根据提供的 options 进行选择。如果没有提供 options，设备将提供对默认适配器的访问，这通常足够满足大多数的目的。

语法
--

```js
requestAdapter()
requestAdapter(options)
```

### 参数

`options` 可选

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

`powerPreference` 可选

一个枚举值，可用于为用户代理提供提示，指示应从系统可用的适配器中选择哪类适配器。可用值为：

* `undefined`（或者未指定），不提供提示。
* `"low-power"`，为优先考虑节能而不是性能提供一个提示。如果你的应用程序在此设置下运行正常，建议使用它，因为它可以显著提高便携式设备的电池寿命。如果没有提供 options，这通常是默认值。
* `"high-performance"`，为优先考虑性能而不是功耗提供了一个提示。我们支持你在十分必要时才使用这个值，因为该值会显著地缩短便携式设备的寿命。它也可能导致 `GPUDevice` 损失增加——系统有时会切换到一个低功耗适配去去保存电力。

该提示的主要目的是为了影响在多 GPU 系统中影响哪个 GPU。例如，一些笔记本有低功耗集成 GPU 和高性能独立 GPU。不同的因素可能会影响返回的适配器，包括电池状态、连接的显示器或可更换的 GPU。

### 备用适配器

用户代理提供的适配器可能是**备用适配器**，如果它确定这是可用的最合适选项。备用适配器通常在性能上有着显著的限制，为了换取更广泛的兼容性、更可预测的行为或者更好的隐私保护。例如，一些浏览器可能通过备用的适配器提供一个基于软件的 API 实现。并非每个系统上的备用适配器都可用。

如果你希望阻止你的应用程序运行在备用的适配器，你应该在请求 `GPUDevice` 之前检查 `GPUAdapter.isFallbackAdapter` (en-US) 属性。

**备注：** 该规范包含 `requestAdapter()` 的 `forceFallbackAdapter` 选项。这是一个布尔值，如果设置为 `true`，则强制用户代理返回备用适配器（如果可用）。然而，任何浏览器仍没有支持这一点。

### 返回值

一个 `Promise`，如果请求成功，会兑现一个 `GPUAdapter` 对象实例。

如果未能获取合适的适配器，`requestAdapter()` 将决议为 `null`。

### 异常

无。

示例
--

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  const device = await adapter.requestDevice();

  //...
}
```

规范
--

| Specification |
| --- |
| WebGPU # dom-gpu-requestadapter |

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

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

参见
--

* WebGPU API


Window：requestAnimationFrame() 方法 - Web API 接口参考

Window：requestAnimationFrame() 方法
=================================

**`window.requestAnimationFrame()`** 告诉浏览器——你希望执行一个动画，并且要求浏览器在下次重绘之前调用指定的回调函数更新动画。该方法需要传入一个回调函数作为参数，该回调函数会在浏览器下一次重绘之前执行。

**备注：** 若你想在浏览器下次重绘之前继续更新下一帧动画，那么回调函数自身必须再次调用 `requestAnimationFrame()`。`requestAnimationFrame()` 是一次性的。

当你准备更新在屏动画时你应该调用此方法。这将使浏览器在下一次重绘之前调用你传入给该方法的动画函数（即你的回调函数）。回调函数执行次数通常是每秒 60 次，但在大多数遵循 W3C 建议的浏览器中，回调函数执行次数通常与浏览器屏幕刷新次数相匹配。为了提高性能和电池寿命，在大多数浏览器里，当 `requestAnimationFrame()` 运行在后台标签页或者隐藏的 `<iframe>` 里时，`requestAnimationFrame()` 会被暂停调用以提升性能和电池寿命。

`DOMHighResTimeStamp` 参数会传入回调方法中，它指示当前被 `requestAnimationFrame()` 排序的回调函数被触发的时间。在同一个帧中的多个回调函数，它们每一个都会接受到一个相同的时间戳，即使在计算上一个回调函数的工作负载期间已经消耗了一些时间。该时间戳是一个十进制数，单位为毫秒，最小精度为 1ms（1000μs）。

**警告：** 请确保总是使用第一个参数（或其他一些获取当前时间的方法）来计算动画在一帧中的进度，**否则动画在高刷新率的屏幕中会运行得更快**。请参考下面示例的做法。

语法
--

```js
requestAnimationFrame(callback)
```

### 参数

`callback`

当你的动画需要更新时，为下一次重绘所调用的函数。该回调函数会传入 `DOMHighResTimeStamp` 参数，该参数与 `performance.now()` 的返回值相同，它表示 `requestAnimationFrame()` 开始执行回调函数的时刻。

### 返回值

一个 `long` 整数，请求 ID，是回调列表中唯一的标识。是个非零值，没有别的意义。你可以传这个值给 `window.cancelAnimationFrame()` 以取消回调函数请求。

示例
--

 在这个例子中，一个元素的动画时间是 2 秒（2000 毫秒）。该元素以 0.1px/ms 的速度向右移动，所以它的相对位置（以 CSS 像素为单位）可以通过动画开始后所经过的时间（以
 毫秒）的函数来计算 `0.1 * elapsed`。该元素的最终位置是在其初始位置的右边 200px（`0.1 * 2000`）。

```js
const element = document.getElementById("some-element-you-want-to-animate");
let start, previousTimeStamp;
let done = false;

function step(timestamp) {
  if (start === undefined) {
    start = timestamp;
  }
  const elapsed = timestamp - start;

  if (previousTimeStamp !== timestamp) {
    // 这里使用 Math.min() 确保元素在恰好位于 200px 时停止运动
    const count = Math.min(0.1 \* elapsed, 200);
    element.style.transform = `translateX(${count}px)`;
    if (count === 200) done = true;
  }

  if (elapsed < 2000) {
    // 2 秒之后停止动画
    previousTimeStamp = timestamp;
    if (!done) {
      window.requestAnimationFrame(step);
    }
  }
}

window.requestAnimationFrame(step);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-animationframeprovider-requestanimationframe |

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

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

参见
--

* `Window.cancelAnimationFrame()`
* mozRequestAnimationFrame——博文
* requestAnimationFrame 用于智能动画制作——博文
* 用 JavaScript 做动画：从 setInterval 到 requestAnimationFrame——博文
* TestUFO：测试你的网络浏览器 requestAnimationFrame() 的时间偏差
* Paul Irish：requestAnimationFrame API：现在具有亚毫秒级的精度
* 一个 polyfill


Window.getDefaultComputedStyle() - Web API 接口参考

Window.getDefaultComputedStyle()
================================

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

`getDefaultComputedStyle()` 给出元素的所有 CSS 属性的默认计算值 (computed values )，忽略作者样式。也就是说，只考虑用户代理和用户风格。

语法及参数说明
-------
```

let style = window.getDefaultComputedStyle(element[, pseudoElt]);
```

element

获取计算样式的元素

pseudoElt 可选

指定匹配的伪类。通常情况下可以为空。

返回的样式是一个 `CSSStyleDeclaration` 对象。

例子
--

```js
var elem1 = document.getElementById("elemId");
var style = window.getDefaultComputedStyle(elem1);
```

```js
<style>
#elem-container {
   position: absolute;
   left:     100px;
   top:      200px;
   height:   100px;
 }
</style>

<div id="elem-container">dummy</div>
<div id="output"></div>

<script>
    var elem = document.getElementById("elem-container");
    var theCSSprop = window.getDefaultComputedStyle(elem).position;
    document.getElementById("output").innerHTML = theCSSprop; // 将会输出 "static"
</script>
```

Description
-----------

The returned object is of the same type as the object returned by `getComputedStyle`, but only takes into account user-agent and user rules.

使用伪元素
-----

`getDefaultComputedStyle` 同样可以从伪元素中获取属性 (比如，`::after`, `::before`).

```html
<style>
 h3:after {
 content: " rocks!";
 }
</style>

<h3>generated content</h3>

<script>
 var h3 = document.querySelector("h3"),
 result = getDefaultComputedStyle(h3, ":after").content;

 console.log("the generated content is: ", result); // 返回 'none'
</script>
```

备注
--

The returned value is, in certain known cases, expressly incorrect by deliberate intent. In particular, to avoid the so called CSS History Leak security issue, browsers may expressly "lie" about the used value for a link and always return values as if a user has never visited the linked site, and/or limit the styles that can be applied using the `:visited` pseudo-selector. See http://blog.mozilla.com/security/2010/03/31/plugging-the-css-history-leak/ and http://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/ for details of the examples of how this is implemented.

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

Proposed to the CSS working group.

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

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


AnalyserNode.smoothingTimeConstant - Web API 接口参考

AnalyserNode.smoothingTimeConstant
==================================

`AnalyserNode` 接口的 **`smoothingTimeConstant`** 属性是一个双精度浮点型 (double) 的值，表示最后一个分析帧的平均常数。它基本上是当前缓冲区和 AnalyserNode 处理的最后一个缓冲区之间的平均值，并导致在值变化时随着时间推移得到一个更平滑的集合。

`smoothingTimeConstant` 属性的默认值为 `0.8`; 值的范围必须在 `0` ~ `1` 之间。如果设置为 0，则不进行平均，而值为 1 意味着 "在计算值时重叠上一个缓冲区和当前缓冲区相当多", 它基本上平滑了 `AnalyserNode.getFloatFrequencyData`/`AnalyserNode.getByteFrequencyData` 调用的变化。

在技术术语中，我们应用一个 布莱克曼窗 并随着时间推移去平滑值。大部分情况下，默认值是较好的。

**备注：** 如果设置了 0~1 范围外的值，将会抛出异常`INDEX_SIZE_ERR`.

语法
--

```js
var audioCtx = new AudioContext();
var analyser = audioCtx.createAnalyser();
analyser.smoothingTimeConstant = 1;
```

### 值类型

双精度浮点型 (double).

例子
--

下面的例子展示了 `AudioContext` 创建一个 `AnalyserNode`, 然后用 `requestAnimationFrame` 和 `<canvas>` 去反复收集当前音频的频率数据，并绘制为一个柱状风格的输出 (频谱).

更多的例子/信息，查看 Voice-change-O-matic 演示 (相关代码在 app.js 的 128 行~205 行).

`如果你对 smoothingTimeConstant()` 的效果好奇，可以尝试克隆上面的例子并设置 "`analyser.smoothingTimeConstant = 0;"` 代替。你会发现值的变化更加快速。

```js
var audioCtx = new (window.AudioContext || window.webkitAudioContext)();
var analyser = audioCtx.createAnalyser();
analyser.minDecibels = -90;
analyser.maxDecibels = -10;
analyser.smoothingTimeConstant = 0.85;

  ...

analyser.fftSize = 256;
var bufferLength = analyser.frequencyBinCount;
console.log(bufferLength);
var dataArray = new Uint8Array(bufferLength);

canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);

function draw() {
  drawVisual = requestAnimationFrame(draw);

  analyser.getByteFrequencyData(dataArray);

  canvasCtx.fillStyle = 'rgb(0, 0, 0)';
  canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);

  var barWidth = (WIDTH / bufferLength) \* 2.5;
  var barHeight;
  var x = 0;

  for(var i = 0; i < bufferLength; i++) {
    barHeight = dataArray[i];

    canvasCtx.fillStyle = 'rgb(' + (barHeight+100) + ',50,50)';
    canvasCtx.fillRect(x,HEIGHT-barHeight/2,barWidth,barHeight/2);

    x += barWidth + 1;
  }
};

draw();
```

规范
--

| Specification |
| --- |
| Web Audio API # dom-analysernode-smoothingtimeconstant |

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

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

相关内容
----

* Using the Web Audio API (en-US)


AnalyserNode.getByteTimeDomainData() - Web API 接口参考

AnalyserNode.getByteTimeDomainData()
====================================

`AnalyserNode` 接口的 **`getByteTimeDomainData()`** 方法复制当前波形或时域数据到传递给它的 `Uint8Array` (en-US) (无符号字节数组) 中。

如果该数组的元素少于 `AnalyserNode.fftSize`, 多余的元素会被丢弃。如果它有多于所需的元素，则忽略多余的元素。

语法
--

```js
var audioCtx = new AudioContext();
var analyser = audioCtx.createAnalyser();
var dataArray = new Uint8Array(analyser.fftSize); // Uint8Array should be the same length as the fftSize
analyser.getByteTimeDomainData(dataArray); // fill the Uint8Array with data returned from getByteTimeDomainData()
```

### 参数

`array`

 时域数据将被复制到的 `Uint8Array` (en-US) 。
 如果数组中的元素少于 `AnalyserNode.frequencyBinCount`, 则会删除多余的元素。如果它包含的元素多于需要的元素，则忽略多余的元素。

### 返回值

**`void`** | None

例子
--

以下的例子展示了 `AudioContext` 生成一个 `AnalyserNode` 基础用法，然后通过 `requestAnimationFrame` 和 `<canvas>` 重复的收集和绘制一个当前音频输入的“示波器样式”输出。有关更完整的应用实例/信息，请查看我们的 Voice-change-O-matic demo (有关代码请参阅 app.js lines 128–205)。

```js
var audioCtx = new (window.AudioContext || window.webkitAudioContext)();
var analyser = audioCtx.createAnalyser();

  ...

analyser.fftSize = 2048;
var bufferLength = analyser.frequencyBinCount;
var dataArray = new Uint8Array(bufferLength);
analyser.getByteTimeDomainData(dataArray);

// draw an oscilloscope of the current audio source

function draw() {

      drawVisual = requestAnimationFrame(draw);
      analyser.getByteTimeDomainData(dataArray);

      canvasCtx.fillStyle = 'rgb(200, 200, 200)';
      canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);

      canvasCtx.lineWidth = 2;
      canvasCtx.strokeStyle = 'rgb(0, 0, 0)';

      var sliceWidth = WIDTH \* 1.0 / bufferLength;
      var x = 0;

      ctx.beginPath();
      for(var i = 0; i < bufferLength; i++) {
        let v = dataArray[i]/128.0,
            y = v \* HEIGHT/2;

        if(i === 0)
          canvasCtx.moveTo(x, y);
        else
          canvasCtx.lineTo(x, y);

        x += sliceWidth;
      }

      canvasCtx.lineTo(canvas.width, canvas.height/2);
      canvasCtx.stroke();
    };

    draw();
```

规格
--

| Specification |
| --- |
| Web Audio API # dom-analysernode-getbytetimedomaindata |

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

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

See also
--------

* Using the Web Audio API (en-US)


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

AnalyserNode.AnalyserNode()
===========================

The **`AnalyserNode`** constructor of the Web Audio API creates a new `AnalyserNode` object instance.

Syntax
------
```

var analyserNode = new AnalyserNode(context, options)
```

### 参数

*继承参数自 `AudioNodeOptions` 字典*.

*context*

`AudioContext` 的引用。

*options* 可选

Options are as follows:

* `fftSize`: 用于频域分析的 FFT 初始尺寸。默认值是 2048。
* `maxDecibels`: 用于 FFT 分析的初始最大功率（dB）。默认值是 -30。
* `minDecibels`: 用于 FFT 分析的初始最小功率（dB）。默认值是 -100。
* `smoothingTimeConstant`: 用于 FFT 分析的初始平滑常数。默认值是 0.8。

### 返回值

A new `AnalyserNode` object instance.

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

| Specification |
| --- |
| Web Audio API # dom-analysernode-analysernode |

Browser Compatibility
---------------------

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


AnalyserNode.getFloatFrequencyData() - Web API 接口参考

AnalyserNode.getFloatFrequencyData()
====================================

**`getFloatFrequencyData()`** 作为`AnalyserNode` 接口的方法能将当前分析节点（AnalyserNode）的频率数据拷贝进一个 `Float32Array` (en-US) 数组对象。

此数组表示的频率范围为 0 ~ 22050 Hz，每个元素表示对应频率上的信号分量强度，单位为分贝。

如果你需要更好的性能并且不太在意数据的精度，你可以使用 `AnalyserNode.getByteFrequencyData()` 作为代替，这一接口使用 `Uint8Array` (en-US)来存储数据（对应的也是这个精度的格式）.

语法
--
```

void analyser.getFloatFrequencyData(array);
```

### 参数

`array`

 你即将用于拷贝频域数据（frequency domain data）的 `Float32Array` (en-US) 数组。对于任何无声的样本，它的值应该是 `-Infinity`.
 如果这一数组的可容纳元素数少于该分析节点的`AnalyserNode.frequencyBinCount`值，超出容量的数据元素将被舍弃。而如果容量多于需要，多余的数组元素将不会被操作。

### 返回值

无返回值。

示例
--

```js
const audioCtx = new AudioContext();
const analyser = audioCtx.createAnalyser();
// Float32Array 的长度应该和 frequencyBinCount 相同
const myDataArray = new Float32Array(analyser.frequencyBinCount);
// 用 getFloatFrequencyData() 方法的返回数据填充 Float32Array 数组
analyser.getFloatFrequencyData(myDataArray);
```

### 例：绘制一个频谱

下面的示例展示了一个 `AudioContext`对象连接 `MediaElementAudioSourceNode`到`AnalyserNode 对象的基本用法（即用 AudioContext 将音频内容连接到分析节点，从而可以展开对音频数据的分析）`. 当音频播放时，我们使用 `requestAnimationFrame()`方法产生轮询从而不断地收集频率数据，进而在 `<canvas>` 元素上绘制 winamp（windows 上的一款 MP3 播放软件）条形图风格的频谱。

更多的应用示例和应用信息，可以参看我们 Voice-change-O-matic-float-data 示例 (在 source code 同样有).

```html
<!doctype html>
<body>
  <script>
 const audioCtx = new AudioContext();

 //创建一个音频源
 //在示例中我们使用了一个音频文件，但其实这里也可以用麦克风输入
 const audioEle = new Audio();
 audioEle.src = "my-audio.mp3"; //这里是文件名
 audioEle.autoplay = true;
 audioEle.preload = "auto";
 const audioSourceNode = audioCtx.createMediaElementSource(audioEle);

 //生成一个分析节点 (analyser node)
 const analyserNode = audioCtx.createAnalyser();
 analyserNode.fftSize = 256;
 const bufferLength = analyserNode.frequencyBinCount;
 const dataArray = new Float32Array(bufferLength);

 //设置音频节点网络（音频源->分析节点->输出）
 audioSourceNode.connect(analyserNode);
 analyserNode.connect(audioCtx.destination);

 //生成 2D canvas
 const canvas = document.createElement("canvas");
 canvas.style.position = "absolute";
 canvas.style.top = 0;
 canvas.style.left = 0;
 canvas.width = window.innerWidth;
 canvas.height = window.innerHeight;
 document.body.appendChild(canvas);
 const canvasCtx = canvas.getContext("2d");
 canvasCtx.clearRect(0, 0, canvas.width, canvas.height);

 function draw() {
 //准备好下次重绘
 requestAnimationFrame(draw);

 //获取实时的频谱信息
 analyserNode.getFloatFrequencyData(dataArray);

 //画一个黑色的背景
 canvasCtx.fillStyle = "rgb(0, 0, 0)";
 canvasCtx.fillRect(0, 0, canvas.width, canvas.height);

 //绘制频谱
 const barWidth = (canvas.width / bufferLength) \* 2.5;
 let posX = 0;
 for (let i = 0; i < bufferLength; i++) {
 const barHeight = (dataArray[i] + 140) \* 2;
 canvasCtx.fillStyle =
 "rgb(" + Math.floor(barHeight + 100) + ", 50, 50)";
 canvasCtx.fillRect(
 posX,
 canvas.height - barHeight / 2,
 barWidth,
 barHeight / 2,
 );
 posX += barWidth + 1;
 }
 }

 draw();
 </script>
</body>
```

规范
--

| Specification |
| --- |
| Web Audio API # dom-analysernode-getfloatfrequencydata |

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

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

See also
--------

* Using the Web Audio API (en-US)