MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

DataTransfer

这篇翻译不完整。请帮忙从英语翻译这篇文章

  在进行拖放操作时,DataTransfer 对象用来保存被拖动的数据。它可以保存一项或多项数据、一种或者多种数据类型。关于拖放的更多信息,请参见 Drag and Drop.

这个对象在所有的拖动事件属性dataTransfer  都是可用的,但是不能单独创建。

属性概述

属性(Properties) 类型(Type)
dropEffect String
effectAllowed String
files FileList
mozCursor String
mozItemCount unsigned long
mozSourceNode Node
mozUserCancelled Boolean
types DOMStringList

方法概述

void addElement(in Element element)
void clearData([in String type])
String getData(in String type)
void setData(in String type, in String data)
void setDragImage(in nsIDOMElement image, in long x, in long y)
void mozClearDataAt([in String type, in unsigned long index])
nsIVariant mozGetDataAt(in String type, in unsigned long index)
void mozSetDataAt(in String type, in nsIVariant data, in unsigned long index)
StringList mozTypesAt([in unsigned long index])

属性

dropEffect

设置实际的放置效果,它应该始终设置成 effectAllowed  的可能值之一 。

对于 dragenter 和 dragover 事件,dropEffect 将基于用户要求的动作被初始化设置。这如何确定是平台特定的但用户通常可以修改键值来调整为理想动作。在 dragenter 和 dragover 事件的事件处理程序中,如果这个效果不是用户要求的动作,那就应该修改dropEffect 的值。

对于 dragstart, drag和dragleave事件,dropEffect会被初始化为 “none”。任何有效的值都可以用来设置 dropEffect,这是这些设置的值不会做任何事情[译者注:也就是说任何有效值都不会报错,但是在这些事件中设置没有任何效果]。

对于drop和dragend事件,dropEffect将被初始化成期望的动作,这个动作的值是最近的执行dragenter或者dragover事件后的dropEffect的值。

可能的值:

  • copy: 复制到新的位置
  • move: 移动到新的位置.
  • link: 建立一个源位置到新位置的链接.
  • none: 禁止放置(禁止任何操作).

分配任何其他值时不会有任何影响并且保留旧值

effectAllowed

用来指定拖动时被允许的效果。你可以在dragstart事件中设置拖动源数据时期望的动作效果,同时在dragenter和dragover事件中为目标设置期望的效果[译者注:effectAllowed设置允许的效果,在dragenter和dragover中通过设置上面的那个属性dropEffect来确定具体的动作效果]。这些值在其他的事件中没有任何作用。

可能的值:

  • copy: 复制到新的位置.
  • move:移动到新的位置 .
  • link:建立一个源位置到新位置的链接.
  • copyLink: 允许复制或者链接.
  • copyMove: 允许复制或者移动.
  • linkMove: 允许链接或者移动.
  • all: 允许所有的操作.
  • none: 禁止所有操作.
  • uninitialized: 缺省值(默认值), 相当于 all.

分配任何其他值时不会有任何影响并且保留旧值

files

包含一个在数据传输上所有可用的本地文件列表。如果拖动操作不涉及拖动文件,此属性是一个空列表。此属性访问指定的FileList 中无效的索引将返回未定义(undefined)。

实例

此实例转存被拖动到浏览器窗口中的文件列表。

找不到文件: filednd.html

请到这个页面中查看效果:  http://jsfiddle.net/9C2EF/

types

保存一个被存储数据的类型列表作为第一项,顺序与被添加数据的顺序一致。如果没有添加数据将返回一个空列表。

Gecko 1.9.2 note
The string "Files" is included in this list if files are included in the drag.

mozCursor

