recursal/MDN huggingface dataset:
DataTransfer.types
==================

**`DataTransfer.types`** 是只读属性。它返回一个我们在`dragstart`事件中设置的拖动数据格式 (如 `字符串`) 的数组。格式顺序与拖动操作中包含的数据顺序相同。

这些格式是指定数据类型或格式的 Unicode 字符串，通常由 MIME 类型给出。一些非 MIME 类型的值是由于历史遗留原因（例如“text”）而特殊设置的。

语法
--
```

dataTransfer.types;
```

### 返回值

拖动操作中使用的数据格式数组。每种格式都是`字符串`类型。如果拖动操作不包含数据，则此数组列表将为空。如果拖动操作中包含任何文件，则其中一个类型将是 `Files`。

示例
--

这个例子展示 `types` 和 `items` 属性的用法


```html
<!doctype html>
<html lang="en">
  <title>Examples of DataTransfer.{types,items} properties</title>
  <meta content="width=device-width" />
  <style>
 div {
 margin: 0em;
 padding: 2em;
 }
 #target {
 border: 1px solid black;
 }
 </style>
  <script>
 function dragstart\_handler(ev) {
 console.log("dragStart: target.id = " + ev.target.id);

 // Add this element's id to the drag payload so the drop handler will
 // know which element to add to its tree
 ev.dataTransfer.setData("text/plain", ev.target.id);
 ev.dataTransfer.effectAllowed = "move";
 }

 function drop\_handler(ev) {
 console.log("drop: target.id = " + ev.target.id);
 ev.preventDefault();

 // Get the id of the target and add the moved element to the target's DOM
 const data = ev.dataTransfer.getData("text");
 ev.target.appendChild(document.getElementById(data));

 // Print each format type
 for (let i = 0; i < ev.dataTransfer.types.length; i++) {
 console.log(`… types[${i}] = ${ev.dataTransfer.types[i]}`);
 }

 // Print each item's "kind" and "type"
 for (let i = 0; i < ev.dataTransfer.items.length; i++) {
 console.log(
 `… items[${i}].kind = ${ev.dataTransfer.items[i].kind}; type = ${ev.dataTransfer.items[i].type}`,
 );
 }
 }

 function dragover\_handler(ev) {
 console.log("dragOver");
 ev.preventDefault();
 // Set the dropEffect to move
 ev.dataTransfer.dropEffect = "move";
 }
 </script>
  <body>
    <h1>
      Examples of <code>DataTransfer</code>.{<code>types</code>,
      <code>items</code>} properties
    </h1>
    <ul>
      <li id="i1" ondragstart="dragstart\_handler(event);" draggable="true">
        Drag Item 1 to the Drop Zone
      </li>
      <li id="i2" ondragstart="dragstart\_handler(event);" draggable="true">
        Drag Item 2 to the Drop Zone
      </li>
    </ul>
    <div
 id="target"
 ondrop="drop\_handler(event);"
 ondragover="dragover\_handler(event);">
      Drop Zone
    </div>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-types-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐的拖拽类型
* DataTransfer 测试——粘贴或拖拽
DataTransfer.setData()
======================

**`DataTransfer.setData()`** 方法用来设置拖放操作的`drag data`到指定的数据和类型。

如果给定类型的数据不存在，则将其添加到拖动数据存储的末尾，使得 `types` 列表中的最后一个项目将是新类型。

如果给定类型的数据已经存在，现有数据将被替换为相同的位置。也就是说，替换相同类型的数据时 `types`列表的顺序不会更改。

示例数据类型为："`text/plain`" 和 "`text/uri-list`".

语法
--
```

