拖拽操作 - Web API 接口参考

拖拽操作
====

本文描述了拖放操作中发生的步骤。

本文档中描述的拖动操作使用 `DataTransfer` 接口。本文档不使用 `DataTransferItem` 接口和 `DataTransferItemList` 接口。

可拖拽（`draggable`）属性
------------------

在一个网页中，有几种特定情况会使用默认拖拽行为，其中包括拖拽选中文本、拖拽图像和拖拽链接。当一个图像或链接被拖拽时，图像或链接的 URL 被设定为拖拽数据。对于其他元素，只当它们是被选中的一部分时，才会触发默认拖拽行为。如果想看看拖拽实际的样子，可以选中网页的一部分，然后按住鼠标，拖动选中的目标。选中的部分根据系统的不同会有不同的渲染效果，并在拖拽时跟随着鼠标指针。然而，这只是默认拖拽行为的效果，此时没有监听程序调整拖拽数据。

在 HTML 中，除了图像、链接和选择的文本默认的可拖拽行为之外，其他元素在默认情况下是不可拖拽的。

要使其他的 HTML 元素可拖拽，必须做三件事：

* 将想要拖拽的元素的 `draggable` 属性设置成 `"true"`。
* 为 `dragstart` 事件添加一个监听程序。
* 在上一步定义的监听程序中 `设置拖拽数据`。

下面的例子允许拖拽一个段落的内容：
```

<p draggable="true" ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')">
  This text <strong>may</strong> be dragged.
</p>
```

属性 `draggable` 设置为 `"true"`，所以这个元素变成可拖拽的。如果该属性被省略或被设置为 `"false"`，则该元素将不可拖拽，此时拖拽只会选中文本。

`draggable` 属性可在任意元素上设置，包括图像和链接。然而，对于后两者，该属性的默认值是 `true`，所以你只会在禁用这二者的拖拽时使用到 `draggable` 属性，将其设置为 `false`。

**备注：** 当一个元素被设置成可拖拽时，元素中的文本和其他子元素不能再以正常的方式（通过鼠标点击和拖拽）被选中。用户必须按住 `alt` 键，再用鼠标选择文本，或者使用键盘选择。

开始拖拽操作
------

这个例子使用 `ondragstart` (en-US) 属性为 `dragstart` 事件添加监听程序。
```

<p draggable="true" ondragstart="event.dataTransfer.setData('text/plain', 'This text may be dragged')">
  This text <strong>may</strong> be dragged.
</p>
```

当用户开始拖拽时，会触发 `dragstart` 事件。

在这个例子中，`dragstart` 事件监听程序被添加到可拖拽元素本身；然而，你可以监听一个祖先元素，因为就像大多数其他事件一样，拖拽事件会冒泡。

在 `dragstart` 事件中，你可以指定拖拽数据、反馈图像和拖拽效果，所有这些都将在下面描述。不过，我们只需要设置拖拽数据，因为在大多数情况下默认的图像和拖拽效果都是适用的。

拖拽数据
----

所有`拖拽事件`都有一个名为 `dataTransfer` 的属性，它持有拖拽数据（`dataTransfer` 是一个 `DataTransfer` 对象）。

当拖拽发生时，数据必须与被拖拽的项目相关联。例如，当在文本框中拖拽选定的文本时，与拖拽数据项相关联的数据就是文本本身。类似地，当在 Web 页面上拖拽链接时，拖拽数据项就是链接的 URL。

`DataTransfer` 包含两个信息，数据的类型（或格式）和数据值。格式是一个类型字符串（例如文本数据的格式是 `text/plain` (en-US)），值是一个文本字符串。拖拽开始时，你提供数据类型和数据值。在拖拽过程中，在 `dragenter` 和 `dragover` 事件监听程序中，你使用拖拽数据的类型来检查是否允许放置（drop）。例如，接受链接的放置目标将检查链接类型 `text/uri-list` (en-US)。在放置事件中，监听程序将取回拖拽数据，并将其插入到放置位置。

`DataTransfer` 的 `types` 属性返回一个类似 `DOMString` 的 MIME-type 的列表，如 `text/plain` (en-US) 或 `image/jpeg` (en-US)。你还可以创建自己的类型。最常用的类型列在文章 推荐拖拽类型 中。

一次拖拽可能包括几个不同类型的数据项。这使得数据可以更具体的类型提供，通常是自定义类型，但若放置目标不支持这些具体类型，则会提供回退（fallback）数据。通常情况下，最不具体的类型是 `text/plain` (en-US) 类型的普通文本数据，即一些简单的文本表示。

要在 `dataTransfer` 中设置拖拽数据项，使用 `setData()` 方法。这个方法接收两个参数，即数据类型和数据值。例如：

```js
event.dataTransfer.setData("text/plain", "Text to drag");
```

在这个例子中，数据值是“Text to drag”，数据类型是 `text/plain` (en-US) 格式。

你可以提供多种格式的数据。要做到这一点，可以用不同的格式多次调用 `setData()` 方法。你应该传入尽量具体的格式。

```js
const dt = event.dataTransfer;
dt.setData("application/x.bookmark", bookmarkString);
dt.setData("text/uri-list", "http://www.mozilla.org");
dt.setData("text/plain", "http://www.mozilla.org");
```

在这里，数据被添加到三种不同的类型中。第一个类型 `application/x-bookmark` 是一种自定义类型。其他应用程序不会支持这个类型，但你可以在同一站点或同以应用程序之间使用自定义类型。

通过提供其他类型的数据，我们还可使用不那么具体的形式支持拖拽到其他应用程序。`application/x.bookmark` 类型可以提供更多的数据，以便在应用程序中使用，而另两个类型则只包含一个 URL 或文本版本。

注意，在本例中，`text/uri-list` (en-US) 和 `text/plain` (en-US) 包含相同的数据。这通常是正确的，但不一定要这么做。

如果你试图以相同的格式添加两次数据，那么新的数据将替换旧的数据。你可以使用 `clearData()` 方法清除这些数据，该方法接收一个参数，即要删除的数据类型。

```js
event.dataTransfer.clearData("text/uri-list");
```

`clearData()` 方法的 `type` 参数是可选的。如果没有声明 `type`，则所有类型的数据都会被删除。如果拖拽不包含拖拽数据项，或者所有的数据项都被清除，那么就不会出现拖拽行为。

设置拖拽反馈图像
--------

当拖拽发生时，会生成拖拽目标的一个半透明图像（触发"`dragstart`" 事件的元素），并在拖拽过程中跟踪鼠标指针。这个图像是自动创建的，所以你不需要自己创建它。但是，你可以使用 `setDragImage()` 方法来自定义拖拽反馈图像。

```js
event.dataTransfer.setDragImage(image, xOffset, yOffset);
```

这三个参数都是必要的。第一个是图像的引用。这个引用通常是一个 `<img>` 元素，但也可以是 `<canvas>` 或任何其他元素。生成的反馈图像就是该图像在屏幕上的样子，以图像原始的大小绘制。`setDragImage()` 方法的第二、三个参数是图像位置相对于鼠标指针位置的偏移量。

也可以使用不在文档中的图像和画布。这种技术在使用 canvas 元素绘制自定义的拖拽反馈图像时非常有用，如下面的例子：

```js
function dragWithCustomImage(event) {
  var canvas = document.createElementNS(
    "http://www.w3.org/1999/xhtml",
    "canvas",
  );
  canvas.width = canvas.height = 50;

  var ctx = canvas.getContext("2d");
  ctx.lineWidth = 4;
  ctx.moveTo(0, 0);
  ctx.lineTo(50, 50);
  ctx.moveTo(0, 50);
  ctx.lineTo(50, 0);
  ctx.stroke();

  var dt = event.dataTransfer;
  dt.setData("text/plain", "Data to Drag");
  dt.setDragImage(canvas, 25, 25);
}
```

在这个例子中，我们做了一个是画布的拖拽图像。当画布宽 50 像素，高 50 像素时，我们使用一半的偏移量（25 和 25），这样鼠标指针即为图像中心。

拖拽效果
----

拖拽过程中可能会执行一些操作。`copy` 操作用来指示被拖拽的数据将从当前位置复制到放置位置。`move` 操作指示被拖拽的数据会被移动，`link` 操作表示在源和放置位置之间将会创建某种形式的关系或连接。

你可以在 `dragstart` 事件监听程序中设置 `effectAllowed` 属性以指定允许拖拽源头执行三种操作中的哪几种。

```js
event.dataTransfer.effectAllowed = "copy";
```

在这个例子中，只允许复制操作。

你可以不同的方式组合这些值：

`none`

不允许操作

`copy`

只复制

`move`

只移动

`link`

只链接

`copyMove`

复制或移动

`copyLink`

复制或链接

`linkMove`

链接或移动

`all`

复制、移动或链接

注意，这些值必须像上面列出的那样使用。例如，将 `effectAllowed` 属性设置为 `copyMove` 允许复制或移动操作，但阻止用户执行链接操作。属性默认允许以上所有的操作（all），所以你不需要调整这个属性，除非你想要排除某个特定操作。

在拖拽操作期间，`dragenter` 或 `dragover` 事件的监听程序可以检查 `effectAllowed` 属性，以查看哪些操作是允许的。相关的 `dropEffect` 属性应该在其中的一个事件中设置，来指定应该执行哪一个单项操作。`dropEffect` 是 `none`、`copy`、`move` 或 `link`。这个属性不使用上述的组合值。

在 `dragenter` 和 `dragover` 事件中，`dropEffect` 属性被初始化为用户请求的效果。用户可以通过按下修饰键来修改为所需的效果。尽管使用什么修饰键取决于不同的平台，但典型情况下，`Shift` 和 `Ctrl` 键用于在复制、移动和链接之间切换。鼠标指针会改变样式以指示需要的操作；例如，对于"复制"操作，光标可能会在旁边出现加号。

你可以在 `dragenter` 或 `dragover` 事件期间修改 `dropEffect` 属性，例如将某个放置目标设置为只支持某些操作。你可以修改 `dropEffect` 属性来覆盖用户指定的效果，并强制修改为一个特定的放置操作。注意，这个效果必须是 `effectAllowed` 属性中的一个。否则，它将被设置为允许的替代值。

```js
event.dataTransfer.dropEffect = "copy";
```

在这个例子中，放置效果是复制。

你可以使用 `none` 表示在这个位置不允许任何放置，尽管在这种情况下，最好不要取消事件。

在 `drop` 和 `dragend` 事件中，你可以检查 `dropEffect` 属性，以确定最终选择了哪种效果。如果所选的效果是 `"move"`，那么应该在 `dragend` 事件中从拖拽源头删除拖拽数据。

指定放置目标
------

`dragenter` 或 `dragover` 事件的监听程序用于表示有效的放置目标，也就是被拖拽项目可能放置的地方。网页或应用程序的大多数区域都不是放置数据的有效位置。因此，这些事件的默认处理是不允许放置。

如果你想要允许放置，你必须取消 `dragenter` 和 `dragover` 事件来阻止默认的处理。你可以在属性定义的事件监听程序返回 `false`，或者调用事件的 `preventDefault()` 方法来实现这一点。在一个独立脚本中的定义的函数里，可能后者更可行。

```html
<div ondragover="return false"></div>
<div ondragover="event.preventDefault()"></div>
```

在 `dragenter` 和 `dragover` 事件中调用 `preventDefault()` 方法将表明在该位置允许放置。但是，你通常希望只在某些情况下调用 `preventDefault()` 方法（如只当拖拽的是链接时）。

要做到这一点，调用一个函数以检查条件，并且只在满足条件时取消事件。如果条件未满足，则不取消事件，此时用户释放鼠标按钮不会执行放置。

最常见的是根据数据传输中拖拽数据的类型来接受或拒绝放置——例如，允许放置图像或链接，或者都允许。你可以检查 `dataTransfer` 属性的 `types` 属性来查看哪些类型允许放置。`types` 属性返回一个字符串类型的数组，这些字符串类型是在拖拽开始时添加的，顺序是从最重要到最不重要。

```js
function contains(list, value) {
  for (var i = 0; i < list.length; ++i) {
    if (list[i] === value) return true;
  }
  return false;
}

function doDragOver(event) {
  var isLink = contains(event.dataTransfer.types, "text/uri-list");
  if (isLink) {
    event.preventDefault();
  }
}
```

在本例中，我们使用 `includes` 方法来检查 `text/uri-list` (en-US) 是否出现在类型列表中。如果出现了，我们将取消这个事件以允许放置。如果拖拽数据不包含链接，则不取消事件，此位置也不允许放置。

如果你希望更具体地限制操作类型，你可能还需要设置 `effectAllowed` 或 `dropEffect` 属性，或者两者都设置。当然，如果你不取消这个事件，改变这两个属性不会有任何效果。

放置反馈
----

有几种方法可以向用户表明哪个位置允许放置。鼠标指针将根据 `dropEffect` 属性的值做必要的更新。鼠标指针具体的外观取决于用户平台，典型的如加号图标会出现在 '`copy`' 中，而不允许放置时，会出现禁止放置的图标。在许多情况下，鼠标指针反馈就足够了。

但是，你还可以根据需要更新用户界面，如添加一个插入标记或使用高亮显示。对于简单的高亮显示，你可以在放置目标上使用 `-moz-drag-over` CSS 伪类。

```css
.droparea:-moz-drag-over {
  border: 1px solid black;
}
```

在这个例子中，当带有 `droparea` 类的元素是一个有效的放置目标时，即在该元素的 `dragenter` 事件中调用 `preventDefault()` 方法时，元素会出现一个 1 像素的黑色轮廓。

**备注：** 要使这个伪类生效，你必须在 `dragenter` 事件中调用 `preventDefault()` 方法，因为这个伪类状态不会检查 `dragover` 事件（译者注：即在 `dragover` 事件中调用 `preventDefault()` 方法也不会使伪类生效，尽管这个伪类叫做“-moz-drag-over”）。