Requires Gecko 1.9.1(Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

拖动光标状态。这主要用来控制光标在拖动过程中的显示。

Note: 这个方法目前只能在Windows上实现

可能的值

auto
使用系统默认行为。
default
使用默认的Gecko 行为,是要在拖动操作期间将光标设置为一个箭头。
Note: 如果您指定"默认"之外的任何值,则假定"auto"。

mozItemCount

正被拖动的项的数目。

Note: 这个属性是Gecko指定的。

mozSourceNode

The Node over which the mouse cursor was located when the button was pressed to initiate the drag operation. This value is null for external drags or if the caller can't access the node.

Note: 这个属性是Gecko指定的。

mozUserCancelled

This property applies only to the dragend event, and is true if the user canceled the drag operation by pressing escape. It will be false in all other cases, including if the drag failed for any other reason, for instance due to a drop over an invalid location. This property is not currently implemented on Linux.

Note: 这个属性是Gecko指定的。

方法

addElement()

设置拖动源。通常你不需要改变这项,如果修改这项将会影响拖动的哪个节点和dragend事件的触发。默认目标是被拖动的节点。

 obj.addElement();
参数
element
要添加的元素.

clearData()

删除与给定类型关联的数据。类型参数是可选的。如果类型为空或未指定,将删除所有类型相关联的数据。如果不存在指定类型的数据,或数据传输不包含任何数据,此方法将没有任何效果。

 obj.clearData(type);
参数
type
要删除的数据类型.

getData()

检索(取得)给定类型的数据,如果给定类型的数据不存在或者数据转存(data transfer)没有包涵数据,方法将返回一个空字符串。

如果你试图获取从不同域中拖动的数据将发生一个安全性错误或者无法访问[译者注:这里翻译不是很确定,如不清楚请看英文原文],这个数据将仅仅在放置动作发生时在drop时间中是可用的。

 obj.getData(type);
参数
type
要检索的数据类型。.

setData()

为一个给定的类型设置数据。如果该数据类型不存在,它将添加到的末尾,这样类型列表中的最后一个项目将是新的格式。如果已经存在的数据类型,替换相同的位置的现有数据。就是,当更换相同类型的数据时,不会更改类型列表的顺序。

 obj.setData(type,data);
参数
type
要添加的数据类型.
data
要添加的数据.

setDragImage()

自定义一个期望的拖动时的图片。大多数情况下,这项不用设置,因为被拖动的节点被创建成默认图片。

如果该节点是 HTML img 元素、 HTML 画布元素或一个 XUL 图像元素,则会使用图像数据[译者注:拖动时的效果将使用这里的图片]。否则为图像应该是可见的节点,根据这个可见的节点创建拖动图像。如果image是null,任何自定义拖动图像都会被清除,并且使用默认值代替。

坐标指定图像相对于鼠标光标位置的偏移量。例如,为使鼠标在图像中心,可以使用图像宽度和高度的值的一半。

 obj.setDragImage(imgElement,offsetX,offsetY);
参数
image
要用作拖动反馈图像元素
x
图像内的水平偏移量.
y
图像内的垂直偏移量.

mozClearDataAt()

删除指定索引处与给定格式相关的数据项。索引值应该是在:0 到总项数减 1[译者注:注意索引是从0开始的,所以最后一项应该是: 总项数-1]。

如果数据项的最后一种格式类型被删除,整个数据项都会被删除,同时从 mozItemCount  减 1。

如果各事列表是空的,所有类型相关的数据都会被删除。如果格式没有发现,这个方法没有任何影响。

Note: 这个方法是Gecko指定的
 void mozClearDataAt(
   [optional] in String type,
   in unsigned long index
 );
参数
type
要删除数据的数据类型.
index
要删除的数据的索引.

mozGetDataAt()

取得指定索引处的与给定的格式相关联的数据项,如果不存在返回null。索引值应该是在:0 到总项数减1 [译者注:注意索引是从0开始的,所以最后一项应该是: 总项数-1]。

Note: 这个方法是Gecko指定的
 nsIVariant mozGetDataAt(
   [optional] in String type,
   in unsigned long index
 );
参数
type
要检索的数据类型.
index
要检索的数据的索引.

mozSetDataAt()

一个数据转存(data transfer)可能存储 多条/多项 数据,每一项都从索引0开始。mozSetDataAt() 只可以被索引参数小于mozItemCount 的现有存在项调用,在这种情况下,已存在的项会被修改;或者索引参数等于mozItemCount ,这种情况下,添加一条新项,同时mozItemCount 加一。      

应按优先顺序排列添加数据, 最先添加指定格式最多的数据,最后添加指定格式最少的数据。如果给定格式的数据已经存在,将会替换相同位置上的旧数据。

数据应该是任何一个字符串,布尔值或者数字类型(这将被转换成一个字符串)或者一个 nsISupports

Note: 这个方法是Gecko指定的
 void mozSetDataAt(
   [optional] in String type,
   in nsIVariant data,
   in unsigned long index
 );
参数
type
要添加的数据类型.
data
要添加的数据.
index
要添加的数据的索引.

mozTypesAt()

保存一个指定索引处被存储的数据格式类型的列表。如果索引不是在范围: 0 到总项数减1 [译者注:注意索引是从0开始的,所以最后一项应该是: 总项数-1],则返回空字符串列表。

Note: 这个方法是Gecko指定的
 nsIVariant mozTypesAt(
   in unsigned long index
 );
参数
index
要取得数据类型的相应的数据索引

请参见

Drag and Drop

文档标签和贡献者

 此页面的贡献者: yuwanfeng, wangxb
 最后编辑者: yuwanfeng,