void dataTransfer.setData(format, data);
```

### 参数

*format*

一个`DOMString` 表示要添加到 `drag object`的拖动数据的类型。

*data*

一个 `DOMString`表示要添加到 `drag object`的数据。

### 返回值

无

示例
--

此示例显示了使用 `DataTransfer` 对象的 `getData()`, `setData()` }和`clearData()` 方法。


```html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>DataTransfer.setData()/.getData()/.clearData()</title>
    <style>
 div {
 margin: 0em;
 padding: 2em;
 }
 #source {
 color: blue;
 border: 1px solid black;
 }
 #target {
 border: 1px solid black;
 }
 </style>
  </head>
  <body>
    <section>
      <h1>
        <code>DataTransfer.setData()</code> <br />
        <code>DataTransfer.getData()</code> <br />
        <code>DataTransfer.clearData()</code>
      </h1>
      <div>
        <p id="source" ondragstart="dragstart\_handler(event);" draggable="true">
          Select this element, drag it to the Drop Zone and then release the
          selection to move the element.
        </p>
      </div>
      <div
 id="target"
 ondrop="drop\_handler(event);"
 ondragover="dragover\_handler(event);">
        Drop Zone
      </div>
    </section>
    <!-- js -->
    <script>
 function dragstart\_handler(ev) {
 console.log("dragStart");
 // Change the source element's background color to signify drag has started
 ev.currentTarget.style.border = "dashed";
 // Set the drag's format and data. Use the event target's id for the data
 ev.dataTransfer.setData("text/plain", ev.target.id);
 }

 function dragover\_handler(ev) {
 console.log("dragOver");
 // prevent Default event
 ev.preventDefault();
 }

 function drop\_handler(ev) {
 console.log("Drop");
 ev.preventDefault();
 // Get the data, which is the id of the drop target
 var data = ev.dataTransfer.getData("text");
 // appendChild
 ev.target.appendChild(document.getElementById(data));
 // Clear the drag data cache (for all formats/types)
 ev.dataTransfer.clearData();
 }
 </script>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-setdata-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐的拖拽类型
* DataTransfer 测试——粘贴或拖拽
DataTransfer.setDragImage()
===========================

发生拖动时，从拖动目标 (`dragstart`事件触发的元素) 生成半透明图像，并在拖动过程中跟随鼠标指针。这个图片是自动创建的，你不需要自己去创建它。然而，如果想要设置为自定义图像，那么 **`DataTransfer.setDragImage()`** 方法就能派上用场。

图像通常是一个 `<image>` 元素，但也可以是`<canvas>` 或任何其他图像元素。该方法的 x 和 y 坐标是图像应该相对于鼠标指针出现的偏移量。

坐标指定鼠标指针相对于图片的偏移量。例如，要使图像居中，请使用图像宽度和高度的一半。

通常在 `dragstart` 事件处理程序中调用此方法。

语法
--
```

void dataTransfer.setDragImage(img, xOffset, yOffset);
```

### 参数

*img |* Element

用于拖曳反馈图像的图像 `Element` 元素。

如果 Element 是一个 img 元素，则将拖动位图设置为该元素的图像（保持大小）；否则，将拖动数位图设置为从给定元素所生成的图片（当前尚未指定执行此操作的确切机制）

*xOffset*

使用 `long` 指示相对于图片的横向偏移量

*yOffset*

使用 `long` 指示相对于图片的纵向偏移量

### 返回值

无

示例
--

这个例子展示如何使用 `setDragImage()` 方法。请注意，此例子引用了命名为 `example.gif` 的图片文件。如果此文件存在，它将被用作拖动图像，如果此文件不存在，浏览器会使用其默认的拖动图像。