对于更复杂的视觉效果，你可以在 `dragenter` 事件中执行其他操作。例如在放置位置插入一个元素，这样的元素可以表示一个插入标记，或表示被拖拽的元素移动到了新位置。为此你可以在 `dragenter` 事件中创建一个新元素，然后将其插入到文档中。

`dragover` 事件在鼠标指向的元素上触发。自然，你可能需要将插入标记移动到事件发生的位置附近。你可以使用事件的 `clientX` 和 `clientY` 属性，还有其他鼠标事件的属性来确定鼠标的位置。

最后，`dragleave` 事件会在拖拽离开元素时在该元素上触发。这是移除插入标记或高亮的好时机。你不需要取消这个事件（译者注：即不需要使用 `preventDefault()`）。使用 `-moz-drag-over` 伪类设置的高亮或其他视觉效果会被自动移除。即使拖拽被取消了，`dragleave` 事件也会照常触发，所以你可以确保在这个事件中对任何插入标记的清除操作都一定可以完成。

执行放置
----

当用户放开鼠标，拖放操作就会结束。

如果在有效的放置目标元素（即取消了 `dragenter` 或 `dragover` 的元素）上放开鼠标，放置会成功实现，`drop` 事件在目标元素上被触发。否则，拖拽会被取消，不会触发 `drop` 事件。

在 `drop` 事件中，你应该取回放置的数据并将其插入到放置的位置。你可以使用 `dropEffect` 属性来确定需要哪种拖拽操作。

在所有拖拽操作相关的事件中，事件的 `dataTransfer` 属性会一直保存着拖拽数据。可使用 `getData()` 方法来取回数据。
```

function onDrop(event) {
  const data = event.dataTransfer.getData("text/plain");
  event.target.textContent = data;
  event.preventDefault();
}
```

`getData()` 方法接收一个参数，取回数据的类型。这个方法会返回拖拽操作开始时调用 `setData()` 方法设置的字符串值。如果不存在传入类型的数据，则会返回空字符串。自然，你应该知道哪种类型的数据可用，因为之前你应该已经在 `dragover` 事件中检查过数据类型了。

在上面的例子中，我们一取回数据就把它作为文本内容插入到目标中。实际效果就是拖拽文本被插入到放置位置，假设放置目标是文本区域，例如 `p` 或 `div` 元素。

在一个网页中，如果你想接收一个放置，不想让浏览器的默认处理程序处理放置数据，你应该调用事件的 `preventDefault()` 方法。例如，当拖拽一个链接到网页时，Firefox 会打开这个链接。而你可以通过取消事件来阻止这样的行为。

你可以取回其他类型的数据。如果数据是一个链接，其类型应为 `text/uri-list` (en-US)。你可以将链接插入到内容中。
```

function doDrop(event) {
  const lines = event.dataTransfer.getData("text/uri-list").split("\n");
  lines.filter(line => !line.startsWith("#"))
    .forEach(line => {
      const link = document.createElement("a");
      link.href = line;
      link.textContent = line;
      event.target.appendChild(link);
    })
  event.preventDefault();
}
```

这个例子使用拖拽数据插入链接。顾名思义，`text/uri-list` (en-US) 类型可包含一个 URL 列表，每行一个 URL。在上述代码中，我们使用 split (en-US) 方法将字符串按行分割，然后迭代列表的每一行，将每一个链接都插入到文档中。注意到我们跳过了井号（#）开头的链接，因为那些只是注释。

在简单的情况中，你可以使用一个特别的类型 `URL` 来取回列表中第一个有效的 URL。例如：

```js
var link = event.dataTransfer.getData("URL");
```

这样就不需要检查注释或者迭代每一行了。但这样就只能取回列表中的第一个 URL。

`URL` 类型是一个特别的类型，只作为简写类型，不在 `types` 属性规定的类型列表中出来。

有时你可能支持不同的格式，而你希望取回数据的格式是支持格式中最具体的一种。在这个例子中，放置目标支持三种格式。

下面的例子返回格式支持最佳的数据：
```

function doDrop(event) {
  const supportedTypes = ["application/x-moz-file", "text/uri-list", "text/plain"];
  const types = event.dataTransfer.types.filter(type => supportedTypes.includes(type));
  if (types.length) {
    const data = event.dataTransfer.getData(types[0]);
  }
  event.preventDefault();
}
```

完成拖拽
----

一旦拖拽完成，`dragend` 事件会在拖拽源头（即触发 `dragstart` 的元素）上发生。无论拖拽是成功还是被取消，这个事件都会被触发。然而，你可以使用 `dropEffect` 属性来决定执行什么放置操作。

如果在 `dragend` 事件中，`dropEffect` 属性值为 `none`，则拖拽会被取消。否则，这个属性会规定需要执行什么操作。源头元素可使用这个信息以在拖拽操作完成后从原来的位置移除被拖拽的项目。`mozUserCancelled` 属性会在用户取消拖拽（按下 Esc 键）时设置为 true，在拖拽因为其他原因如无效放置目标等被取消时，或拖拽成功时，则设置为 false。

放置可发生在同一窗口或另一个应用程序中。两种情况都会触发 `dragend` 事件。事件的 `screenX` 和 `screenY` 属性会被设置为放置发生时鼠标在屏幕上的坐标。

`dragend` 事件结束后，整个拖放操作就完成了。

[1] 在 Gecko 内核中，如果源头节点在拖拽过程中（如放置或 `dragover` 中）被移动或移除了，则不会触发 `dragend` 事件。参见 bug 460801。

参见
--

* HTML Drag and Drop API (Overview)
* Recommended Drag Types (en-US)
* HTML5 Living Standard: Drag and Drop


推荐拖动类型 - Web API 接口参考

推荐拖动类型
======

HTML 拖放支持拖动各种类型的数据，包括纯文本，URL，HTML 代码，文件等。该文档描述了拖放常见数据类型的最佳做法。

**警告：** 本文档中包含一个**moz**前缀的所有方法和属性 (如**mozSetDataAt()**) 是 Gecko 的具体接口。这些接口仅适用于基于 Gecko 的浏览器。

拖动文字
----

拖动文字时请使用 `text/plain` 类型，那么数据必须是字符串，例如：
```

event.dataTransfer.setData("text/plain", "This is text to drag")
```

拖动文本框中的文字和页面选中部分的文字是自动完成的，所以你不需要手动处理这些拖动。

如果应用和拖动目标不支持其他类型，推荐你使用 `text/plain` 类型的数据进行填充，否则将没有默认的替代文字。建议总是在最后添加原始文字类型的数据做为备选项（译者 plter 注：如果拖动开始时没有设置数据，则在有些浏览器中后续拖动相关事件可能不会触发）。

注：在旧代码中，可能会使用 `text/unicode` 或者 `Text` 类型，这两个与 `text/plain` 是一样的，并且应该被替换用于存储和提取数据。

拖动链接
----

Links should include data of two types; the first should be the URL using the type `text/uri-list`, and the second is the URL using the `text/plain` type. Both types should use the same data, the URL of the link. For example:
```

var dt = event.dataTransfer;
dt.setData("text/uri-list", "http://www.mozilla.org");
dt.setData("text/plain", "http://www.mozilla.org");
```

As usual, set the `text/plain` type last as it is less specific than the uri type.

Note: the URL type is `uri-list` with an 'I', not with an 'L'.

