DataTransfer

DataTransfer 对象用于保存拖动并放下(drag and drop)过程中的数据。它可以保存一项或多项数据,这些数据项可以是一种或者多种数据类型。关于拖放的更多信息,请参见 Drag and Drop.

这个对象可以从所有拖动事件 drag events 的 dataTransfer 属性上获取。

构造函数

DataTransfer()

生成并且返回一个新的 DataTransfer 对象。

属性

标准属性

DataTransfer.dropEffect
获取当前选定的拖放操作类型或者设置的为一个新的类型。值必须为  nonecopylink 或 move
DataTransfer.effectAllowed
提供所有可用的操作类型。必须是  nonecopycopyLinkcopyMovelinklinkMovemoveall or uninitialized 之一。
DataTransfer.files
包含数据传输中可用的所有本地文件的列表。如果拖动操作不涉及拖动文件,则此属性为空列表。
DataTransfer.items 只读
提供一个包含所有拖动数据列表的 DataTransferItemList 对象。
DataTransfer.types 只读
一个提供 dragstart (en-US) 事件中设置的格式的 strings 数组。

Gecko 属性

Experimental

这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

注意:本节中的所有属性为 Gecko 特有。
DataTransfer.mozCursor (en-US)
给出拖动光标的状态。这主要用于在拖动期间控制光标。
DataTransfer.mozSourceNode (en-US) 只读
按下鼠标按钮按下启动拖动操作时鼠标光标所在的 Node 。对于外部拖动或调用方无法访问节点,此值为  null 。
DataTransfer.mozUserCancelled (en-US) 只读
此属性仅适用于 dragend 事件,如果通过用户按下 escape 取消拖动操作,则为 true 。在所有其他情况下,这将为 false ,包括由于其他原因(如,放置在无效位置)导致的拖动失败。

不推荐的属性

DataTransfer.mozItemCount (en-US) 只读
提供拖动操作中的项目数。在Firefox71中删除。

方法

标准方法

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

Gecko 方法

非标准

该特性是非标准的,请尽量不要在生产环境中使用它!

注意:本节所有方法为 Gecko 专有。

DataTransfer.addElement() (en-US)
Sets the drag source to the given element.

不推荐的方法

DataTransfer.mozClearDataAt() (en-US)
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.
DataTransfer.mozGetDataAt() (en-US)
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.
DataTransfer.mozSetDataAt() (en-US)
A data transfer may store multiple items, each at a given zero-based index. mozSetDataAt() may only be called with an index argument less than mozItemCount in which case an existing item is modified, or equal to mozItemCount in which case a new item is added, and the mozItemCount is incremented by one. Removed in Firefox 71.
DataTransfer.mozTypesAt() (en-US)
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.

示例

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

规范

Specification Status Comment
HTML Living Standard
DataTransfer
Living Standard mozCursormozItemCountmozSourceNodemozUserCancelledaddElement()mozClearDataAt()mozGetDataAt()mozSetDataAt() and mozTypesAt are Gecko specific.
HTML 5.1
DataTransfer
Recommendation Not included in W3C HTML5 Recommendation

浏览器兼容性

BCD tables only load in the browser

参见