```js
<!DOCTYPE html>
<html lang=en>
<title>Example of DataTransfer.setDragImage()</title>
<meta name="viewport" content="width=device-width">
<style>
  div {
    margin: 0em;
    padding: 2em;
  }
  #source {
    color: blue;
    border: 1px solid black;
  }
  #target {
    border: 1px solid black;
  }
</style>
<script>
function dragstart\_handler(ev) {
 console.log("dragStart");
 // 设置拖动的格式和数据。使用事件目标的 id 作为数据
 ev.dataTransfer.setData("text/plain", ev.target.id);
 // 创建一个图像并且使用它作为拖动图像
 // 请注意：改变 "example.gif" 为一个已经存在的图片
 // 或者，一个还没有创建出来的图片，那么浏览器将会使用默认的拖动图片
 // 译者注：默认的拖动图片与拖动对象没有联系。一般是一个小型文件图标
 var img = new Image();
 img.src = 'example.gif';
 ev.dataTransfer.setDragImage(img, 10, 10);
}

function dragover\_handler(ev) {
 console.log("dragOver");
 ev.preventDefault();
}

function drop\_handler(ev) {
 console.log("Drop");
 ev.preventDefault();
 // 获取拖放目标的 id 数据
 var data = ev.dataTransfer.getData("text");
 ev.target.appendChild(document.getElementById(data));
}
</script>
<body>
<h1>Example of <code>DataTransfer.setDragImage()</code></h1>
 <div>
   <p id="source" ondragstart="dragstart\_handler(event);" draggable="true">
     Select this element, drag it to the Drop Zone and then release the selection to move the element.</p>
 </div>
 <div id="target" ondrop="drop\_handler(event);" ondragover="dragover\_handler(event);">Drop Zone</div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-setdragimage-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐的拖拽类型
* DataTransfer 测试——粘贴或拖拽
DataTransfer.items
==================

`DataTransfer`的`items` 属性只读，是拖动操作中 `数据传输项`的`列表`。该列表包含了操作中每一项目的对应项，如果操作没有项目，则列表为空。

语法
--
```

itemList = dataTransfer.items;
```

### 返回值

一个`DataTransferItemList` 对象，包含了表示拖动操作中被拖动项的`DataTransferItem`对象，每一个拖动项对应一个列表项。如果拖动操作中没有数据，则列表为空。

示例
--

这个例子演示了 `items` 和 `types` 属性的用法。


```js
<!DOCTYPE html>
<html lang=en>
<title>Examples of DataTransfer.{types,items} properties</title>
<meta content="width=device-width">
<style>
  div {
    margin: 0em;
    padding: 2em;
  }
  #target {
    border: 1px solid black;
  }
</style>
<script>
function dragstart\_handler(ev) {
 console.log("dragStart: target.id = " + ev.target.id);
 // Add this element's id to the drag payload so the drop handler will
 // know which element to add to its tree
 ev.dataTransfer.setData("text/plain", ev.target.id);
 ev.dataTransfer.effectAllowed = "move";
}

function drop\_handler(ev) {
 console.log("drop: target.id = " + ev.target.id);
 ev.preventDefault();
 // Get the id of the target and add the moved element to the target's DOM
 var data = ev.dataTransfer.getData("text");
 ev.target.appendChild(document.getElementById(data));
 // Print each format type
 if (ev.dataTransfer.types != null) {
   for (var i=0; i < ev.dataTransfer.types.length; i++) {
     console.log("... types[" + i + "] = " + ev.dataTransfer.types[i]);
   }
 }
 // Print each item's "kind" and "type"
 if (ev.dataTransfer.items != null) {
   for (var i=0; i < ev.dataTransfer.items.length; i++) {
     console.log("... items[" + i + "].kind = " + ev.dataTransfer.items[i].kind + " ; type = " + ev.dataTransfer.items[i].type);
   }
 }
}

function dragover\_handler(ev) {
 console.log("dragOver");
 ev.preventDefault();
 // Set the dropEffect to move
 ev.dataTransfer.dropEffect = "move"
}
</script>
<body>
<h1>Examples of <code>DataTransfer</code>.{<code>types</code>, <code>items</code>} properties</h1>
 <ul>
   <li id="i1" ondragstart="dragstart\_handler(event);" draggable="true">Drag Item 1 to the Drop Zone</li>
   <li id="i2" ondragstart="dragstart\_handler(event);" draggable="true">Drag Item 2 to the Drop Zone</li>
 </ul>
 <div id="target" ondrop="drop\_handler(event);" ondragover="dragover\_handler(event);">Drop Zone</div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-items-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐的拖拽类型
* DataTransfer 测试——粘贴或拖拽
DataTransfer.getData()
======================

**`DataTransfer.getData()`** 方法接受指定类型的拖放（以`DOMString`的形式）数据。如果拖放行为没有操作任何数据，会返回一个空字符串。

数据类型有：`text/plain`，`text/uri-list`。

语法
--
```

DOMString dataTransfer.getData(format);
```

### 参数

*format*

`DOMString`类型

### 返回值

`DOMString`

返回一个给定类型的`DOMString`格式的数据。如果没有操作数据或者没有指定操作数据的类型，都会返回一个空字符串。