To drag multiple links, you can also separate each link with a linebreak. A line that begins with a number sign (#) is a comment and should not be considered a valid URL. You can use a comment to indicate the purpose of a link, or to hold the title associated with a link. The `text/plain` version of the drag data should include all links but should not include the comments.

For example:
```

http://www.mozilla.org
#A second link
http://www.example.com
```

This sample `text/uri-list` data contains two links and a comment.

When retrieving a dropped link, you should ensure you handle the case where multiple links may have been dragged, including any comments that appear in the data. For convenience, the special type `URL` may be used to refer to the first valid link within the data for the `text/uri-list` type. You should not add data using the `URL` type; attempting to do so will just set the value of the `text/uri-list` type instead.
```

var url = event.dataTransfer.getData("URL");
```

You may also see data using the Mozilla specific type `text/x-moz-url`. If it appears, it should be used before the `text/uri-list` type. It holds the URL of the link followed by the title of the link, separated by a linebreak. For example:
```

http://www.mozilla.org
Mozilla
http://www.example.com
Example
```

拖动 HTML 和 XML
-------------

HTML content may use the `text/html` type. The data for this type should be the serialized HTML to drag. For instance, it would be suitable to set the data value for this type to the value of the `innerHTML` property of an element.

XML content may use the `text/xml` type, but you should ensure that the data value is well-formed XML.

You may also include a plain text representation of the HTML or XML data using the `text/plain` type. The data should be just the text and should not include any of the source tags or attributes. For instance:
```

var dt = event.dataTransfer;
dt.setData("text/html", "Hello there, <strong>stranger</strong>");
dt.setData("text/plain", "Hello there, stranger");
```

拖动文件
----

A local file is dragged using the `application/x-moz-file` type with a data value that is an nsIFile object. Non-privileged web pages are not able to retrieve or modify data of this type. Because a file is not a string, you must use the `mozSetDataAt()` method to assign the data. Similarly, when retrieving the data, you must use the `mozGetDataAt()` method.
```

event.dataTransfer.mozSetDataAt("application/x-moz-file", file, 0);
```

If possible, you may also include the file URL of the file using both the `text/uri-list` and/or `text/plain` types. These types should be added last so that the more specific `application/x-moz-file` type has higher priority.

The following example shows how to create an area for receiving dropped files:
```

<listbox ondragenter="return checkDrag(event)"
         ondragover="return checkDrag(event)"
         ondrop="doDrop(event)"/>

<script>
function checkDrag(event)
{
  return event.dataTransfer.types.contains("application/x-moz-file");
}

function doDrop(event)
{
  var file = event.dataTransfer.mozGetDataAt("application/x-moz-file", 0);
  if (file instanceof Components.interfaces.nsIFile)
    event.currentTarget.appendItem(file.leafName);
}
</script>
```

In this example, the event returns false only if the data transfer contains the `application/x-moz-file` type. During the drop event, the data associated with the file type is retrieved, and the filename of the file is added to the listbox. Note that the `instanceof` operator is used here as the `mozGetDataAt()` method will return an `nsISupports` that needs to be checked and converted into an nsIFile. This is also a good extra check in case someone made a mistake and added a non-file for this type.

### 更新 DataTransfer.types

Note that the latest spec now dictates that `DataTransfer.types` should return a frozen array of `DOMString`s rather than a `DOMStringList` (this is supported in Firefox 52 and above).

As a result, the contains method no longer works on the property; the includes method should be used instead to check if a specific type of data is provided, using code like the following:

```js
if ([...event.dataTransfer.types].includes("text/html")) {
  // Do something
}
```

You could always use some feature detection to determine which method is supported on `types`, and run code as appropriate.

拖动图像
----

Direct image dragging is not commonly done. In fact, Mozilla does not support direct image dragging on Mac or Linux platforms. Instead, images are usually dragged only by their URLs. To do this, use the `text/uri-list` type as with other URL links. The data should be the URL of the image or a data URL if the image is not stored on a web site or disk. For more information about data URLs, see the data URL scheme.

As with other links, the data for the `text/plain` type should also contain the URL. However, a data URL is not usually as useful in a text context, so you may wish to exclude the `text/plain` data in this situation.

In chrome or other privileged code, you may also use the `image/jpeg`, `image/png` or `image/gif` types, depending on the type of image. The data should be an object which implements the nsIInputStream interface. When this stream is read, it should provide the data bits for the image, as if the image was a file of that type.

You should also include the `application/x-moz-file` type if the image is located on disk. In fact, this a common way in which image files are dragged.

It is important to set the data in the right order, from most specific to least specific. The image type such as `image/jpeg` should come first, followed by the `application/x-moz-file` type. Next, you should set the `text/uri-list` data and finally the `text/plain` data. For example:
```

var dt = event.dataTransfer;
dt.mozSetDataAt("image/png", stream, 0);
dt.mozSetDataAt("application/x-moz-file", file, 0);
dt.setData("text/uri-list", imageurl);
dt.setData("text/plain", imageurl);
```

Note the `mozGetDataAt()` method is used for non-text data. As some contexts may only include some of these types, it is important to check which type is made available when receiving dropped images.

拖动节点
----

Nodes and elements in a document may be dragged using the `application/x-moz-node` type. The data for the type should be a DOM node. This allows the drop target to receive the actual node where the drag was started from. Note that callers from a different domain will not be able to access the node even when it has been dropped.

You should always include a plain text alternative for the node.

拖动自定义数据
-------

You can also use other types that you make up for custom purposes. You should strive to always include a plain text alternative unless that object being dragged is specific to a particular site or application. In this case, the custom type ensures that the data cannot be dropped elsewhere.

将文件拖动到一个操作系统文件夹
---------------

There are cases in which you may want to add a file to an existing drag event session, and you may also want to write the file to disk when the drop operation happens over a folder in the operating system when your code receives notification of the target folder's location. This only works in extensions (or other privileged code) and the data type "application/moz-file-promise" should be used. The following sample offers an overview of this advanced case:

```js
// currentEvent is a given existing drag operation event

currentEvent.dataTransfer.setData("text/x-moz-url", URL);
currentEvent.dataTransfer.setData("application/x-moz-file-promise-url", URL);
currentEvent.dataTransfer.setData(
  "application/x-moz-file-promise-dest-filename",
  leafName,
);
currentEvent.dataTransfer.mozSetDataAt(
  "application/x-moz-file-promise",
  new dataProvider(success, error),
  0,
  Components.interfaces.nsISupports,
);

function dataProvider() {}

dataProvider.prototype = {
  QueryInterface: function (iid) {
    if (
      iid.equals(Components.interfaces.nsIFlavorDataProvider) ||
      iid.equals(Components.interfaces.nsISupports)
    )
      return this;
    throw Components.results.NS\_NOINTERFACE;
  },
  getFlavorData: function (aTransferable, aFlavor, aData, aDataLen) {
    if (aFlavor == "application/x-moz-file-promise") {
      var urlPrimitive = {};
      var dataSize = {};

      aTransferable.getTransferData(
        "application/x-moz-file-promise-url",
        urlPrimitive,
        dataSize,
      );
      var url = urlPrimitive.value.QueryInterface(
        Components.interfaces.nsISupportsString,
      ).data;
      console.log("URL file orignal is = " + url);

      var namePrimitive = {};
      aTransferable.getTransferData(
        "application/x-moz-file-promise-dest-filename",
        namePrimitive,
        dataSize,
      );
      var name = namePrimitive.value.QueryInterface(
        Components.interfaces.nsISupportsString,
      ).data;

      console.log("target filename is = " + name);

      var dirPrimitive = {};
      aTransferable.getTransferData(
        "application/x-moz-file-promise-dir",
        dirPrimitive,
        dataSize,
      );
      var dir = dirPrimitive.value.QueryInterface(
        Components.interfaces.nsILocalFile,
      );

      console.log("target folder is = " + dir.path);

      var file = Cc["@mozilla.org/file/local;1"].createInstance(
        Components.interfaces.nsILocalFile,
      );
      file.initWithPath(dir.path);
      file.appendRelativePath(name);

      console.log("output final path is =" + file.path);

      // now you can write or copy the file yourself...
    }
  },
};
```

参见
--

* HTML Drag and Drop API (Overview)
* Drag Operations (en-US)
* HTML5 Living Standard: Drag and Drop


HTMLImageElement.referrerPolicy - Web API 接口参考

HTMLImageElement.referrerPolicy
===============================

**`HTMLImageElement.referrerPolicy`** 反映了 `<img>` 元素的 HTML 属性 `referrerpolicy` 的定义，这个属性定义了`<img>` 元素在获取资源时的引用方式。

语法
--
```

refStr = imgElt.referrerPolicy;
imgElt.referrerPolicy = refStr;
```

### 值

* `"no-referrer"` 表示 HTTP 头部信息将不会发送 `referrer` 。
* `"origin"` 表示 referrer 只包含策略、主机名、端口等页面源的信息。
* `"unsafe-url"` 这意味着引用者将包括源站和路径（但不包括片段、密码或用户名）。这种情况是不安全的，因为它可能会泄漏路径信息，这些信息已被使用 TLS 隐藏到第三方。
示例
--

```js
var img = new Image();
img.src = "img/logo.png";
img.referrerPolicy = "origin";

var div = document.getElementById("divAround");
div.appendChild(img); // Fetch the image using the origin as the referrer
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-referrerpolicy |

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

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

参见
--

* `HTMLAnchorElement.referrerPolicy`、`HTMLAreaElement.referrerPolicy` (en-US) 和 `HTMLIFrameElement.referrerPolicy` (en-US)


HTMLImageElement.srcset - Web API 接口参考

HTMLImageElement.srcset
=======================

`HTMLImageElement` 的 **`srcset`** 的值是一个字符串，用来定义一个或多个图像候选地址，以 `,` 分割，每个候选地址将在特定条件下得以使用。候选地址包含图片 URL 和一个可选的宽度描述符和像素密度描述符，该候选地址用来在特定条件下替代原始地址成为 `src` (en-US) 的属性。

`srcset`属性和`sizes` (en-US) 属性是响应式网页设计中至关重要的组件，可以搭配使用来创建根据展示场景使用图像的页面。

语法
--
```

htmlImageElement.srcset = imageCandidateStrings;
let srcset = htmlImageElement.srcset;
```

### 值

一个包含单个或多个以逗号分隔的图像候选列表`USVString` ，表示在`<img>`里可以展示哪些图片。

每个图像候选字符串必须以有效 URL 开头，指向一个非交互的图形资源。紧接着是一个逗号 (`,`) 字符。最后是一个条件描述符，该描述符定义了在什么环境下使用该图像。除了分隔 URL 和相应条件描述符的空格之外的空格字符都将被忽略，包括头部和末尾的空格，以及每个逗号前后的空格。

如果没有提供条件描述符（也就是说，图像候选字符只含一个 URL），并没有命中的其他候选，则使用该候选作为回退方案。否则，条件描述符可以采用以下两种形式之一：

* 要指定在某个宽度下使用特定图像候选代表的图像资源，请提供 **宽度描述符**，包含表示该宽度的数字（以像素为单位）+ 小写字母“w”。例如，渲染一个 450 像素宽的图像对应的描述符字符串： `450w`。指定的宽度必须是正数、非零整数，并且*必须*与引用图像的固有宽度相匹配。
* 或者，你可以使用**像素密度描述符**，它指定了在什么样的显示器像素密度下应用相应的图像资源。它是通过将像素密度声明为正的非零浮点值，后跟小写字母“x”来编写的。例如，要指定在像素密度是标准密度的两倍时使用相应的图像，你可以提供像素密度描述符 `2x` 或 `2.0x`。< /li>

你可以混合使用这两种类型的描述符。但是，你不能为同一个描述符指定多个图像候选字符。以下都是有效的图像候选字符串：
```

"images/team-photo.jpg 1x, images/team-photo-retina.jpg 2x, images/team-photo-full 2048w"
```

此字符串指定了在标准像素密度 (`1x`) 以及两倍像素密度 (`2x`) 下使用的图像版本。还可以使用宽度为 2048 像素 (`2048w`) 的图像版本。
```

"header640.png 640w, header960.png 960w, header1024.png 1024w, header.png"
```

此字符串指定了在 user agent's 需要渲染宽度为 640px、960px 或 1024px 的图像时使用的图像版本。以及一个额外的备用图像候选，没有任何条件，可用于任意宽度。
```

"icon32px.png 32w, icon64px.png 64w, icon-retina.png 2x icon-ultra.png 3x icon.svg"
```

这里，为宽度为 32 像素和 64 像素以及像素密度为 2 倍和 3 倍的图标提供了选项。备用图像以 SVG 文件的形式提供，它可在所有情况下使用。请注意，图像候选可使用不同的图像类型。

有关可用于 `<img>` 元素的图像格式的详细信息，请参阅 图片文件类型和格式指南 。

示例
--

### HTML

下面的 HTML 表明图像的默认宽度是 200 像素。 `srcset` 属性还指定了 200 像素版本应用于 1x 显示器，而 400 像素版本应用于 2x 显示器。

```html
<div class="box">
  <img
 src="https://yari-demos.prod.mdn.mozit.cloud/zh-CN/docs/web/html/element/img/clock-demo-200px.png"
 alt="Clock"
 srcset="
 https://yari-demos.prod.mdn.mozit.cloud/zh-CN/docs/web/html/element/img/clock-demo-200px.png 1x,
 https://yari-demos.prod.mdn.mozit.cloud/zh-CN/docs/web/html/element/img/clock-demo-400px.png 2x
 " />
</div>
```

### CSS

CSS 仅指定图像及其父盒子的宽为 200 像素，并有一个简单的边框。还提供了 `word-break` 属性，使用 `break-all` 值告诉浏览器将字符串包在可用宽度内。

```css
.box {
  width: 200px;
  border: 2px solid rgba(150, 150, 150, 255);
  padding: 0.5em;
  word-break: break-all;
}

.box img {
  width: 200px;
}
```

### JavaScript

The following code is run within a handler for the `window`'s `load` event. It uses the image's `currentSrc` (en-US) property to fetch and display the URL selected by the browser from the `srcset`.

以下代码在 `window` 的 `load` 事件的处理程序中运行。它使用图像的 `currentSrc` (en-US) 属性来获取并显示浏览器从 `srcset` 中选择的 URL。

```js
let box = document.querySelector(".box");
let image = box.querySelector("img");

let newElem = document.createElement("p");
newElem.innerHTML = `Image: <code>${image.currentSrc}</code>`;
box.appendChild(newElem);
```

### 结果

输出展示在下面，所选 URL 将取决于你显示的图像版本，1x 版本还是 2x 版本？。如果你碰巧有标准和高密度显示器，请尝试在它们之间移动此窗口并重新加载页面以查看结果变化。

有关其他示例，请参阅我们的响应式图片指南。

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-srcset |

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

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

See also
--------

* Images in HTML
* Responsive images
* Image file type and format guide


HTMLImageElement.naturalHeight - Web API 接口参考

HTMLImageElement.naturalHeight
==============================

`HTMLImageElement` 接口的 **`naturalHeight`** 属性是一个只读值，它返回图像固有的（自然的）、修正高度后的 CSS 像素。

这是图像在没有限制其高度的情况下绘制的高度；如果你没有为图像指定高度，或者将图像放置在限制或明确指定图像高度的容器中，它将被渲染为如此高。

**备注：** 大多数时候自然高度是服务器发送的图像的实际高度。不过，浏览器可以在将图像推送到渲染器之前对其进行修改。例如，Chrome 会降低低端设备上图像的分辨率。在这种情况下，`naturalHeight` 会将浏览器干预修改的图像高度视为自然高度，并返回该值。

值
-

一个整数值，指示图像的固有高度（以 CSS 像素为单位）。这是在没有为图像建立约束或特定值时自然绘制图像的高度。与 `height` (en-US) 不同，此自然高度已针对显示它的设备的像素密度进行了校正。

如果固有高度不可用——要么是因为图像没有指定固有高度，要么是因为图像数据不可用于获取此信息，“naturalHeight”返回 0。

示例
--

此示例显示图像的自然、密度调整大小以及由页面的 CSS 和其他因素更改的渲染大小。

### HTML

```html
<div class="box">
  <img
 src="/zh-CN/docs/Web/HTML/Element/img/clock-demo-400px.png"
 class="image" />
</div>
<div class="output"></div>
```

HTML 具有一个 400x398 像素的图像，该图像放置在一个 `<div>` 元素中。

### CSS

```css
.box {
  width: 200px;
  height: 200px;
}

.image {
  width: 100%;
}

.output {
  padding-top: 2em;
}
```

在上面的 CSS 中主要需要注意的是，用于绘制图像的容器的样式是 200px 宽，并且图像将被绘制以填充其宽度（100%）。

### JavaScript

```js
let output = document.querySelector(".output");
let image = document.querySelector("img");

window.addEventListener("load", (event) => {
  output.innerHTML +=
    `Natural size: ${image.naturalWidth} x ` +
    `${image.naturalHeight} pixels<br>`;
  output.innerHTML +=
    `Displayed size: ${image.width} x ` + `${image.height} pixels`;
});
```

JavaScript 代码将自然尺寸和显示尺寸转储到带有 `output` 类的 `<div>` 中。这是为了响应窗口的 `load` 事件处理程序，以确保在尝试检查其宽度和高度之前，确保图像可用。

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-naturalheight-dev |

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

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


Image() - Web API 接口参考

Image()
=======

\*\*`Image()`\*\*函数将会创建一个新的`HTMLImageElement`实例。

它的功能等价于 `document.createElement('img')`

语法
--
```

Image(width, height)
```

### 参数

width

图片的宽度 (即 `width` 属性).

height

图片的高度 (即 `height` 属性).

示例
--

```js
var myImage = new Image(100, 200);
myImage.src = "picture.jpg";
document.body.appendChild(myImage);
```

上面的代码相当于在 `<body>`中定义了下面的 HTML:

```html
<img width="100" height="200" src="picture.jpg" />
```

**备注：** 无论构造函数中指定的大小是多少，都会加载整个位图。如果在构造时指定了尺寸信息，那么将会反应在实例的 `HTMLImageElement.width` (en-US) 和 `HTMLImageElement.height` (en-US) 属性上。图像自身的 CSS 像素值将会反应在`HTMLImageElement.naturalWidth` (en-US) 和 `HTMLImageElement.naturalHeight`属性。如果没有指定值，那么两个属性的值相同

规范
--

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

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

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


HTMLImageElement.decoding - Web API 接口参考

HTMLImageElement.decoding
=========================

`HTMLImageElement` 接口的 **`decoding`** 属性用于告诉浏览器使用何种方式解析图像数据。Syntax
------
```

refStr = imgElem.decoding;
imgElem.decoding = refStr;
```

### Values

使用 `DOMString` 表示解码方式。可使用以下值：

* **`sync`**: 同步解码图像，保证与其他内容一起显示。
* **`async`**: 异步解码图像，加快显示其他内容。
* **`auto`**: 默认模式，表示不偏好解码模式。由浏览器决定哪种方式更适合用户。
Usage notes
-----------

`decoding` 属性使你可以控制是否允许浏览器尝试异步加载图像。如果这样做会引起问题，你可指定值为 `sync` 禁止异步加载。异步加载对 `<img>` 元素很有用，对屏幕外的图像对象可能会更有用。

Examples
--------

```js
var img = new Image();
img.decoding = "sync";
img.src = "img/logo.png";
```

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

| Specification |
| --- |
| HTML Standard # dom-img-decoding |

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

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


HTMLImageElement.decode() - Web API 接口参考

HTMLImageElement.decode()
=========================

`HTMLImageElement` 接口的 **`decode()`** 方法返回一个当图片解码后可安全用于附加到 DOM 上时 resolves 的 `Promise` 对象。这可用于在将图片附加到一个 DOM 中的元素（或作为一个新元素加入 DOM 中）之前启动加载，所以在将图像添加到 DOM 时可以立即渲染图像。这反过来，防止了将图像加入 DOM 后图像的加载造成下一帧渲染的延迟。

语法
--
```

var promise = HTMLImageElement.decode();
```

### 参数

无。

### 返回

一个一旦数据准备好可供使用时 resolve 的 promise 对象。

### 异常

`DOMException` 表示解码图像时出错。

使用提示
----

一个 `decode()` 的潜在用例：当在加载一个非常大的图片时（例如，一个在线相册），你可以在加载初期提供一个低分辨率的缩略图，之后通过实例化一个 `HTMLImageElement` 将该图像替换为一个全分辨率图像，设置其 source 为全分辨率图像 URL，使用 `decode()` 获取一旦全分辨率图像准备好被使用时 resolved 的 promise 对象。这时你可以使用当前可用的全分辨率图像替换之前的低分辨率图像。

例子
--

以下例子展示了如何使用 `decode()` 方法来控制一个图像插入 DOM 的时机。若不使用 `Promise` (en-US) 返回方法，你将在图像的 `load` 事件处理函数中将图像加入 DOM 中，通过 `error` 事件处理函数处理错误。

```js
const img = new Image();
img.src = "nebula.jpg";
img
  .decode()
  .then(() => {
    document.body.appendChild(img);
  })
  .catch((encodingError) => {
    // Do something with the error.
  });
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-decode-dev |

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

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


HTMLImageElement.loading - Web API 接口参考

HTMLImageElement.loading
========================

`HTMLImageElement` 的 **`loading`** 属性为一个字符串，它的值会提示 用户代理 告诉浏览器不在可视视口内的图片该如何加载。这样一来，通过推迟图片加载仅让其在需要的时候加载而非页面初始载入时立刻加载，优化了页面的载入。

语法
--
```

let imageLoadScheduling = htmlImageElement.loading;
htmlImageElement.loading = eagerOrLazy;
```

### 值

`DOMString` 提示用户代理该如何最佳规划图片加载来优化页面性能。可能的值有：

`eager`

默认行为， `eager` 告诉浏览器当处理 `<img>` 标签时立即加载图片。

`lazy`

告诉用户代理推迟图片加载直到浏览器认为其需要立即加载时才去加载。例如，如果用户正在往下滚动页面，值为 `lazy` 会导致图片仅在马上要出现在 可视视口中时开始加载。

使用说明
----

### load 事件的时机

`load` 事件在文档被完整的处理完成时触发。当图片使用立即加载 (默认值) 时，文档中的所有图片都会在 `load` 事件触发前载入。

当 `loading` 值设为 `lazy` 时，图片不再会在请求，下载，处理的时间内推迟 `load` 事件触发。

`loading` 属性值设为 `lazy` 但是在页面初次加载时就在可视视口内的图片会立即加载但它们也不会推迟 `load` 事件。换句话说，这些图片不会在处理 `<img>` 元素时立即加载，但仍会作为页面初始加载的一部分而加载。他们只是不会影响 `load` 事件。

这表明当 `load` 触发时，可视区域内懒加载的图片可能不可见。

### 防止元素在图片懒加载时出现移位

当一个加载被 `loading` 属性设为 `lazy` 的图片最后加载时，浏览器会根据`<img>` 元素的尺寸和图片自身大小重排文档，更新被图片影响的元素的位置。

为了防止重排发生，你需要使用 `width` 和 `height` 属性明确设置图片大小。通过这样建立固有长宽比，你防止了元素的移位。取决于实际的加载时间和重排，移位造成的最小的影响可能只是使用户困惑和不适，最坏的影响则是导致用户点错目标。

示例
--

下面展示的 `addImageToList()` 函数将一个照片缩略图添加到一个物品列表中，使用懒加载防止请求图片，直到其真正需要显示。

```js
function addImageToList(url) {
  const list = document.querySelector("div.photo-list");

  let newItem = document.createElement("div");
  newItem.className = "photo-item";

  let newImg = document.createElement("img");
  newImg.loading = "lazy";
  newImg.width = 320;
  newImg.height = 240;
  newImg.src = url;

  newItem.appendChild(newImg);
  list.appendChild(newItem);
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-loading |

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

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

参见
--

* `<img>` 元素
* MDN 学习专区中的 Web 性能
* MDN web 性能指南中的懒加载


AudioScheduledSourceNode.stop() - Web API 接口参考

AudioScheduledSourceNode.stop()
===============================

`AudioScheduledSourceNode` 上的`stop()`方法将声音安排在指定的时间停止播放。如果没有指定时间，声音将立即停止播放。

每次在同一个节点上调用 `stop()` 时，指定的时间将替换任何未发生的计划停止时间。如果节点已经停止，则此方法无效。

**备注：** 如果计划的停止时间发生在节点计划的开始时间之前，则节点永远不会开始运行。

语法
--
```

AudioScheduledSourceNode.stop([when]);
```

### 参数

`when` 可选

声音停止播放的时间，单位为秒。这个值在 `AudioContext` 用于其 `currentTime` 属性的同一时间坐标系统中指定。省略这个参数，设置为 0 或者负值都会立即停止播放。

### Return value

`undefined`### Exceptions

`InvalidStateNode`

节点还没有通过调用`start()` (en-US)方法被播放。

`RangeError`

当 `when` 指定为负值时。

Example
-------

This example demonstrates starting an oscillator node, scheduled to begin playing at once and to stop playing in one second. The stop time is determined by taking the audio context's current time from `AudioContext.currentTime` and adding 1 second.

```js
context = new AudioContext();
osc = context.createOscillator();
osc.connect(context.destination);

/\* Let's play a sine wave for one second. \*/

osc.start();
osc.stop(context.currentTime + 1);
```

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

| Specification |
| --- |
| Web Audio API # dom-audioscheduledsourcenode-stop |

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

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

See also
--------

* Using the Web Audio API (en-US)
* `start()` (en-US)
* `AudioScheduledSourceNode`
* `AudioBufferSourceNode`
* `ConstantSourceNode` (en-US)
* `OscillatorNode`


VRDisplay.requestAnimationFrame() - Web API 接口参考

VRDisplay.requestAnimationFrame()
=================================

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

The **`requestAnimationFrame()`** method of the `VRDisplay` interface is a special implementation of `Window.requestAnimationFrame` containing a callback function that will be called every time a new frame of the `VRDisplay` presentation is rendered:

* When the `VRDisplay` is not presenting a scene, this is functionally equivalent to `Window.requestAnimationFrame`.
* When the VRDisplay is presenting, the callback is called at the native refresh rate of the `VRDisplay`.
Syntax
------

```js
var handle = vrDisplayInstance.requestAnimationFrame(callback);
```

### Parameters

callback

A callback function that will be called every time a new frame of the `VRDisplay` presentation is rendered.

### Return value

A long representing the handle of the `requestAnimationFrame()` call. This can then be passed to a `VRDisplay.cancelAnimationFrame()` (en-US) call to unregister the callback.

Examples
--------
```

TBD.
```

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

该 API 在旧的 WebVR API（已被 WebXR Device API 取代）中定义。它不再有望成为标准。

在所有浏览器都实现新的 WebXR API (en-US) 之前，建议使用框架（如：A-Frame、Babylon.js 或 Three.js）或 polyfill 来开发适用于所有浏览器的 WebXR 应用程序。[1]

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

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

See also
--------

* WebVR API


Clients.matchAll() - Web API 接口参考

Clients.matchAll()
==================

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

`Clients` 接口的 **`matchAll()`** 方法返回 service worker `Client` 对象列表的 `Promise` . 包含 `options` 参数以返回域与关联的 service worker 的域相同所有 service worker 的 clients. 如果未包含 options，该方法仅返回由 service worker 控制的 service worker clients.

语法
--

```js
ServiceWorkerClients.matchAll(options).then(function (clients) {
  // do something with your clients list
});
```

### 参数

`options 可选`

一个 options 对象，允许你为匹配操作设置选项。可用选项包括：

* `includeUncontrolled`: `Boolean` (en-US) — 如果设置为`true`, 匹配操作将返回与当前服务工作者共享相同源的所有服务工作者客户端。否则，它仅返回由当前服务工作者控制的服务工作者客户端。默认值为`false`.
* `type`: 设置想要匹配的 clients 类型。可用值包括 `window`, `worker`, `sharedworker`, 和 `all`. 默认是 `all`.

### 返回值

resolve 为一个 `Client` 对象数组的 `Promise` . 在 Chrome 46/Firefox 54 以及更高版本中，该方法以最近关注的顺序返回 clients , 根据规范更正。

示例
--

```js
clients.matchAll(options).then(function (clientList) {
  for (var i = 0; i < clients.length; i++) {
    if (clientList[i].url === "index.html") {
      clients.openWindow(clientList[i]);
      // or do something else involving the matching client
    }
  }
});
```

规范
--

| Specification |
| --- |
| Service Workers # clients-matchall |

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

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


Clients.openWindow() - Web API 接口参考

Clients.openWindow()
====================

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

`Clients`接口的 **`openWindow()`** 方法创建一个顶级的浏览器上下文并加载给定的 URL. 如果调用脚本没有显示弹出窗口的权限， **`openWindow()`** 将抛出 InvalidAccessError.

在 Firefox 中，只有在作为通知点击事件的结果调用时，才允许该方法显示弹出窗口。

在 Chrome for Android 中，该方法可以改为在先前添加到用户主屏幕的 standalone web app 提供的现有浏览上下文中打开 URL.

语法
--

```js
ServiceWorkerClients.openWindow(url).then(function (WindowClient) {
  // do something with your WindowClient
});
```

### 参数

`url`

一个 `USVString`，表示要在窗口中打开的 client 的 URL。通常，此值必须是与调用脚本有相同域的 URL.

### 返回值

如果 URL 来自与服务工作者相同的域，则 resolve 为 `WindowClient` (en-US) 对象的 Promise，否则 resolve 为 null value.

示例
--

```js
// When the user clicks a notification focus the window if it exists or open
// a new one otherwise.
onotificationclick = function (event) {
  var found = false;
  clients.matchAll().then(function (clientsArr) {
    for (i = 0; i < clientsArr.length; i++) {
      if (clientsArr[i].url === event.data.url) {
        // We already have a window to use, focus it.
        found = true;
        clientsArr[i].focus();
        break;
      }
    }
    if (!found) {
      // Create a new window.
      clients.openWindow(event.data.url).then(function (windowClient) {
        // do something with the windowClient.
      });
    }
  });
};
```

规范
--

| Specification |
| --- |
| Service Workers # clients-openwindow |

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

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


Clients.get() - Web API 接口参考

Clients.get()
=============

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

`Clients` 接口的 **`get()`** 方法 获取给定 `id` 匹配的 Service Worker client，并在 `Promise` 中返回它。

语法
--

```js
self.clients.get(id).then(function (client) {
  // do something with your returned client
});
```

### 参数

`id`

一个 `DOMString` ，表示你想要获取的 client id.

### 返回

一个 resolve 为 `Client` 对象的 `Promise`.

示例
--

```js
self.clients.get(options).then(function (client) {
  self.clients.openWindow(client.url);
});
```

规范
--

| Specification |
| --- |
| Service Workers # clients-get |

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

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


Clients.claim() - Web API 接口参考

Clients.claim()
===============

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

`Clients` 接口的 **`claim()`** 方法允许一个激活的 service worker 将自己设置为其 `scope` (en-US) 内所有 clients 的`controller` . 这会在由此 service worker 控制的任何 clients 中触发 `navigator.serviceWorker` 上的 "`controllerchange`" 事件。

当一个 service worker 被初始注册时，页面在下次加载之前不会使用它。 `claim()` 方法会立即控制这些页面。请注意，这会导致 service worker 控制通过网络定期加载的页面，或者可能通过不同的 service worker 加载。

语法
--
```

await clients.claim();
```

### 参数

None.

### 返回

A `Promise` for `void`.

示例
--

The following example uses `claim()` inside service worker's "`activate`" event listener so that clients loaded in the same scope do not need to be reloaded before their fetches will go through this service worker.

```js
self.addEventListener("activate", (event) => {
  event.waitUntil(clients.claim());
});
```

规范
--

| Specification |
| --- |
| Service Workers # clients-claim |

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

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

See also
--------

* Using Service Workers (en-US)
* The service worker lifecycle
* Is ServiceWorker ready?
* `Promises`
* `self.skipWaiting()` - skip the service worker's waiting phase


ServiceWorkerGlobalScope.skipWaiting() - Web API 接口参考

ServiceWorkerGlobalScope.skipWaiting()
======================================

`ServiceWorkerGlobalScope` 的 **`ServiceWorkerGlobalScope.skipWaiting()`** 方法强制等待 service worker 成为激活的 service worker。

这个方法与 `Clients.claim()` 一起使用，以确保原 service worker 的更新，能立即对当前对客户端和其他所有激活的客户端生效。

语法
--

```js
skipWaiting()
```

### 参数

无。

### 返回值

一个 `Promise`，该 promise 会立即兑现为 `undefined`。

示例
--

虽然 `self.skipWaiting()` 可以在 service worker 执行期间的任何时间点调用，但是它只有在新安装的 service worker 可能保持在 `waiting` 状态的时候才会起作用。因此，通常从 `InstallEvent` 处理程序内部调用 `self.skipWaiting()`。

以下示例会导致新安装的 service worker 进入 `activating` 状态，而不会管是否已经有一个激活的 service worker。

```js
self.addEventListener("install", (event) => {
  // skipWaiting() 返回一个 promise，但完全可以忽略它
  self.skipWaiting();

  // 执行 service worker 安装所需
  // 的任何其他操作，
  // 可能需要在 event.waitUntil() 的内部进行
});
```

规范
--

| Specification |
| --- |
| Service Workers # service-worker-global-scope-skipwaiting |

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

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

参见
--

* 使用 Service Worker
* Service worker 基础代码示例
* 是否支持 ServiceWorker？
* `Clients.claim()`
* `Promise`
* 使用 web worker


DeviceMotionEvent.acceleration - Web API 接口参考

DeviceMotionEvent.acceleration
==============================

acceleration 属性会返回设备的加速度记录（单位：m / s2）。

**备注：** 如果硬件无法从 acceleration 数据中移除重力加速度，则该值在`DeviceMotionEvent`中可能并不存在，你应当使用`DeviceMotionEvent.accelerationIncludingGravity`代替

语法
--
```

var acceleration = instanceOfDeviceMotionEvent.acceleration;
```

值
-

`acceleration`是一个包括三轴（x、y、z）加速度信息的对象，每个轴都有自己的属性：

`x`

表示 x 轴（西到东）上的加速度

`y`

表示 y 轴（南到北）上的加速度

`z`

表示 z 轴（下到上）上的加速度

说明
--

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-devicemotionevent-acceleration③ |

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

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

推荐浏览
----

* `DeviceMotionEvent.accelerationIncludingGravity`
* `devicemotion`
* `window.ondevicemotion`
* `deviceorientation`
* `DeviceOrientationEvent`
* Detecting device orientation (en-US)
* Orientation and motion data explained


DeviceMotionEvent.interval - Web API 接口参考

DeviceMotionEvent.interval
==========================

返回从底层硬件获取数据的时间间隔（单位：毫秒）。你可以使用它来确定运动事件的粒度。

语法
--
```

var interval = instanceOfDeviceMotionEvent.interval;
```

说明
--

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-devicemotionevent-interval① |

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

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

推荐浏览
----

* `DeviceMotionEvent`
* `devicemotion`
* `window.ondevicemotion`
* `deviceorientation`
* `DeviceOrientationEvent`
* Detecting device orientation (en-US)
* Orientation and motion data explained


DeviceMotionEvent.DeviceMotionEvent() - Web API 接口参考

DeviceMotionEvent.DeviceMotionEvent()
=====================================

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

The **`DeviceMotionEvent`** constructor 会创建一个新的 `DeviceMotionEvent`.

语法
--
```

var deviceMotionEvent = new DeviceMotionEvent(type[, options])
```

### 参数

`type`

必须是 `"devicemotion"`.

`options`可选

可选项如下：

* `acceleration`: 一个对象，包含设备在 X，Y 和 Z 三个轴线上的加速度。加速度的单位为m/s2.
* `accelerationIncludingGravity`: 一个对象，包含设备在 X，Y 和 Z 三个轴线上，重力作用下的加速度。加速度的单位为m/s2.
* `rotationRate`: 一个对象，包含设备的定向在三个定向轴 alpha, beta 和 gamma 上的偏移比率。偏移比率的单位是每秒偏移的角度。
* `interval`: 时间间隔，单位毫秒，表示设备获取数据的间隔时间。

说明
--

无特别说明。

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

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


DeviceMotionEvent.rotationRate - Web API 接口参考

DeviceMotionEvent.rotationRate
==============================

返回设备围绕其每个轴（x、y、z）旋转的速率（单位：度/秒）。

**备注：** 如果设备无法提供此信息，则为 null

语法
--
```

var rates = instanceOfDeviceMotionEvent.rotationRate;
```

值
-

rotationRates 属性是一个只读对象，用于描述设备围绕其每个轴的旋转速率：

`alpha`

设备绕其 Z 轴旋转的速率（即绕垂直于屏幕的线旋转）

`beta`

设备绕其 X 轴旋转的速率（即从前到后旋转）

`gamma`

设备绕其 Y 轴旋转的速率（即从一侧到另一侧）

说明
--

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-devicemotionevent-rotationrate② |

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

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

推荐阅读
----

* `DeviceMotionEvent`
* `devicemotion`
* `window.ondevicemotion`
* `deviceorientation`
* `DeviceOrientationEvent`
* Detecting device orientation (en-US)
* Orientation and motion data explained


DeviceMotionEvent.accelerationIncludingGravity - Web API 接口参考

DeviceMotionEvent.accelerationIncludingGravity
==============================================

accelerationIncludingGravity 属性返回设备的加速度的记录，单位为米每秒平方（m / s2）。与已移除重力加速度的`DeviceMotionEvent.acceleration`不同，此值是由用户引起的设备的加速度和由重力加速度的总和。

此值通常不如`DeviceMotionEvent.acceleration`实用，但是在部分不能自动从加速度数据中移除重力加速度的设备（例如没有陀螺仪的设备），是唯一可用值。

语法
--
```

var acceleration = instanceOfDeviceMotionEvent.accelerationIncludingGravity;
```

值
-

`accelerationIncludingGravity`是一个包括三轴（x、y、z）加速度信息的对象，每个轴都有自己的属性：

`x`

表示 x 轴（西到东）上的加速度

`y`

表示 y 轴（南到北）上的加速度

`z`

表示 z 轴（下到上）上的加速度

说明
--

| Specification |
| --- |
| DeviceOrientation Event Specification # ref-for-dom-devicemotionevent-accelerationincludinggravity④ |

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

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

推荐浏览
----

* `DeviceMotionEvent.acceleration`
* `devicemotion`
* `window.ondevicemotion`
* `deviceorientation`
* `DeviceOrientationEvent`
* Detecting device orientation (en-US)
* Orientation and motion data explained


UIEvent.detail - Web API 接口参考

UIEvent.detail
==============

**`UIEvent.detail`** 是只读属性，当值为非空的时候，提供当前点击数 (和环境有关) 。

对 `click` 或者 `dblclick` 事件，`UIEvent.detail` 是当前点击数量。

对 `mousedown` 或者 `mouseup` 事件，`UIEvent.detail` 是 1 加上当前点击数。

对所有的其他`UIEvent` 对象，`UIEvent.detail` 总是零。

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

| Specification |
| --- |
| UI Events # dom-uievent-detail |

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

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


UIEvent() - Web API 接口参考

UIEvent()
=========

**`UIEvent()`** 作为构造函数，可用于构造一个新的 `UIEvent` 对象。

语法
--
```

event = new UIEvent(typeArg [, UIEventInit])
```

### Values

`typeArg`

传递的是一个 `DOMString`类型的字符串，用来命名且重新发布的事件。

`UIEventInit` 可选

是 `UIEventInit` 集合，它拥有以下属性：

* **`detail`**: 可选，默认为 long 类型的 0 数值，用来标记事件的关联值。`UIEvent.detail` 列出了标准事件的语义。
* **`view`**: 可选，默认为 null，类型为 `WindowProxy`, 用来关联`Window` 与 event 本身。
* **`sourceCapabilities`**:
非标准
 一个 `InputDeviceCapabilities` (en-US) 类型的接口实例 (对象)，用来提供物理设备的触摸信息。

**备注：** `UIEventInit` 合集依然接受从`EventInit` 定义来的合集。

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

| Specification |
| --- |
| UI Events # dom-uievent-uievent |

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

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

See also
--------

* `UIEvent`, the interface of the objects it constructs.


KeyboardEvent.which - Web API 接口参考

KeyboardEvent.which
===================

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

`KeyboardEvent` 接口的 **`which`** 只读属性返回所按下键的数字 `keyCode` 或所按下字母数字键的字符代码 (`charCode`) 。

语法
--
```

var keyResult = event.which;
```

### 返回值

* `keyResult` contains the numeric code for a particular key pressed, depending on whether an alphanumeric or non-alphanumeric key was pressed. Please see `KeyboardEvent.charCode` and `KeyboardEvent.keyCode` for more details.
例子
--

```html
<html>
  <head>
    <title>charCode/keyCode/which example</title>

    <script type="text/javascript">
 function showKeyPress(evt) {
 alert(
 "onkeypress handler: \n" +
 "keyCode property: " +
 evt.keyCode +
 "\n" +
 "which property: " +
 evt.which +
 "\n" +
 "charCode property: " +
 evt.charCode +
 "\n" +
 "Character Key Pressed: " +
 String.fromCharCode(evt.charCode) +
 "\n",
 );
 }

 function keyDown(evt) {
 alert(
 "onkeydown handler: \n" +
 "keyCode property: " +
 evt.keyCode +
 "\n" +
 "which property: " +
 evt.which +
 "\n",
 );
 }
 </script>
  </head>

  <body onkeypress="showKeyPress(event);" onkeydown="keyDown(event);">
    <p>Please press any key.</p>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| UI Events # dom-uievent-which |

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

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

See also
--------

* `KeyboardEvent`, the interface this property belongs too.


用户界面项目视图 - Web API 接口参考

用户界面项目视图
========

The **`UIEvent.view`** 只读属性返回的生成事件的 `document.defaultView` (`window` of the document) 对象。在浏览器中，这是事件所在的 `Window` 对象。

语法
--
```

var view = event.view;
```

* `view` 是对 `AbstractView` 对象的引用。
技术参数
----

| Specification |
| --- |
| UI Events # dom-uievent-view |

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

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


AudioListener：forwardY 属性 - Web API 接口参考

AudioListener：forwardY 属性
=========================

`AudioListener` 接口的 `forwardY` 只读属性是一个 `AudioParam`，表示定义监听者指向的前进方向的方向向量的 y 值。

**备注：** 当与 `PannerNode` (en-US) 一起使用时，如果 `panningModel` (en-US) 设置为 equalpower，则参数为 *a-rate*；否则为 *k-rate*。

值
-

一个 `AudioParam`。其默认值为 0，范围可在正负无穷之间。

示例
--

查看 BaseAudioContext.createPanner() (en-US) 以获取示例代码。

规范
--

| Specification |
| --- |
| Web Audio API # dom-audiolistener-forwardy |

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

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

参见
--

* 使用 Web Audio API


SpeechGrammar.src - Web API 接口参考

SpeechGrammar.src
=================

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

**`src`** 属性是 `SpeechGrammar` 接口设置并返回的一个字符串，包含了 `SpeechGrammar` 对象的文法。

语法
--
```

var myGrammar = speechGrammarInstance.src;
```

### 值

`DOMString` 用以表示文法。

示例
--

```js
var grammar =
  "#JSGF V1.0; grammar colors; public <color> = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;";
var recognition = new SpeechRecognition();
var speechRecognitionList = new SpeechGrammarList();
speechRecognitionList.addFromString(grammar, 1);
recognition.grammars = speechRecognitionList;

console.log(speechRecognitionList[0].src); // 应该返回和上面文法变量一样的内容
console.log(speechRecognitionList[0].weight); // 应该返回 1 - 与上面第四行所设置的权重一致
```

规范
--

| Specification |
| --- |
| Web Speech API # dom-speechgrammar-src |

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

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

相关链接
----

* Web Speech API


SpeechGrammar.weight - Web API 接口参考

SpeechGrammar.weight
====================

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

`SpeechGrammar` 接口的可选属性 **`weight`** 设置并返回了一个 `SpeechGrammar` 对象的权重。

语法
--
```

var myGrammarWeight = speechGrammarInstance.weight;
```

### 值

浮点数表示了当前文法的权重，范围在 0.0-1.0 之间。

样例
--

```js
var grammar =
  "#JSGF V1.0; grammar colors; public <color> = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;";
var recognition = new SpeechRecognition();
var speechRecognitionList = new SpeechGrammarList();
speechRecognitionList.addFromString(grammar, 1);
recognition.grammars = speechRecognitionList;

console.log(speechRecognitionList[0].src); // 应该返回和上面文法变量一样的内容
console.log(speechRecognitionList[0].weight); // 应该返回 1 - 与上面第四行所设置的权重一致
```

规范
--

| Specification |
| --- |
| Web Speech API # dom-speechgrammar-weight |

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

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

相关链接
----

* Web Speech API


SpeechGrammar.SpeechGrammar() - Web API 接口参考

SpeechGrammar.SpeechGrammar()
=============================

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

**`SpeechGrammar`** 是 `SpeechGrammar` 接口的构造函数，创建一个新的 `SpeechGrammar` 对象实例。

语法
--
```

var mySpeechGrammar = new SpeechGrammar();
```

### Parameters

无。

样例
--

```js
var grammar =
  "#JSGF V1.0; grammar colors; public <color> = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;";
var recognition = new SpeechRecognition();
var speechRecognitionList = new SpeechGrammarList();
speechRecognitionList.addFromString(grammar, 1);
recognition.grammars = speechRecognitionList;

var newGrammar = new SpeechGrammar();
newGrammar.src =
  "#JSGF V1.0; grammar names; public <name> = chris | kirsty | mike;";
speechRecognitionList[1] = newGrammar; // 将 SpeechGrammar 对象添加到列表中
```

规格
--

此 API 没有官方的 W3C 或 WHATWG 规范。

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

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

相关链接
----

* Web Speech API


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

Element.hasAttributeNS()
========================

概述
--

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

语法
--
```

result =element.hasAttributeNS(namespace,localName)
```

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

// 在为属性设置值之前检测该属性是否存在
var d = document.getElementById("div1");
if (d.hasAttributeNS(
        "http://www.mozilla.org/ns/specialspace/",
        "special-align")) {
   d.setAttribute("align", "center");
}
```

备注
--

该方法与`hasAttribute`类似，只是要检查的属性由命名空间和名称指定。只有使用命名空间的 XML 文档才使用方法

DOM methods dealing with element's attributes:

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

规范
--

DOM Level 2 Core: hasAttributeNS


GlobalEventHandlers.onpointerenter - Web API 接口参考

GlobalEventHandlers.onpointerenter
==================================

HTML DOMpointerenter 事件的 GlobalEventHandlers（全局事件处理函数）

```js
var enterHandler = targetElement.onpointerenter;
```

### 返回值

`enterHandler`

`targetElement`的 pointerenter 事件处理函数。

示例
--

这个例子展示了使用 onpointerenter 来设置元素 pointerenter 事件处理函数的两种方式\*。\*

```js
<html>
<script>
function enterHandler(ev) {
 // 处理 pointerenter 事件
}
function init() {
 var el=document.getElementById("target1");
 el.onpointerenter = enterHandler;
}
</script>
<body onload="init();">
<div id="target1"> 点我 ... </div>
<div id="target2" onpointerenter="enterHandler(event)"> 点我 ... </div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| Pointer Events # the-pointerenter-event |
| Pointer Events # dom-globaleventhandlers-onpointerenter |

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

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

参见
--

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


Element.scrollTopMax - Web API 接口参考

Element.scrollTopMax
====================

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

**`Element.scrollTopMax`** 返回一个只读 Number 表示元素所能滚动的最大高度

语法
--
```

var pxl = elt.scrollTopMax;
```

规范
--

此属性不在当前规范中

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

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

See also
--------

* `Element.scrollLeftMax` giving the same information for the other axis.


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

Element.getElementsByClassName()
================================

**`Element.getElementsByClassName()`** 方法返回一个即时更新的（live）`HTMLCollection`，包含了所有拥有指定 class 的子元素。当在 document 对象上调用此方法时，会检索整个文档，包括根元素。

相似地，`getElementsByClassName()` 方法会在整个文档上执行；它返回指定拥有指定 class 名称的 document 根节点的后代元素。

语法
--
```

var elements = element.getElementsByClassName(names);
```

* **elements** 是一个即时更新的（live）`HTMLCollection`。
* **names** 是一个字符串，表示要匹配的类名（class names）列表；类名被空白符分隔。
* *element* 是文档中的任一 `Element`。
例子
--

获取所有包含 class 名称为 test 的元素：

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

获取所有包含 `red` 和 `test` class 名的元素：

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

获取 `id` 为 `main` 的元素的所有包含一个 `test` class 名的后代元素：

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

可以在任何 `HTMLCollection` 上面使用 `Array.prototype` 的方法，要把 `HTMLCollection` 作为该方法的上下文对象（this）。下例，查找类名为 `test` 的元素中的所有 `<div>` 元素：

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

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-element-getelementsbyclassname |

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

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


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

Element.getBoundingClientRect()
===============================

**`Element.getBoundingClientRect()`** 方法返回一个 `DOMRect` 对象，其提供了元素的大小及其相对于视口的位置。

语法
--

```js
getBoundingClientRect()
```

### 参数

无。

### 返回值

返回值是一个 `DOMRect` 对象，是包含整个元素的最小矩形（包括 `padding` 和 `border-width`）。该对象使用 `left`、`top`、`right`、`bottom`、`x`、`y`、`width` 和 `height` 这几个以像素为单位的只读属性描述整个矩形的位置和大小。除了 `width` 和 `height` 以外的属性是相对于视图窗口的左上角来计算的。

![](/zh-CN/docs/Web/API/Element/getBoundingClientRect/element-box-diagram.png)

该方法返回的 `DOMRect` 对象中的 `width` 和 `height` 属性是包含了 `padding` 和 `border-width` 的，而不仅仅是内容部分的宽度和高度。在标准盒子模型中，这两个属性值分别与元素的 `width`/`height` + `padding` + `border-width` 相等。而如果是 `box-sizing: border-box`，两个属性则直接与元素的 `width` 或 `height` 相等。

这个对象是由该元素的 `getClientRects()` 方法返回的一组矩形的集合，就是该元素的 CSS 边框大小。

空边框盒（译者注：没有内容的边框）会被忽略。如果所有的元素边框都是空边框，那么这个矩形给该元素返回的 `width`、`height` 值为 0，`left`、`top` 值为第一个 CSS 盒子（按内容顺序）的 top-left 值。

如果你需要获得边界矩形相对于整个网页左上角的位置，则可以将当前的滚动位置（可通过 `window.scrollX` 和 `window.scrollY` 获得）添加到 `top` 和 `left` 属性上。获得的边界矩形与当前的滚动位置无关。

示例
--

### 基础示例

在这个简单的示例中，获得的 `DOMRect` 对象表示的是一个简单的 `<div>` 元素的边界客户端矩形，并将其属性值显示出来。

```html
<div></div>
```

```css
div {
  width: 400px;
  height: 200px;
  padding: 20px;
  margin: 50px auto;
  background: purple;
}
```

```js
let elem = document.querySelector("div");
let rect = elem.getBoundingClientRect();
for (var key in rect) {
  if (typeof rect[key] !== "function") {
    let para = document.createElement("p");
    para.textContent = `${key} : ${rect[key]}`;
    document.body.appendChild(para);
  }
}
```

注意：`width`/`height` 是与元素的 `width`/`height` + `padding` 相等的。

也同样注意 `x`/`left`、`y`/`top`、`right` 和 `bottom` 与视口边缘到元素对应的一侧的绝对距离相等。

### 滚动

这个示例演示了当网页滚动时，边界客户端矩形是如何变化的。

```html
<div id="example"></div>
<div id="controls"></div>
```

```css
div#example {
  width: 400px;
  height: 200px;
  padding: 20px;
  margin: 50px auto;
  background: purple;
}

body {
  padding-bottom: 1000px;
}
p {
  margin: 0;
}
```

```js
function update() {
  const container = document.getElementById("controls");
  const elem = document.getElementById("example");
  const rect = elem.getBoundingClientRect();

  container.innerHTML = "";
  for (let key in rect) {
    if (typeof rect[key] !== "function") {
      let para = document.createElement("p");
      para.textContent = `${key} : ${rect[key]}`;
      container.appendChild(para);
    }
  }
}

document.addEventListener("scroll", update);
update();
```

规范
--

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

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

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

参考资料
----

* `getClientRects()`
* MSDN: `getBoundingClientRect`
* MSDN: `ClientRect`，更早版本的 `DOMRect`


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

Element.setAttributeNode()
==========================

`setAttributeNode()` 为指定的 Element 添加属性节点。

Syntax
------
```

var replacedAttr = element.setAttributeNode(attribute);
```

* `attribute 是添加到 element 中的属性节点`.
* `replacedAttr` 是被替换掉的属性节点。如果存在原有属性，则函数返回原有属性节点。
Example
-------
```

// <div id="one" align="left">one</div>
// <div id="two">two</div>
var d1 = document.getElementById("one");
var d2 = document.getElementById("two");
var a = d1.getAttributeNode("align");
d2.setAttributeNode(a.cloneNode(true));
alert(d2.attributes[1].value)
// returns: `left'
```

Notes
-----

如果 element 中已经存在该属性名的属性，则函数使用新的属性替换掉原有的属性并将原有属性返回

这个方法很少被用到，多数情况下使用函数 `setAttribute()` 修改 element 的属性。

DOM methods dealing with element's attributes:

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

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

DOM Level 2 Core: setAttributeNode (introduced in DOM Level 1 Core)


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

Element.scrollIntoView()
========================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
`Element` 接口的 `scrollIntoView()` 方法会滚动元素的父容器，使被调用 `scrollIntoView()` 的元素对用户可见。

语法
--

```js
scrollIntoView()
scrollIntoView(alignToTop)
scrollIntoView(scrollIntoViewOptions)
```

### 参数

`alignToTop`可选

一个布尔值：

* 如果为 `true`，元素的顶端将和其所在滚动区的可视区域的顶端对齐。相应的 `scrollIntoViewOptions: {block: "start", inline: "nearest"}`。这是这个参数的默认值。
* 如果为 `false`，元素的底端将和其所在滚动区的可视区域的底端对齐。相应的 `scrollIntoViewOptions: {block: "end", inline: "nearest"}`。

`scrollIntoViewOptions` 可选
实验性

一个包含下列属性的对象：

`behavior` 可选

定义滚动是立即的还是平滑的动画。该选项是一个字符串，必须采用以下值之一：

* `smooth`：滚动应该是平滑的动画。
* `instant`：滚动应该通过一次跳跃立刻发生。
* `auto`：滚动行为由 `scroll-behavior` 的计算值决定。

`block` 可选

定义垂直方向的对齐，`start`、`center`、`end` 或 `nearest` 之一。默认为 `start`。

`inline` 可选

定义水平方向的对齐，`start`、`center`、`end` 或 `nearest` 之一。默认为 `nearest`。

### 返回值

无 (`undefined`)。

示例
--

```js
const element = document.getElementById("box");

element.scrollIntoView();
element.scrollIntoView(false);
element.scrollIntoView({ block: "end" });
element.scrollIntoView({ behavior: "smooth", block: "end", inline: "nearest" });
```

注意
--

取决于其他元素的布局情况，此元素可能不会完全滚动到顶端或底端。

规范
--

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

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

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

参见
--

* `Element.scrollIntoViewIfNeeded()`
非标准


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

元素：click 事件
===========

当定点设备的按钮（通常是鼠标的主键）在一个元素上被按下和放开时，`click` 事件就会被触发。

如果在一个元素上按下按钮，而将指针移到元素外再释放按钮，则在包含这两个元素的最具体的父级元素上触发事件。

`click` 事件会在 `mousedown` 和 `mouseup` 事件依次触发后触发。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent事件属性
----

*该接口同样继承了其父级（`UIEvent` 和 `Event`）的属性。*

`MouseEvent.altKey` 只读

若在按下 `alt` 键的情况下触发鼠标事件，则返回 `true`。

`MouseEvent.button` 只读

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

`MouseEvent.buttons` 只读

触发鼠标事件时按下的按钮（如果有按钮被按下）。

`MouseEvent.clientX` 只读

鼠标指针在本地（DOM）坐标系中的 X 坐标。

`MouseEvent.clientY` 只读

鼠标指针在本地（DOM）坐标系中的 Y 坐标。

`MouseEvent.ctrlKey` 只读

若在按下 `control` 键的情况下触发鼠标事件，则返回 `true`。

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

返回指针相对于当前触发事件的层级的横坐标。

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

返回指针相对于当前触发事件的层级的纵坐标。

`MouseEvent.metaKey` 只读

若在按下 `meta` 键的情况下触发鼠标事件，则返回 `true`。

`MouseEvent.movementX` 只读

返回鼠标指针相对于最后一次 `mousemove` 事件的 X 坐标。

`MouseEvent.movementY` 只读

返回鼠标指针相对于最后一次 `mousemove` 事件的 Y 坐标。

`MouseEvent.offsetX` 只读

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

`MouseEvent.offsetY` 只读

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

`MouseEvent.pageX` 只读

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

`MouseEvent.pageY` 只读

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

`MouseEvent.relatedTarget` 只读

返回与事件关联的次要目标（如果存在）。

`MouseEvent.screenX` 只读

返回鼠标指针在全局（屏幕）坐标系中的 X 坐标。

`MouseEvent.screenY` 只读

返回鼠标指针在全局（屏幕）坐标系中的 Y 坐标。

`MouseEvent.shiftKey` 只读

若在按下 `shift` 键的情况下触发鼠标事件，则返回 `true`。

`MouseEvent.mozInputSource`
非标准
 只读

触发事件的设备类型（一个 `MOZ_SOURCE_*` 常量）。这可以让你确定鼠标事件是由实际的鼠标还是由触摸事件生成（这可能会影响解析与事件相关联的坐标的准确度）。

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

单击时施加的压力。

`MouseEvent.x` 只读

`MouseEvent.clientX` 的别名。

`MouseEvent.y` 只读

`MouseEvent.clientY` 的别名。

使用说明
----

`MouseEvent` 对象会被传入到 `click` 的事件处理器中，其 `detail` 属性设置了 `target` 被点击的次数。换句话说，在双击时，`detail` 是 2；三击时是 3；以此类推。该计数器会在没有任何点击的情况下会很快被重置，而间隔多长的时间则因浏览器和平台而异。间隔时间也可能受到用户偏好设置的影响；例如，无障碍选项可能会延长间隔时间，以便在自适应界面上更轻松地执行多次点击。

### Internet Explorer

IE 8 和 9 中存在一个错误，在将 `background-color` 的计算值为 `transparent` 的元素覆盖在其他元素之上时，该元素不会收到 `click` 事件。`click` 事件将只会在底层元素上触发。参见在线演示。

该错误的解决方案：

* 仅适用于 IE 9：
    + 设置 `background-color``: rgba(0,0,0,0)`
    + 设置 `opacity``: 0` 以及为 `background-color` 设置一个明确的、除 `transparent` 以外的值。
* 适用于 IE8 和 IE9：设置 `filter: alpha(opacity=0);` 以及为 `background-color` 设置一个明确的、除 `transparent` 以外的值。
### Safari 手机版

safari 手机版 7.0+（也可能是更早的版本）存在一个错误，当一个元素为交互式元素（例如：`<div>`），且没有直接将事件监听器绑定在它们自身（即，适用事件委托）时，将无法触发在该元素上触发 `click` 事件。查看在线演示。也可以看 Safari 的可点击元素 和可点击元素的定义。

解决方法如下：

* 为该元素或者祖先元素，设置 `cursor``: pointer;` 样式。
* 为该元素或者祖先元素（不包括 `<body>`），设置 `onclick="void(0)"` 属性。
* 使用可点击元素如 `<a>`，代替不可交互元素如 `<div>`。
* 不使用 `click` 的事件委托。

Safari 手机版里，以下元素是交互式的（因此不会受到上述错误的影响）：

* `<a>`（需要有 `href`）
* `<area>`（需要有 `href`）
* `<button>`
* `<img>`
* `<input>`
* `<label>`（需要与 form 控件关联）
* `<textarea>`
* *这份清单并不完整，你可以帮助 MDN 做扩展。*
示例
--

该示例会显示对 `<button>` 的连续点击次数。

### HTML

```html
<button>Click</button>
```

### JavaScript

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

button.addEventListener("click", (event) => {
  button.textContent = `Click count: ${event.detail}`;
});
```

### 结果

尝试快速、重复地点击按钮以增加点击次数。如果你在两次点击之间停止一会儿，计数器将会重置。

规范
--

| Specification |
| --- |
| UI Events # event-type-click |
| HTML Standard # handler-onclick |

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

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

参见
--

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


GlobalEventHandlers.onpointercancel - Web API 接口参考

GlobalEventHandlers.onpointercancel
===================================

A `global event handler` for the `pointercancel` event.

语法
--
```

var cancelHandler = targetElement.onpointercancel;
```

### 返回值

`cancelHandler`

元素`targetElement` 的 *pointercancel* 事件处理器。

示例
--

该示例展示使用 *onpointercancel 设置一个元素的* *pointercancel* 事件处理器的两个方法。

```js
<html>
<script>
function cancelHandler(ev) {
 // 处理 pointercancel 事件
}
function init() {
 var el=document.getElementById("target1");
 el.onpointercancel = cancelHandler;
}
</script>
<body onload="init();">
<div id="target1"> Touch me ... </div>
<div id="target2" onpointercancel="cancelHandler(event)"> Touch me ... </div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| Pointer Events # the-pointercancel-event |
| Pointer Events # dom-globaleventhandlers-onpointercancel |

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

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

参见
--

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


Element.scrollLeft - Web API 接口参考

Element.scrollLeft
==================

**`Element.scrollLeft`** 属性可以读取或设置元素滚动条到元素左边的距离。

注意如果这个元素的内容排列方向（`direction`）是`rtl` (right-to-left) ，那么滚动条会位于最右侧（内容开始处），并且`scrollLeft`值为 0。此时，当你从右到左拖动滚动条时，scrollLeft 会从 0 变为负数。

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

语法
--
```

//获取滚动条到元素左边的距离
var sLeft = element.scrollLeft;
```

`sLeft`是一个整数，代表元素滚动条距离元素左边多少像素。
```

//设置滚动条滚动了多少像素
element.scrollLeft = 10;
```

`scrollLeft` 可以是任意整数，然而：

* 如果元素不能滚动（比如：元素没有溢出），那么`scrollLeft` 的值是 0。
* 如果给`scrollLeft` 设置的值小于 0，那么`scrollLeft` 的值将变为 0。
* 如果给`scrollLeft` 设置的值大于元素内容最大宽度，那么`scrollLeft` 的值将被设为元素最大宽度。
示例
--

### HTML

```html
<div id="container">
  <div id="content">Click the button to slide right!</div>
</div>

<button id="slide" type="button">Slide right</button>
```

### CSS

```css
#container {
  width: 100px;
  height: 100px;
  border: 1px solid #ccc;
  overflow-x: scroll;
}

