HTML 拖放 API

HTML 拖放介面能讓網頁應用程式於 Firefox 及其他瀏覽器中使用拖放功能。舉例來說,使用者可以利用此功能以滑鼠選擇可拖曳(draggable)元素,拖曳至一個可放置(droppable)元素上,並放開滑鼠按鍵來放置此元素。在拖曳操作時,一個半透明的可拖曳(draggable)元素會跟隨著滑鼠游標。

對於網站、擴充套件以及 XUL 應用程式來說,你可以自定義能成為可拖曳(draggable)的元素類型、可拖曳(draggable)元素產生的回鐀類型,以及可放置(droppable)的元素。

此文件為 HTML 拖放的概述,包含了相關介面的說明、在應用程式中加入拖放支援的基本步驟,以及相關介面使用簡介。

拖曳事件

HTML 拖放操作基於 DOM 事件模型並且使用繼承自滑鼠事件拖曳事件介面。一個典型的拖曳操作開始於使用者利用滑鼠選取了一個可拖曳(draggable)元素、移動滑鼠至一個可放置(droppable)元素並放開滑鼠按鍵。在操作的過程中,會觸發多種類型的事件,且一些事件類型可能會被觸發多次(如 dragdragover 事件類型)。

所有的拖曳事件類型都有相關的通用事件處理器(global event handler)。每一種拖曳事件類型及拖曳通用事件處理器屬性都有說明此事件的參考文件。以下的表格提供了每一種事件的簡要說明,以及參考文件的連結。

事件 事件處理器屬性 說明
drag ondrag 於一個元素或文字選取區塊被拖曳時觸發。
dragend ondragend 於拖曳操作結束時觸發(如放開滑鼠按鍵或按下鍵盤的 escap 鍵)。(請參考結束拖曳。)
dragenter ondragenter 於一個元素或文字選取區塊被拖曳移動進入一個有效的放置目標時觸發。(請參考指定拖曳目標。)
dragexit ondragexit 當一個元素不再是被選取中的拖曳元素時觸發。
dragleave ondragleave 於一個元素或文字選取區塊被拖曳移動離開一個有效的放置目標時觸發。
dragover ondragover 於一個元素或文字選取區塊被拖曳移動經過一個有效的放置目標時觸發(每幾百毫秒觸發一次)。
dragstart ondragstart 於使用者開始拖曳一個元素或文字選取區塊時觸發。(請參考開始拖曳。)
drop ondrop 於一個元素或文字選取區塊被放置至一個有效的放置目標時觸發。(請參考執行放置。)

Note that dragstart and dragend events are not fired when dragging a file into the browser from the OS.

介面

HTML 拖放介面有 DragEventDataTransferDataTransferItem 以及 DataTransferItemList

DragEvent 介面擁有一個建構式及一個屬性-dataTransfer 屬性為一個 DataTransfer 物件。DataTransfer 物件包含了拖曳事件的狀態,如正在進行的拖曳事件類型(例如 copymove)、拖曳中的資料(一或多個項目)以及每一個拖曳項目(drag item)的檔案類型(MIME type)。DataTransfer 物件也擁有加入及移除拖曳資料項目的方法。DragEventDataTransfer 介面應該是唯一須要加至應用程式中的 HTML 拖放功能。另外,請留意 Firefox 支援了一些 Gecko-specific 擴充DataTransfer 物件使用,雖然這些擴充只能在 Firefox 上作用。

Each DataTransfer object contains an items property which is a list of DataTransferItem objects. Each DataTransferItem object represents a single drag item and each item has a kind property which is the kind of data (either string or file) and a type property which is the data item's type (i.e. MIME type). The DataTransferItem object also has methods to get the drag item's data.

The DataTransferItemList object is a list of DataTransferItem objects. The list object has methods to: add a drag item to the list, remove a drag item from the list and clear the list of all drag items.

A key difference between the DataTransfer and DataTransferItem interfaces is that the former uses the synchronous getData() method to access a drag item's data, whereas the later uses the asynchronous getAsString() method to access a drag item's data.

Note: the DragEvent and DataTransfer interfaces are broadly interoperable with desktop browsers. However, the DataTransferItem and DataTransferItemList interfaces have limited browser support. See Interoperability for more information about drag and drop interoperability.

Gecko-specific interfaces

Mozilla and Firefox support some features not in the standard drag and drop model. These are convenience functions to facilitate dragging multiple items and dragging non-string data (such as files). For more information, see Dragging and Dropping Multiple Items. Additionally, see the DataTransfer reference page for all of the Gecko-specific properties and Gecko-specific methods.

基本用法

