---
title: DataTransfer
slug: Web/API/DataTransfer
tags:
  - API
  - DataTransfer
  - HTML Drag and Drop API
  - NeedsMarkupWork
  - Web Development
  - 参考
  - 复制粘贴
  - 拖放
  - 接口
translation_of: Web/API/DataTransfer
---
<div>{{APIRef("HTML Drag and Drop API")}}</div>

<p><code>DataTransfer</code> 对象用于保存拖动并放下（drag and drop）过程中的数据。它可以保存一项或多项数据，这些数据项可以是一种或者多种数据类型。关于拖放的更多信息，请参见 <a class="internal" href="/En/DragDrop/Drag_and_Drop" title="En/DragDrop/Drag and Drop">Drag and Drop</a>.</p>

<p>这个对象可以从所有拖动事件 {{domxref("DragEvent","drag events")}} 的 {{domxref("DragEvent.dataTransfer","dataTransfer")}} 属性上获取。</p>

<h2 id="构造函数">构造函数</h2>

<p>{{domxref("DataTransfer.DataTransfer","DataTransfer()")}}</p>

<dl>
 <dd>生成并且返回一个新的 <code>DataTransfer</code> 对象。</dd>
</dl>

<h2 id="属性">属性</h2>

<h3 id="标准属性">标准属性</h3>

<dl>
 <dt>{{domxref("DataTransfer.dropEffect")}}</dt>
 <dd>获取当前选定的拖放操作类型或者设置的为一个新的类型。值必须为  <code>none</code>, <code>copy</code>, <code>link</code> 或 <code>move</code>。</dd>
 <dt>{{domxref("DataTransfer.effectAllowed")}}</dt>
 <dd>提供所有可用的操作类型。必须是  <code>none</code>, <code>copy</code>, <code>copyLink</code>, <code>copyMove</code>, <code>link</code>, <code>linkMove</code>, <code>move</code>, <code>all</code> or <code>uninitialized</code> 之一。</dd>
 <dt>{{domxref("DataTransfer.files")}}</dt>
 <dd>包含数据传输中可用的所有本地文件的列表。如果拖动操作不涉及拖动文件，则此属性为空列表。</dd>
 <dt>{{domxref("DataTransfer.items")}} {{readonlyInline}}</dt>
 <dd>提供一个包含所有拖动数据列表的 {{domxref("DataTransferItemList")}} 对象。</dd>
 <dt>{{domxref("DataTransfer.types")}} {{readonlyInline}}</dt>
 <dd>一个提供 {{event("dragstart")}} 事件中设置的格式的 {{domxref("DOMString","strings")}} 数组。</dd>
</dl>

<h3 id="Gecko_属性">Gecko 属性</h3>

<p>{{SeeCompatTable}}</p>

<div class="note"><strong>注意：</strong>本节中的所有属性为 Gecko 特有。</div>

<dl>
 <dt>{{domxref("DataTransfer.mozCursor")}}</dt>
 <dd>给出拖动光标的状态。这主要用于在拖动期间控制光标。</dd>
 <dt>{{domxref("DataTransfer.mozSourceNode")}} {{readonlyInline}}</dt>
 <dd>按下鼠标按钮按下启动拖动操作时鼠标光标所在的 {{ domxref("Node") }} 。对于外部拖动或调用方无法访问节点，此值为  <code>null</code> 。</dd>
 <dt>{{domxref("DataTransfer.mozUserCancelled")}} {{readonlyInline}}</dt>
 <dd>此属性仅适用于 <code>dragend</code> 事件，如果通过用户按下 escape 取消拖动操作，则为 <code>true</code> 。在所有其他情况下，这将为 <code>false</code> ，包括由于其他原因（如，放置在无效位置）导致的拖动失败。</dd>
 <dt>
 <h3 id="不推荐的属性">不推荐的属性</h3>
 </dt>
 <dt>{{domxref("DataTransfer.mozItemCount")}} {{readonlyInline}} {{deprecated_inline}}</dt>
 <dd>提供拖动操作中的项目数。在Firefox71中删除。</dd>
</dl>

<h2 id="Methods" name="Methods">方法</h2>

<h3 id="标准方法">标准方法</h3>