#content {
  width: 250px;
  background-color: #ccc;
}
```

### JavaScript

```js
const button = document.getElementById("slide");

button.onclick = function () {
  document.getElementById("container").scrollLeft += 20;
};
```

### 结构

规范
--

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

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

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

参见
--

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


GlobalEventHandlers.onscroll - Web API 接口参考

GlobalEventHandlers.onscroll
============================

元素的 `scroll` 事件处理函数。

### 语法
```

element.onscroll = functionReference
```

### 参数

functionReference 是一个函数的引用。当该元素滚动时，会执行该函数。

**备注：** 不要将 onscroll 与 `onwheel`混淆。onwheel 是鼠标滚轮旋转，而 onscroll 处理的是对象内部内容区的滚动事件。

示例
--

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <style>
 #container {
 position: absolute;
 height: auto;
 top: 0;
 bottom: 0;
 width: auto;
 left: 0;
 right: 0;
 overflow: auto;
 }

 #foo {
 height: 1000px;
 width: 1000px;
 background-color: #777;
 display: block;
 }
 </style>
  </head>
  <body>
    <div id="container">
      <div id="foo"></div>
    </div>

    <script type="text/javascript">
 document.getElementById("container").onscroll = function () {
 console.log("scrolling");
 };
 </script>
  </body>
</html>
```