This section provides a summary of the basic steps to add drag and drop functionality to an application. Each section includes a description of the step, a short code example, and links to additional information.

Identify what is draggable

To make an element draggable requires adding the draggable attribute plus the ondragstart global event handler, as shown in the following code sample

function dragstart_handler(ev) {
 console.log("dragStart");
 // Add the target element's id to the data transfer object
 ev.dataTransfer.setData("text/plain", ev.target.id);
}

<body>
 <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">This element is draggable.</p>
</body>

See the draggable attribute reference and the Drag operations guide for more information.

Define the drag's data

The application is free to include any number of data items in a drag operation. Each data item is a string of a particular type, typically a MIME type such as text/html.

Each drag event has a dataTransfer property that holds the event's data. This property (which is a DataTransfer object) also has methods to manage drag data. The setData() method is used to add an item to the drag data, as shown in the following example.

function dragstart_handler(ev) {
  // Add the drag data
  ev.dataTransfer.setData("text/plain", ev.target.id);
  ev.dataTransfer.setData("text/html", "<p>Example paragraph</p>");
  ev.dataTransfer.setData("text/uri-list", "http://developer.mozilla.org");
}

For a list of common data types used for drag and drop (such as text, HTML, links, and files), see Recommended Drag Types and for more information about drag data, see Drag Data.

Define the drag image

By default, the browser supplies an image that appears beside the mouse pointer during a drag operation. However, an application may define a custom image by using the setDragImage() method as shown in the following example.

function dragstart_handler(ev) {
  // Create an image and then use it for the drag image.
  // NOTE: change "example.gif" to an existing image or the image 
  // will not be created and the default drag image will be used.
  var img = new Image(); 
  img.src = 'example.gif'; 
  ev.dataTransfer.setDragImage(img, 10, 10);
}

To learn more about drag feedback images, see Setting the Drag Feedback Image.

Define the drag effect

The dropEffect property is used to control the feedback (typically visual) the user is given during a drag and drop operation. It affects which cursor the browser displays while dragging. For example, when the user hovers over a target drop element, the browser's cursor may indicate the type of operation that will occur.

Three effects may be defined:

copy indicates that the data being dragged will be copied from its present location to the drop location.

move indicates that the data being dragged will be moved

link indicates that some form of relationship or connection will be created between the source and drop locations.

During the drag operation, the drag effects may be modified to indicate that certain effects are allowed at certain locations. If allowed, a drop may occur at that location.

The following example shows how to use this property.

function dragstart_handler(ev) {
  // Set the drag effect to copy
  ev.dataTransfer.dropEffect = "copy";
}

See Drag Effects for more details.

Define a drop zone

By default, the browser prevents anything from happening when dropping something onto the HTML element. To change that behavior so that an element becomes a drop zone or is droppable, the element must have both ondragover and ondrop event handler attributes. The following example shows how to use those attributes and includes basic event handlers for each attribute.

function dragover_handler(ev) {
 ev.preventDefault();
 // Set the dropEffect to move
 ev.dataTransfer.dropEffect = "move"
}
function drop_handler(ev) {
 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));
}
<body>
 <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Drop Zone</div>
</body>

Note each handler calls preventDefault() to prevent additional event processing for this prevent (such as touch events or pointer events).

For more information, see Specifying Drop Targets.

Handle the drop effect

The handler for the drop event is free to process the drag data in an application specific way. Typically, an application will use the getData() method to retrieve drag items and process them accordingly. Additionally, application semantics may differ depending on the value of the dropEffect and/or the state of modifier keys.

The following example shows a drop handler getting the source element's id from the drag data and then using the id to move the source element to the drop element.

function dragstart_handler(ev) {
 // Add the target element's id to the data transfer object
 ev.dataTransfer.setData("text/plain", ev.target.id);
 ev.dropEffect = "move";
}
function drop_handler(ev) {
 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));
}
<body>
 <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">This element is draggable.</p>
 <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Drop Zone</div>
</body>

For more information, see Performing a Drop.

Drag end

At the end of a drag operation, the dragend event fires at the source element - the element that was the target of the drag start. This event fires whether the drag completed or was canceled. The dragend event handler can check the value of the dropEffect property to determine if the drag operation succeeded or not.

For more information about handling the end of a drag operation, see Finishing a Drag.

Interoperability

As can be seen in the DataTransferItem interface's Browser Compatibility table, drag-and-drop interoperability is relatively broad among desktop browsers (except the DataTransferItem and DataTransferItemList interfaces have less support). This data also indicates drag and drop support among mobile browsers is very low.

Examples and demos

參見

文件標籤與貢獻者

 此頁面的貢獻者: jackblackevo, teoli, foxbrush
 最近更新: jackblackevo,