### 注意

HTML5 拖放规范 规定了一个 `drag data store mode`。这可能会导致预期外的结果，即 **`DataTransfer.getData()`** 没有返回预期值。

示例
--

这个例子展示了 `DataTransfer`对象的`getData()`和`setData()`方法。

### HTML


```html
<div id="div1" ondrop="drop(event)" ondragover="allowDrop(event)">
  <span id="drag" draggable="true" ondragstart="drag(event)"
 >drag me to the other box</span
 >
</div>
<div id="div2" ondrop="drop(event)" ondragover="allowDrop(event)"></div>
```

### CSS


```css
#div1,
#div2 {
  width: 100px;
  height: 50px;
  padding: 10px;
  border: 1px solid #aaaaaa;
}
```

### JavaScript


```js
function allowDrop(allowdropevent) {
  allowdropevent.target.style.color = "blue";
  allowdropevent.preventDefault();
}

function drag(dragevent) {
  dragevent.dataTransfer.setData("text", dragevent.target.id);
  dragevent.target.style.color = "green";
}

function drop(dropevent) {
  dropevent.preventDefault();
  var data = dropevent.dataTransfer.getData("text");
  dropevent.target.appendChild(document.getElementById(data));
  document.getElementById("drag").style.color = "black";
}
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-getdata-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐的拖拽类型
* DataTransfer 测试——粘贴或拖拽
DataTransfer.effectAllowed
==========================

**`DataTransfer.effectAllowed`** 属性指定拖放操作所允许的一个效果。*copy* 操作用于指示被拖动的数据将从当前位置复制到放置位置。*move* 操作用于指定被拖动的数据将被移动。*link* 操作用于指示将在源和放置位置之间创建某种形式的关系或连接。

应该在`dragstart`事件中设置此属性，以便为拖动源设置所需的拖动效果。在 `dragenter` 和`dragover` 事件处理程序中，该属性将设置为在`dragstart` 事件期间分配的任何值，因此，可以使用`effectAllowed`来确定允许哪个效果。

给`effectAllowed`赋一个值，以使其在除`dragstart` 之外的事件中无效。

语法
--
```

dataTransfer.effectAllowed;
```

### 值

表示允许的拖动操作`DOMString` 。这个可能值是：

none

此项表示不允许放下

copy

源项目的复制项可能会出现在新位置。

copyLink

允许 *copy* 或者 *link* 操作。

copyMove

允许 *copy* 或者 *move* 操作。

link

可以在新地方建立与源的链接。

linkMove

允许 *link* 或者 *move* 操作。

move

一个项目可能被移动到新位置。

all

允许所有的操作。

uninitialized

效果没有设置时的默认值，则等同于 *all*。

分配一个没有效果的其他值给 `effectAllowed`，则保留原值。

Internet Explorer 会将该值改为小写。因此，`linkMove`将会变为 `linkmove`，等等。

示例
--

此例子展示 `effectAllowed` 用法 和 `dropEffect` 属性


```js
<!DOCTYPE html>
<html lang=en>
<title>Examples of DataTransfer.{dropEffect,effectAllowed} properties</title>
<meta content="width=device-width">
<style>
  div {
    margin: 0em;
    padding: 2em;
  }
  #source {
    color: blue;
    border: 1px solid black;
  }
  #target {
    border: 1px solid black;
  }
</style>
<script>
function dragstart\_handler(ev) {
 console.log("dragStart: dropEffect = " + ev.dataTransfer.dropEffect + " ; effectAllowed = " + ev.dataTransfer.effectAllowed);
 // 将这个元素的 id 添加到 drag 载荷中，
 // 以便 drop 事件知道将哪个元素添加到其树中。
 ev.dataTransfer.setData("text", ev.target.id);
 ev.dataTransfer.effectAllowed = "move";
}

function drop\_handler(ev) {
 console.log("drop: dropEffect = " + ev.dataTransfer.dropEffect + " ; effectAllowed = " + ev.dataTransfer.effectAllowed);
 ev.preventDefault();
 // 得到目标的 id 并且将移动的元素添加到目标 DOM 中
 var data = ev.dataTransfer.getData("text");
 ev.target.appendChild(document.getElementById(data));
}