Example
-------

这个示例能说明更多问题

This example monitors scrolling on a `<textarea>`, and logs the element's vertical scroll position accordingly.

### HTML

```html
<textarea>1 2 3 4 5 6 7 8 9</textarea>
<p id="log"></p>
```

### CSS

```css
textarea {
  width: 4rem;
  height: 8rem;
  font-size: 3rem;
}
```

### JavaScript

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

textarea.onscroll = logScroll;

function logScroll(e) {
  log.textContent = `Scroll position: ${e.target.scrollTop}`;
}
```

### Result

注意
--

当用户滚动某个元素的内容时 `scroll` 事件将会被触发。`Element.onscroll` 同等于 `element.addEventListener("scroll" ... )`。

规范
--

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


Element.shadowRoot - Web API 接口参考

Element.shadowRoot
==================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
`Element.shadowRoot` 是只读属性，表示元素挂载的 shadow root。可以使用 `Element.attachShadow` 给一个已存在的元素添加 shadow root。

值
-

可以是一个`ShadowRoot`实例对象，但如果一个 shadow root 的 `mode`被设置为 `closed`那么它的值将会是 `null`。(详情请见 `Element.attachShadow` ).

示例
--

下面代码片段取自 life-cycle-callbacks (在线查看), 在这个示例中我们创建了一个在元素属性中指定了大小和颜色的正方形元素。

在`<custom-square>`标签的 class 定义中我们在生命周期的回调函数里调用了一些外部方法——`updateStyle()`，正是这个函数使得我们添加的正方形元素可以改变大小和颜色。你可以看到我们将`this`（即我们创建的正方形元素本身）作为一个参数传入了这个方法。

```js
connectedCallback() {
  console.log('Custom square element added to page.');
  updateStyle(this);
}

