HTML 中的拖放

Adobe AIR 1.0 和更高版本

若要将数据拖入和拖出基于 HTML 的应用程序(或者拖入和拖出 HTMLLoader 中显示的 HTML),则可以使用 HTML 拖放事件。使用 HTML 拖放 API,可以拖到和拖出 HTML 内容中的 DOM 元素。

注: 还可以通过侦听包含 HTML 内容的 HTMLLoader 对象上发生的事件,来使用 AIR NativeDragEvent 和 NativeDragManager API。但是,HTML API 更好地与 HTML DOM 集成到了一起,因而您可以控制默认行为。

默认的拖放行为

HTML 环境为涉及文本、图像和 URL 的拖放手势提供了默认行为。利用默认行为,始终都可以将这些类型的数据拖出元素。但是,只能将文本拖入元素,并且只能拖到页面的可编辑区域内的元素。在页面的可编辑区域之间或可编辑区域内部拖动文本时,默认行为会执行移动动作。从不可编辑的区域或应用程序外部向可编辑区域拖动文本时,默认行为则会执行复制动作。

可以通过自行处理拖放事件来覆盖默认行为。若要取消默认行为,必须调用为拖放事件调度的对象的 preventDefault() 方法。这样,您就可以根据需要将数据插入放置目标以及从拖动源中删除数据,以便执行所选的动作。

默认情况下,用户可以选择和拖动任何文本,并可以拖动图像和链接。可以使用 WebKit CSS 属性 -webkit-user-select 来控制任何 HTML 元素的选择方式。例如,如果将 -webkit-user-select 设置为 none ,则元素内容是不可选择的,因而也无法拖动。还可以使用 -webkit-user-drag CSS 属性控制元素作为一个整体是否可以拖动。不过,元素的内容则单独处理。用户仍可以拖动文本的选定部分。有关详细信息,请参阅 AIR 中的 CSS

HTML 中的拖放事件

从中发起拖动操作的启动器元素调度的事件有:

事件

说明

dragstart

在用户启动拖动手势时调度。如有必要,此事件的处理函数可以通过调用事件对象的 preventDefault() 方法来阻止拖动。若要控制是否可以复制、链接或移动所拖动的数据,请设置 effectAllowed 属性。所选的文本、图像和链接由默认行为放置到剪贴板上,但您可以使用事件对象的 dataTransfer 属性为拖动手势设置其他数据。

drag

在执行拖动手势期间持续调度

dragend

在用户释放鼠标按键终止拖动手势时调度。

由拖动目标调度的事件有:

事件

说明

dragover

当拖动手势仍然在元素边界内时持续调度。此事件的处理函数应设置 dataTransfer.dropEffect 属性,以指示在用户释放鼠标时放置操作是否会导致复制、移动或链接动作。

dragenter

在拖动手势进入元素的边界内时调度。

如果在 dragenter 事件处理函数中更改 dataTransfer 对象的任何属性,则这些更改将很快被下一个 dragover 事件覆盖。另一方面,在 dragenter 与第一个 dragover 事件之间有一个短暂的延迟,如果设置了不同的属性,此延迟可导致光标闪烁。在很多情况下,都可以对这两个事件使用相同的事件处理函数。

dragleave

在拖动手势离开元素边界时调度。

drop

在用户将数据放到元素上时调度。只能在此事件的处理函数内访问所拖动的数据。

为响应这些事件而调度的事件对象与鼠标事件类似。可以使用诸如 ( clientX , clientY ) 和 ( screenX , screenY ) 等鼠标事件属性来确定鼠标位置。

拖动事件对象最重要的属性是 dataTransfer ,此属性包含被拖动的数据。 dataTransfer 对象本身具有以下属性和方法:

属性或方法

说明

effectAllowed

拖动源允许的效果。通常情况下,dragstart 事件的处理函数设置此值。请参阅 HTML 中的拖动效果

dropEffect