function dragover\_handler(ev) {
 console.log("dragOver: dropEffect = " + ev.dataTransfer.dropEffect + " ; effectAllowed = " + ev.dataTransfer.effectAllowed);
 ev.preventDefault();
 // 设置 dropEffect 为 move
 ev.dataTransfer.dropEffect = "move"
}
</script>
<body>
<h1>Examples <code>DataTransfer</code>.{<code>dropEffect</code>, <code>effectAllowed</code>} properties</h1>
 <div>
   <p id="source" ondragstart="dragstart\_handler(event);" draggable="true">
     Select this element, drag it to the Drop Zone and then release the selection to move the element.</p>
 </div>
 <div id="target" ondrop="drop\_handler(event);" ondragover="dragover\_handler(event);">Drop Zone</div>
</body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-effectallowed-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐的拖拽类型
* DataTransfer 测试——粘贴或拖拽
DataTransfer.files
==================

\*\*`DataTransfer.files`\*\*属性在拖动操作中表示`文件列表`。如果操作不包含文件，则此列表为空。

此功能可用于将文件从用户桌面拖动到浏览器。

语法
--
```

dataTransfer.files;
```

### 返回值

拖动操作中的文件`列表`，操作中每个文件的一个列表项。如果拖动操作没有文件，此列表为空。

举个例子
----

这个接口有两个实例：

* 只针对 Firfox: http://jsfiddle.net/9C2EF/
* 所有浏览器：https://jsbin.com/hiqasek/
规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-files-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DataTransfer()
==============

通过构造函数 **`DataTransfer`** 创建一个新的 `DataTransfer` 对象。注意，单独创建该对象没有意义，且 Internet Explorer 中 `DataTransfer` 不是一个构造函数。

语法
--
```

var dataTrans = new DataTransfer()
```

### 参数

无

### 返回值

一个空的 `DataTransfer` 对象。

规范
--

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

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

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

**`DataTransfer.dropEffect`** 属性控制在拖放操作中给用户的反馈（通常是视觉上的）。它会影响在拖拽过程中光标的手势。例如，当用户 hover 在一个放置目标元素上，浏览器的光标可能会预示了将会发生什么操作。

当 `DataTransfer` 被创建时，`dropEffect` 被设置为一个字符串。读这个值时会返回它的当前值。设置这个值时，如果这个新的值是下面列出的值中的一个，这个属性的值就会被设置为这个新的值，其他的值都会被忽略。

对于 `dragenter` 和 `dragover` 事件，`dropEffect` 会根据用户的请求的行为进行初始化。具体如何初始化和浏览器平台有关，但是通常来讲，用户可以通过按住修改键，比如 alt 键来修改想要的行为。当我们期望得到一个指定的行为时而不是用户的请求行为时，可以通过 `dragenter` 和 `dragover` 事件处理修改 `dropEffect` 的值。

对于 `drop` 和 `dragend` 事件，`dropEffect` 会被设置为想要得到的值，即最后一次 `dragenter` 或 `dragover` 事件后 `dropEffect` 的值。例如，在一个 `dragend` 事件中，如果期望得到的 dropEffect 是“move”，那么被拖拽的数据会从源中移除。

语法
--


```js
dataTransfer.dropEffect;
```

### 值

一个代表拖动操作效果的 `DOMString`，可能的值有：

`copy`

在新位置生成源项的副本

`move`

将项目移动到新位置

`link`

在新位置建立源项目的链接

`none`

项目可能禁止拖放（译者注：还与 effectAllowed 设置的值相关）

将任何其他值赋给 `dropEffect` 都没有效果，这种情况下会保留旧值。

示例
--

这个例子演示了 `dropEffect` 和 `effectAllowed` 属性的用法

### HTML


```html
<div>
  <p id="source" ondragstart="dragstart\_handler(event);" draggable="true">
    Select this element, drag it to the Drop Zone and then release the selection
    to move the element.
  </p>
</div>
<div
 id="target"
 ondrop="drop\_handler(event);"
 ondragover="dragover\_handler(event);">
  Drop Zone
</div>
```

### CSS