attributeChangedCallback(name, oldValue, newValue) {
  console.log('Custom square element attributes changed.');
  updateStyle(this);
}
```

在`updateStyle()`函数中我们通过`Element.shadowRoot`获取到了 Shadow DOM 引用。在这里我们利用了标准的 DOM 遍历技巧来获取在 Shadow DOM 中`<style>`元素并更新了其中的 CSS 样式：

```js
function updateStyle(elem) {
  const shadow = elem.shadowRoot;
  const childNodes = Array.from(shadow.childNodes);

  childNodes.forEach((childNode) => {
    if (childNode.nodeName === "STYLE") {
      childNode.textContent = `
 div {
 width: ${elem.getAttribute("l")}px;
 height: ${elem.getAttribute("l")}px;
 background-color: ${elem.getAttribute("c")};
 }
 `;
    }
  });
}
```

规范
--

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

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

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


Element.onfullscreenerror - Web API 接口参考

Element.onfullscreenerror
=========================

`Element` 接口的 **`onfullscreenerror`** 属性是在`Element` 过渡到或退出全屏模式发生错误后处理事件`fullscreenerror`的事件处理程序。

语法
--
```

targetElement.onfullscreenerror = fullscreenErrorHandler;
```

### 值

一个处理事件`fullscreenerror`的事件处理程序。

示例
--

本示例尝试不从用户发起的事件 (如点击事件`click`或键盘事件`keypress`) 处理程序来触发全屏，由于全屏模式只允许由用户主动输入触发，因此该操作会发生错误，从而导致`Element`会触发`fullscreenerror`事件传递给错误处理程序

```js
let elem = document.querySelector("video")}}