由目标或用户选择的效果。如果在 dragover dragenter 事件处理函数中设置 dropEffect ,则 AIR 会更新鼠标光标,以指示在用户释放鼠标时出现的效果。如果允许的效果中没有一种效果与 dropEffect 设置匹配,则不允许放置,并显示 不可用 光标。如果尚未设置 dropEffect 来响应最新的 dragover dragenter 事件,则用户可以使用标准的操作系统功能键从允许的效果中进行选择。

最终的效果由为 dragend 调度的对象的 dropEffect 属性报告。如果用户通过在符合条件的目标外部释放鼠标放弃放置操作,则 dropEffect 将设置为 none

类型

一个数组,其中包含了 dataTransfer 对象中存在的每种数据格式的 MIME 类型字符串。

getData(mimeType)

mimeType 参数指定的格式获取数据。

只能为响应 drop 事件调用 getData() 方法。

setData(mimeType)

以 mimeType 参数指定的格式向 dataTransfer 添加数据。可以通过对每种 MIME 类型调用 setData() ,以多种格式添加数据。将清除由默认拖动行为放入 dataTransfer 对象的所有数据。

只能为响应 dragstart 事件调用 setData() 方法。

clearData(mimeType)

清除采用 mimeType 参数指定的格式的所有数据。

setDragImage(image, offsetX, offsetY)

设置自定义拖动图像。只能为响应 dragstart 事件,且只有当拖动整个 HTML 元素(通过将 -webkit-user-drag CSS 样式设置为 element )时,才可以调用 setDragImage() 方法。 image 参数可以是 JavaScript 元素或 Image 对象。

用于 HTML 拖放的 MIME 类型

与 HTML 拖放事件的 dataTransfer 对象一起使用的 MIME 类型包括:

数据格式

MIME 类型

文本

"text/plain"

HTML

"text/html"

URL

"text/uri-list"

位图

"image/x-vnd.adobe.air.bitmap"

文件列表

"application/x-vnd.adobe.air.file-list"

还可以使用其他 MIME 字符串,包括应用程序定义的字符串。但是,其他应用程序可能无法识别或使用所传输的数据。以所需格式向 dataTransfer 对象添加数据的工作由您负责完成。

重要说明: 只有在应用程序沙箱中运行的代码才能访问放置的文件。如果试图在非应用程序沙箱内读取或设置 File 对象的任何属性,则会产生安全错误。有关详细信息,请参阅 在非应用程序 HTML 沙箱中处理文件放置

HTML 中的拖动效果

拖动手势的启动器可以通过在 dragstart 事件的处理函数中设置 dataTransfer.effectAllowed 属性,来限制允许的拖动效果。可以使用以下字符串值:

字符串值

说明

"none"

不允许任何拖动操作。

"copy"

将数据复制到目标位置,并保留原始数据的位置不变。

"link"

使用指回原始数据的链接与放置目标共享数据。

"move"

将数据复制到目标,并将其从原始位置删除。

"copyLink"

可以复制数据,也可链接数据。

"copyMove"

可以复制数据,也可移动数据。

"linkMove"

可以链接数据,也可移动数据。

"all"

可以复制数据、移动数据,也可链接数据。当您阻止默认行为时, All 是默认效果。

拖动手势的目标可以设置 dataTransfer.dropEffect 属性,以指示在用户完成放置后采取的动作。如果放置效果是允许的动作之一,则系统将显示相应的复制、移动或链接光标。如果不是,则系统将显示 不可用 光标。如果目标未设置放置效果,则用户可以使用功能键从允许的动作中进行选择。

同时在 dragover dragenter 事件的处理函数中设置 dropEffect 值:

function doDragStart(event) { 
    event.dataTransfer.setData("text/plain","Text to drag"); 
    event.dataTransfer.effectAllowed = "copyMove"; 
} 
 
function doDragOver(event) { 
    event.dataTransfer.dropEffect = "copy"; 
} 
 
function doDragEnter(event) { 
    event.dataTransfer.dropEffect = "copy"; 
}
注: 尽管您始终都应在 dragenter 的处理函数中设置 dropEffect 属性,但要注意,下一个 dragover 事件会将此属性重置为其默认值。设置 dropEffect 以响应这两个事件。