```css
div {
  margin: 0em;
  padding: 2em;
}

#source {
  color: blue;
  border: 1px solid black;
}

#target {
  border: 1px solid black;
}
```

### JavaScript


```js
function dragstart\_handler(ev) {
  console.log(
    "dragStart: dropEffect = " +
      ev.dataTransfer.dropEffect +
      " ; effectAllowed = " +
      ev.dataTransfer.effectAllowed,
  );

  // Add this element's id to the drag payload so the drop handler will
  // know which element to add to its tree
  ev.dataTransfer.setData("text", ev.target.id);
  ev.dataTransfer.effectAllowed = "move";
}

function drop\_handler(ev) {
  console.log(
    "drop: dropEffect = " +
      ev.dataTransfer.dropEffect +
      " ; effectAllowed = " +
      ev.dataTransfer.effectAllowed,
  );
  ev.preventDefault();

  // Get the id of the target and add the moved element to the target's DOM
  var data = ev.dataTransfer.getData("text");
  ev.target.appendChild(document.getElementById(data));
}

function dragover\_handler(ev) {
  console.log(
    "dragOver: dropEffect = " +
      ev.dataTransfer.dropEffect +
      " ; effectAllowed = " +
      ev.dataTransfer.effectAllowed,
  );
  ev.preventDefault();
  // Set the dropEffect to move
  ev.dataTransfer.dropEffect = "move";
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransfer-dropeffect-dev |

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

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

参见
--

* HTML 拖放 API
* 拖拽操作
* 推荐拖拽类型
* DataTransfer test - Paste or Drag
EyeDropper：open() 方法
====================

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

**`EyeDropper.open()`** 方法启动拾色器模式，返回一个 Promise，在用户选择颜色而退出拾色器模式后兑现。

语法
--


```js
open()
open(options)
```

### 参数

`options` 可选

一个用于传递 `AbortSignal` 信号的对象：

`signal`

一个 `AbortSignal` 对象。当调用 `AbortSignal` 的 `abort()` 方法时，拾色器模式将被中止。


### 返回值

一个 `Promise`，最终在用户从屏幕上选择一个像素颜色时解决。

该 Promise 会兑现一个带有以下属性的对象：

`sRGBHex`

代表所选颜色的字符串，采用十六进制 sRGB 格式（`#aabbcc`）。

### 异常

在 `Promise` 被拒绝（rejected）时，不会抛出异常，而是返回一个错误对象。Promise 在以下两种情况下被拒绝：

* 当用户通过按下 `Escape` 键来取消拾色器模式时。
* 当通过作为参数传递给 `open()` 方法的 `AbortController` 来中止拾色器模式时。
规范
--

| Specification |
| --- |
| EyeDropper API # dom-eyedropper-open |

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

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

参见
--

* 它属于 `EyeDropper` 接口。
EyeDropper：EyeDropper() 构造函数
============================

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

**`EyeDropper()`** 构造函数返回一个新的 `EyeDropper` 对象。

语法
--


```js
new EyeDropper()
```

### 参数

无。

规范
--

| Specification |
| --- |
| EyeDropper API # eyedropper-interface |

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

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

参见
--

* 它属于 `EyeDropper` 接口。
HTMLElement：dragstart 事件
========================

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

语法
--

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


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

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

事件类型
----

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

Event

UIEvent

MouseEvent

DragEvent事件属性
----

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

`DragEvent.dataTransfer` 只读 

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

示例
--

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

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

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

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

#### HTML


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


#### CSS


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

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

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

.dragging {
  opacity: 0.5;
}
```


#### JavaScript


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

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


#### 结果

规范
--

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

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

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

参见
--

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

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

语法
--
```

parentObj = element.offsetParent;
```


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

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

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

规范
--

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

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
HTML 元素：change 事件
=================

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

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

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

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

语法
--

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


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

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

事件类型
----

通用 `Event`。

示例
--

### <select> 元素

#### HTML


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

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


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

select {
  grid-area: select;
}

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


#### JavaScript


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

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


#### 结果

### 文本输入元素

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

#### HTML


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


#### JavaScript


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

input.addEventListener("change", updateValue);

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


#### 结果

规范
--

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

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

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

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