elem.onfullscreenerror = function ( event ) {
  displayWarning("Unable to switch into full-screen mode.");
};

//....

elem.requestFullscreen();
```

规范
--

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

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

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

参见
--

* Fullscreen API
* Guide to the Fullscreen API
* `fullscreenerror`
* `Element.onfullscreenchange`
* `Document.onfullscreenerror`


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

Element.insertAdjacentElement()
===============================

**`insertAdjacentElement()`** 方法将一个给定的元素节点插入到相对于被调用的元素的给定的一个位置。

语法
--
```

element.insertAdjacentElement(position, element);
```

### 参数

position

A `DOMString` 表示相对于该元素的位置；必须是以下字符串之一：

* `'beforebegin'`: 在该元素本身的前面。
* `'afterbegin'`:只在该元素当中，在该元素第一个子孩子前面。
* `'beforeend'`:只在该元素当中，在该元素最后一个子孩子后面。
* `'afterend'`: 在该元素本身的后面。

element

要插入到树中的元素。

### 返回值

插入的元素，插入失败则返回 null.

### 异常

| 异常 | 说明 |
| --- | --- |
| `SyntaxError` | 插入的位置是一个无法识别的值。 |
| `TypeError` | 插入的元素不是一个有效元素。 |

### 位置命名的可视化展示

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

**备注：** 当节点处于 DOM 树中而且有一个父元素的时候 `beforebegin` 和 `afterend` 操作才能起作用。

例子
--

```js
beforeBtn.addEventListener("click", function () {
  var tempDiv = document.createElement("div");
  tempDiv.style.backgroundColor = randomColor();
  activeElem.insertAdjacentElement("beforebegin", tempDiv);
  setListener(tempDiv);
});

afterBtn.addEventListener("click", function () {
  var tempDiv = document.createElement("div");
  tempDiv.style.backgroundColor = randomColor();
  activeElem.insertAdjacentElement("afterend", tempDiv);
  setListener(tempDiv);
});
```

看看我们在 Github（也可以参考 源码）上的 insertAdjacentElement.html 演示。在一个容器当中我们有一组`<div>` 元素。点击其中一个 div 时，这个容器会处于选中状态，然后你就可以按下*Insert before* 或*Insert after* 按钮通过 `insertAdjacentElement() 方法`来把一个新的 divs 插入到选中的元素前面或者后面。

规范
--

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

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

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

参见
--

* `Element.insertAdjacentHTML()`
* `Element.insertAdjacentText()`
* `Node.insertBefore()`
* `Node.appendChild()` (same effect as `beforeend`)


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

Element.remove()
================

**`Element.remove()`** 方法，把对象从它所属的 DOM 树中删除。

语法
--
```

node.remove();
```

示例
--

### 使用 `remove()`

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

```js
var el = document.getElementById("div-02");
el.remove();
// id 为 'div-02' 的 div 被删掉了
```

### `Element.remove()` 是不可见的

在 `with` 语句中，`remove()` 方法是不可见的。参阅 `Symbol.unscopables` 了解更多信息。

```js
with (node) {
  remove();
}
// ReferenceError: remove is not defined
```

规范
--

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

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

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

参见
--

* `ChildNode` 纯接口。
* 实现此纯接口的对象类型： `CharacterData`、`Element` , 和 `DocumentType`.


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

Element.getAttribute()
======================

概要
--

**`getAttribute()`** 返回元素上一个指定的属性值。如果指定的属性不存在，则返回 `null` 或 `""` （空字符串）；具体细节，请参阅 Notes 部分。

语法
--
```

let attribute = element.getAttribute(attributeName);
```

上面：

* `attribute` 是一个包含 `attributeName` 属性值的字符串。
* `attributeName` 是你想要获取的属性值的属性名称。
例子
--

```js
let div1 = document.getElementById("div1");
let align = div1.getAttribute("align");

alert(align);
// shows the value of align for the element with id="div1"
```

备注
--

当在被标记为 HTML 文档中的一个 HTML 元素上调用此方法时，`getAttribute()` 会先将其参数转换为小写形式。

当指定的属性不存在于元素上时，所有浏览器（Firefox、Internet Explorer、Opera 最新版本、Safari、Konqueror 以及 iCab 等等）都返回 `null`，这也是当前 DOM 规范草案规定的。然而，旧的 DOM 3 Core specification 认为此时正确的返回值应该是一个空字符串，一些 DOM 实现环境实现了该行为（behavior）。在 XUL (Gecko) 中，getAttribute 的实现遵从 DOM 3 Core specification，返回一个空字符串。因此，如果一个属性可能不存在于指定的元素上，在调用 `getAttribute()` 之前，你应该使用 `element.hasAttribute()` 来检测该属性是否存在。

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

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

规范
--

* DOM Level 2 Core: getAttribute (introduced in DOM Level 1 Core)
* HTML 5: APIs in HTML documents


compositionupdate - Web API 接口参考

compositionupdate
=================

**`compositionupdate`** 事件触发于字符被输入到一段文字的时候（这些可见字符的输入可能需要一连串的键盘操作、语音识别或者点击输入法的备选词）

|  |  |
| --- | --- |
| Bubbles | Yes |
| Cancelable | No |
| Target objects | `Element` |
| Interface | `TouchEvent` |

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | 焦点所在的，处理文字输入的元素。 |
| `type` 只读  | `DOMString` | The type of event. |
| `bubbles` 只读  | `boolean` | Does the event normally bubble? |
| `cancelable` 只读  | `boolean` | Is it possible to cancel the event? |
| `view` 只读  | `WindowProxy` | `Document.defaultView` (the `window` of the document). |
| `detail` 只读  | `long` (`float`) | 0. |
| `data` 只读  | `DOMString` (string) | 要被替换掉的字符串，如果输入时没有字符串被选，则为空字符串。只读。 |
| `locale` 只读  | `DOMString` (string) | 输入事件的语言代号，或者空字符串。只读。 |

规范
--

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

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

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

参阅
--

* `compositionstart`
* `compositionupdate`
* `compositionend`


Element.clientTop - Web API 接口参考

Element.clientTop
=================

一个元素顶部边框的宽度（以像素表示）。不包括顶部外边距或内边距。`clientTop` 是只读的。

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

语法
--

```js
var top = element.clientTop;
```

示例
--

padding-top

Gentle, individualistic and very loyal, Birman cats fall between Siamese and Persian in character. If you admire cats that are non aggressive, that enjoy being with humans and tend to be on the quiet side, you may well find that Birman cats are just the felines for you.

All Birmans have colorpointed features, dark coloration of the face, ears, legs and tail.

Cat image and text coming from www.best-cat-art.com

padding-bottom

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

备注
--

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

参见
--

* MSDN: Measuring Element Dimension and Location


GlobalEventHandlers.onlostpointercapture - Web API 接口参考

GlobalEventHandlers.onlostpointercapture
========================================

The **`onlostpointercapture`** event handler property of the `GlobalEventHandlers` interface returns the event handler (function) for the `lostpointercapture` event type.

语法
--
```

window.onlostpointercapture = functionReference
```

示例
--

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

规范
--

| Specification |
| --- |
| Pointer Events # the-lostpointercapture-event |
| Pointer Events # dom-globaleventhandlers-onlostpointercapture |

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

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

参见
--

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


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

Element.removeAttribute()
=========================

`元素`方法 **`removeAttribute()`** 从指定的元素中删除一个属性。

### 语法
```