<dl>
 <dt>{{domxref("DataTransfer.clearData()")}}</dt>
 <dd>删除与给定类型关联的数据。类型参数是可选的。如果类型为空或未指定，则删除与所有类型关联的数据。如果指定类型的数据不存在，或者 data transfer 中不包含任何数据，则该方法不会产生任何效果。</dd>
 <dt>{{domxref("DataTransfer.getData()")}}</dt>
 <dd>检索给定类型的数据，如果该类型的数据不存在或 data transfer不包含数据，则返回空字符串。</dd>
 <dt>{{domxref("DataTransfer.setData()")}}</dt>
 <dd>设置给定类型的数据。如果该类型的数据不存在，则将其添加到末尾，以便类型列表中的最后一项将是新的格式。如果该类型的数据已经存在，则在相同位置替换现有数据。</dd>
 <dt>{{domxref("DataTransfer.setDragImage()")}}</dt>
 <dd>用于设置自定义的拖动图像。</dd>
</dl>

<h3 id="Gecko_方法">Gecko 方法</h3>

<p>{{Non-standard_header()}}</p>

<div class="blockIndicator note">
<p><strong>注意：</strong>本节所有方法为 Gecko 专有。</p>
</div>

<dl>
 <dt>{{domxref("DataTransfer.addElement()")}}</dt>
 <dd>Sets the drag source to the given element.</dd>
</dl>

<h3 id="不推荐的方法">不推荐的方法</h3>

<dl>
 <dt>{{domxref("DataTransfer.mozClearDataAt()")}} {{deprecated_inline}}</dt>
 <dd>Removes the data associated with the given format for an item at the specified index. The index is in the range from zero to the number of items minus one. Removed in Firefox 71.</dd>
 <dt>{{domxref("DataTransfer.mozGetDataAt()")}} {{deprecated_inline}}</dt>
 <dd>Retrieves the data associated with the given format for an item at the specified index, or null if it does not exist. The index should be in the range from zero to the number of items minus one. Removed in Firefox 71.</dd>
 <dt>{{domxref("DataTransfer.mozSetDataAt()")}} {{deprecated_inline}}</dt>
 <dd>A data transfer may store multiple items, each at a given zero-based index. <code>mozSetDataAt()</code> may only be called with an index argument less than <code>mozItemCount</code> in which case an existing item is modified, or equal to <code>mozItemCount</code> in which case a new item is added, and the <code>mozItemCount</code> is incremented by one. Removed in Firefox 71.</dd>
 <dt>{{domxref("DataTransfer.mozTypesAt()")}} {{deprecated_inline}}</dt>
 <dd>Holds a list of the format types of the data that is stored for an item at the specified index. If the index is not in the range from 0 to the number of items minus one, an empty string list is returned. Removed in Firefox 71.</dd>
</dl>

<h2 id="示例">示例</h2>

<p>本文档中的每个方法和属性都有自己的参考页面，每个参考页面中都直接包含了接口的示例或给出了示例的链接。</p>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('HTML WHATWG', 'interaction.html#datatransfer','DataTransfer')}}</td>
   <td>{{Spec2('HTML WHATWG')}}</td>
   <td><code>mozCursor</code>, <code>mozItemCount</code>, <code>mozSourceNode</code>, <code>mozUserCancelled</code>, <code>addElement()</code>, <code>mozClearDataAt()</code>, <code>mozGetDataAt()</code>, <code>mozSetDataAt()</code> and <code>mozTypesAt</code> are Gecko specific.</td>
  </tr>
  <tr>
   <td>{{SpecName('HTML5.1', 'editing.html#the-datatransfer-interface','DataTransfer')}}</td>
   <td>{{Spec2('HTML5.1')}}</td>
   <td>Not included in W3C HTML5 {{Spec2('HTML5 W3C')}}</td>
  </tr>
  <tr>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{Compat("api.DataTransfer")}}</p>

<h2 id="See_also" name="See_also">参见</h2>

<ul>
 <li><a class="internal" href="/zh-CN/docs/Web/API/HTML_Drag_and_Drop_API">拖与放</a></li>
 <li><a href="HTML_Drag_and_Drop_API/Drag_operations">拖动操作</a></li>
 <li><a href="HTML_Drag_and_Drop_API/Recommended_drag_types">推荐拖动类型</a></li>
 <li><a href="/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Multiple_items">拖动多项</a></li>
 <li><a href="https://codepen.io/tech_query/pen/MqGgap">DataTransfer 测试 - 粘贴、拖放</a></li>
</ul>