在 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 時，元素內容即為無法選取的狀態，因此也就無法拖曳。您也可以使用 CSS 屬性 -webkit-user-drag 來控制能否拖曳一整個元素。不過，元素的內容視為各自獨立。使用者仍可拖曳已選取的部分文字。如需詳細資訊，請參閱 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 。

types

包含 MIME 類型字串的陣列，各字串代表存在於 dataTransfer 物件中的每一種資料格式。

getData(mimeType)

取得由 mimeType 參數所指定之格式的資料。

只有在回應 drop 事件時，才能呼叫 getData() 方法。

setData(mimeType)

將 mimeType 參數所指定之格式的資料加入 dataTransfer 中。您可以呼叫 setData() 並指定每一種 MIME 類型，藉此加入多種格式的資料。經由預設的拖曳行為放入 dataTransfer 物件中的任何資料都將遭到清除。

只有在回應 dragstart 事件時，才能呼叫 setData() 方法。

clearData(mimeType)

清除由 mimeType 參數所指定之格式的任何資料。

setDragImage(image, offsetX, offsetY)

設定自訂的拖曳影像。唯有回應 dragstart 事件，以及因為 -webkit-user-drag CSS 樣式設定為 element 而拖曳整個 HTML 元素時，才會呼叫 setDragImage() 方法。 image 參數可以是 JavaScript Element 或 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 。