element.removeAttribute(attrName);
```

### 参数

属性名

`DOMString`指定要从元素中移除的属性的名称。如果指定的属性不存在，则 removeAttribute() 返回，但不会生成错误。

### 返回值

IE 返回 boolean 类型值，其他返回 undefined

**备注：** 因为 `removeAttribute()` 不会返回任何有效值，你不能使用链式方法（连续使用方法，例如 `document.body.removeAttribute("first").removeAttribute("second")…`）连续移除多个属性。

使用说明
----

若要彻底移除一个属性的效果，应当使用 `removeAttribute()`，而不是使用 `setAttribute()` 将属性值设置为 `null`。对于许多属性，如果仅将其值设为 `null`，这不会造达成和预期一样的效果。

DOM methods dealing with element's attributes:

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

例子
--

```js
// Given: <div id="div1" align="left" width="200px">
document.getElementById("div1").removeAttribute("align");
// Now: <div id="div1" width="200px">
```

规范
--

DOM Level 2 Core: removeAttribute (introduced in DOM Level 1 Core)

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

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


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

Element：mousedown 事件
====================

**`mousedown`** 事件在定点设备（如鼠标或触摸板）按钮在元素内按下时，会在该元素上触发。

**备注：** 其与 `click` 事件的区别是，`click` 事件在完整的单击操作完成后触发；也就是说，`click` 事件在按下并释放鼠标按钮后并且指针仍在同一元素内时触发。`mousedown` 事件在按下鼠标按钮的那一刻触发。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent事件属性
----

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

`MouseEvent.altKey` 只读

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

`MouseEvent.button` 只读

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

`MouseEvent.buttons` 只读

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

`MouseEvent.clientX` 只读

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

`MouseEvent.clientY` 只读

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

`MouseEvent.ctrlKey` 只读

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

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

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

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

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

`MouseEvent.metaKey` 只读

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

`MouseEvent.movementX` 只读

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

`MouseEvent.movementY` 只读

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

`MouseEvent.offsetX` 只读

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

`MouseEvent.offsetY` 只读

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

`MouseEvent.pageX` 只读

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

`MouseEvent.pageY` 只读

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

`MouseEvent.relatedTarget` 只读

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

`MouseEvent.screenX` 只读

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

`MouseEvent.screenY` 只读

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

`MouseEvent.shiftKey` 只读

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

`MouseEvent.mozInputSource`
非标准
 只读

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

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

单击时施加的压力大小。

`MouseEvent.x` 只读

`MouseEvent.clientX` 的别名。

`MouseEvent.y` 只读

`MouseEvent.clientY` 的别名。

示例
--

参见 `mousemove` 事件的示例。

规范
--

| Specification |
| --- |
| UI Events # event-type-mousedown |
| HTML Standard # handler-onmousedown |

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

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

参见
--

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


GlobalEventHandlers.onanimationiteration - Web API 接口参考

GlobalEventHandlers.onanimationiteration
========================================

`animationiteration`事件的处理器 . 当 CSS Animation 运动到最后一帧时触发。An iteration ends when a single pass through the sequence of animation instructions is completed by executing the last animation step.

语法
--
```

var animIterationHandler = target.onanimationiteration;

target.onanimationiteration = `Function`
```

### Value

A `Function` to be called when an `animationiteration` event occurs indicating that a CSS animation has reached the end of an iteration while running on the *`target`*, where the target object is an HTML element (`HTMLElement`), document (`Document`), or window (`Window`). The function receives as input a single parameter: an `AnimationEvent` (en-US) object describing the event which occurred.

示例
--

Let's create an animation which automatically pauses at the end of each iteration, allowing the user to choose whether or not to start the next iteration. Much of this code is the same as in other examples of animation events, so it may look familiar.
```

<div class="main">
  <div id="box">
    <div id="text">Box</div>
  </div>
</div>

<div class="button" id="play">Begin Demonstration</div>
```

### CSS
```

:root {
  --boxwidth: 50px;
}

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

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

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

Leaving out some bits of the CSS that don't matter for the discussion here, let's take a look at the styles for the box that we're animating. First is the box itself. We set its size, position, color, and layout. Note that there's nothing there about animation. That's because we don't want the box to start animating right away. We'll add the `animation` style later to start animating the box.

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

The animation's keyframes are defined next; they describe an animation which causes the box to migrate from the top-left corner of the container to the bottom-right corner.

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

### JavaScript

Some JavaScript code will need to be written to handle the click on the button to start the next iteration. Let's have a look.

```js
var box = document.getElementById("box");
var iterationCounter = 0;

box.onanimationiteration = function (event) {
  box.style.animationPlayState = "paused";
  document.getElementById("play").innerHTML =
    "Start Iteration #" + (iterationCounter + 1);
};
```

This sets up two global variables: `box`, which references the `"box"` element that we're animating, and `iterationCounter`, which is initially zero, which indicates how many iterations of the animation have occurred.

The onanimationiteration event handler is then set up. It simply sets the box's `animation-play-state` to "paused", then updates the text displayed in the button to indicate that clicking the button will start playing the next iteration of theanimation.

Finally, we set up a handler for a click on the button that runs the animation:

```js
document.getElementById("play").addEventListener(
  "click",
  function (event) {
    box.style.animationPlayState = "running";
    iterationCounter++;
  },
  false,
);
```

This sets the box element's `animation-play-state` to "running" and increments the iteration counter. That's all there is to it!

### 结果

Assembled together, you get this:

Each time the box reaches the opposing corner, it stops, with the button reflecting which iteration number is up next, until you click the button to run the next iteration.

规范
--

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

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

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

参见
--

* The `animationiteration` event this event handler is triggered by.
* `AnimationEvent` (en-US)


touchend - Web API 接口参考

touchend
========

当触点离开触控平面时触发`touchend`事件。

常规信息
----

规范

Touch Events

接口

TouchEvent

是否冒泡

Yes

能否取消默认行为

Yes

目标

Document, Element

默认行为

无

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | EventTarget | The event target (the topmost target in the DOM tree). |
| `type` 只读  | DOMString | The type of event. |
| `bubbles` 只读  | Boolean | Whether the event normally bubbles or not. |
| `cancelable` 只读  | Boolean | Whether the event is cancellable or not. |
| `view` 只读  | WindowProxy | `document.defaultView` (`window` of the document) |
| `detail` 只读  | long (float) | 0. |
| `touches` 只读  | TouchList | A list of `Touch`es for every point of contact currently touching the surface. |
| `targetTouches` 只读  | TouchList | A list of `Touch`es for every point of contact that is touching the surface and started on the element that is the target of the current event. |
| `changedTouches` 只读  | TouchList | A list of `Touch`es for every point of contact which contributed to the event. For the touchstart event this must be a list of the touch points that just became active with the current event. For the touchmove event this must be a list of the touch points that have moved since the last event. For the touchend and touchcancel events this must be a list of the touch points that have just been removed from the surface. |
| `ctrlKey` 只读  | boolean | `true` if the control key was down when the event was fired. `false` otherwise. |
| `shiftKey` 只读  | boolean | `true` if the shift key was down when the event was fired. `false` otherwise. |
| `altKey` 只读  | boolean | `true` if the alt key was down when the event was fired. `false` otherwise. |
| `metaKey` 只读  | boolean | `true` if the meta key was down when the event was fired. `false` otherwise. |

例子
--

这些事件的代码示例在这个页面Touch events中均有体现。

规范
--

| Specification |
| --- |
| Touch Events # event-touchend |
| Touch Events # dom-globaleventhandlers-ontouchend |

Related Events
--------------

* `touchstart`
* `touchend`
* `touchmove`
* `touchcancel`


Element.clientHeight - Web API 接口参考

Element.clientHeight
====================

只读属性 **`Element.clientHeight`** 对于没有定义 CSS 或者内联布局盒子的元素为 0；否则，它是元素内部的高度（以像素为单位），包含内边距，但不包括边框、外边距和水平滚动条（如果存在）。

`clientHeight` 可以通过 CSS `height` + CSS `padding` - 水平滚动条高度（如果存在）来计算。

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

**备注：** 此属性会将获取的值四舍五入取整数。如果你需要小数结果，请使用 `element.getBoundingClientRect()`。

值
-

一个数字。

示例
--

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

规范
--

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

### 备注

`clientHeight` 是在 IE 浏览器对象模型中引入的属性。

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

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

参见
--

* `HTMLElement.offsetHeight`
* `Element.scrollHeight`
* 确定元素的宽高


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

Element：mouseup 事件
==================

**`mousedown`** 事件在定点设备（如鼠标或触摸板）按钮在元素内释放时，在该元素上触发。

`mouseup` 事件与 `mousedown` 事件相对应。

语法
--

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

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

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

事件类型
----

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

Event

UIEvent

MouseEvent事件属性
----

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

`MouseEvent.altKey` 只读

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

`MouseEvent.button` 只读

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

`MouseEvent.buttons` 只读

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

`MouseEvent.clientX` 只读

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

`MouseEvent.clientY` 只读

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

`MouseEvent.ctrlKey` 只读

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

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

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

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

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

`MouseEvent.metaKey` 只读

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

`MouseEvent.movementX` 只读

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

`MouseEvent.movementY` 只读

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

`MouseEvent.offsetX` 只读

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

`MouseEvent.offsetY` 只读

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

`MouseEvent.pageX` 只读

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

`MouseEvent.pageY` 只读

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

`MouseEvent.relatedTarget` 只读

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

`MouseEvent.screenX` 只读

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

`MouseEvent.screenY` 只读

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

`MouseEvent.shiftKey` 只读

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

`MouseEvent.mozInputSource`
非标准
 只读

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

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

单击时施加的压力。

`MouseEvent.x` 只读

`MouseEvent.clientX` 的别名。

`MouseEvent.y` 只读

`MouseEvent.clientY` 的别名。

示例
--

参见 `mousemove` 事件的示例。

规范
--

| Specification |
| --- |
| UI Events # event-type-mouseup |
| HTML Standard # handler-onmouseup |

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

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

参见
--

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


mousewheel - Web API 接口参考

mousewheel
==========

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

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

*过时*且*非标准*的 `mousewheel` 事件在元素上异步触发，以在操作鼠标滚轮或类似设备时提供更新。`mousewheel` 事件从未成为任何标准的一部分，虽然它被多个浏览器实现，但 Firefox 从未实现过该事件。

**备注：** 请改用标准的 `wheel` 事件，而不是这个过时的事件。

语法
--

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

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

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

事件类型
----

`wheelEvent`。继承自 `Event`。

Event

UIEvent

MouseEvent

WheelEvent事件属性
----

*该接口继承了其祖先接口 `MouseEvent`、`UIEvent` 和 `Event` 的属性。*

`WheelEvent.deltaX` 只读

返回一个表示水平滚动量的双精度浮点数（`double`）。

`WheelEvent.deltaY` 只读

返回一个表示垂直滚动量的双精度浮点数（`double`）。

`WheelEvent.deltaZ` 只读

返回一个表示 Z 轴滚动量的双精度浮点数（`double`）。

`WheelEvent.deltaMode` 只读

返回一个无符号长整型（`unsigned long`)，其表示 `delta*` 值的滚动数量的单位。允许的值如下：

| 常量 | 值 | 描述 |
| --- | --- | --- |
| `WheelEvent.DOM_DELTA_PIXEL` | `0x00` | `delta*` 值以像素为单位为准。 |
| `WheelEvent.DOM_DELTA_LINE` | `0x01` | `delta*` 值以行为单位指定。每次鼠标单击滚动一个内容行，而计算行高度的方法取决于浏览器。 |
| `WheelEvent.DOM_DELTA_PAGE` | `0x02` | `delta*` 值以页为单位指定。每次鼠标单击滚动一个页面的内容。 |

`WheelEvent.wheelDelta` 只读
已弃用

返回一个表示像素距离的整数（32 位）。

`WheelEvent.wheelDeltaX` 只读
已弃用

返回一个表示水平滚动量的整数。

`WheelEvent.wheelDeltaY` 只读
已弃用

返回一个表示垂直滚动量的整数。

详细属性
----

`detail` 属性的值始终为零，除了 Opera 之外。Opera 使用 `detail` 属性与仅适用于 Firefox 的 `DOMMouseScroll` (en-US) 事件的 `detail` 值类似，该值表示以行为单位的滚动距离，负值表示滚动向底部或右侧移动，正值表示向顶部或左侧滚动。

**备注：** 在 macOS 上，滚动距离（以及 `detail` 的值）是根据加速滚动距离计算的。

wheelDelta、wheelDeltaX 和 wheelDeltaY 的值
---------------------------------------

`wheelDelta` 属性值是一个抽象值，表示滚轮转动的距离。如果滚轮向用户旋转，则该值为正，否则为负。这意味着 delta 值的符号与 DOM Level 3 事件的 `wheel` 属性不同。然而，这些值的数量意义在不同的浏览器中也不相同。详见以下说明。

IE 和 Opera（Presto）仅支持 `wheelDelta` 属性，不支持水平滚动。

`wheelDeltaX` 属性值表示沿水平轴的 `wheelDelta` 属性值。当用户操作设备向右滚动时，该值为负。反之，即向左滚动时，该值为正。

`wheelDeltaY` 属性值表示沿垂直轴的 `wheelDelta` 属性值。该值的符号与 `wheelDelta` 属性值相同：向用户滚动时为正，向远离用户的方向滚动时为负。

### Chrome

在 Windows 上，该值与 `WM_MOUSEWHEEL` 或 `WM_MOUSEHWHEEL` 的 delta 值相同。并且，即使系统设置的滚动量为页面滚动，该值也不会改变，即该值与 Windows 上的 IE 相同。

在 Linux 上，本机滚轮事件每次的值为 `120` 或 `-120`。这使得行为与 Windows 上的 IE 和 Chrome 相同。

如果**设备**支持连续滚动（例如，MacBook 的触摸板或可以平滑旋转的鼠标滚轮），则该值从加速滚动量计算而得。在这种情况下，该值与 Safari 一致。

如果设备**不**支持连续滚动（通常是旧的无法平滑旋转的鼠标滚轮），则该值从非加速滚动量（每个齿轮 120）计算而得。在这种情况下，该值与 Safari 不同。

这种差异对 Web 应用程序开发人员来说是一个严重的问题。也就是说，Web 开发人员无法知道 `mousewheel` 事件是由哪个设备引起的。

### Safari

该值始终是从加速滚动量计算而来的。这与除支持连续滚动的设备的 Chrome 之外的其他浏览器非常不同。

### Opera（Presto）

该值始终是 `detail` 属性值 ✕ `40`。

在 Windows 上，由于 `detail` 属性值是从实际滚动量计算得出的，因此该值与其他浏览器不同，除非系统设置或页面中的每个滚动步距为 3 行。

在 Linux 上，每个原生滚轮事件的值为 `80` 或 `-80`。这与其他浏览器不同。

在 Mac 上，`detail` 属性值是从原生事件的加速滚动量计算得出的。该值通常比 Safari 或 Chrome 的值要大得多。

规范
--

不属于任何规范。

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

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

参见
--

* 请改用标准的 `wheel` 事件来监听。