支援拖入手勢

Adobe AIR 1.0 以及更新的版本

為了支援拖入手勢,您的應用程式 (或者,大體上是指應用程式的視覺化組件) 必須回應 nativeDragEnter nativeDragOver 事件。

一般放下作業的步驟

放下作業通常會發生下列一連串事件:

  1. 使用者將剪貼簿物件拖曳到某個組件上方。

  2. 該組件傳送 nativeDragEnter 事件。

  3. nativeDragEnter 事件處理常式檢查事件物件,據以判定適用的資料格式和允許的動作。如果組件能夠處置放下動作,便會呼叫 NativeDragManager.acceptDragDrop()

  4. NativeDragManager 將滑鼠游標變更為可放下物件的形狀。

  5. 使用者在組件上方放開物件。

  6. 接收端組件傳送 nativeDragDrop 事件。

  7. 接收端組件從事件物件內的 Clipboard 物件中讀取其所需格式的資料。

  8. 如果拖曳手勢源自 AIR 應用程式內部,初始的互動式物件即傳送 nativeDragComplete 事件。如果手勢源自 AIR 外部,就不會傳送任何回應。

傳達拖入手勢

當使用者將剪貼簿項目拖曳至視覺化組件的邊界內時,該組件會傳送 nativeDragEnter nativeDragOver 事件。這些事件的處理常式則可檢查事件物件的 clipboard allowedActions 屬性,以判斷組件能否接受剪貼簿項目。為了傳達訊號表示組件能夠接受放下動作,事件處理常式必須呼叫 NativeDragManager.acceptDragDrop() 方法,同時傳遞接收端組件的參考。若有多個已登錄的事件偵聽程式呼叫了 acceptDragDrop() 方法,則以清單中所列的最後一個處理常式為最優先。只要滑鼠還沒移出接收端物件的邊界,因而未觸發 nativeDragExit 事件, acceptDragDrop() 呼叫就仍然有效。

如果傳遞給 doDrag() allowedActions 參數允許一種以上的動作,使用者可以藉由按住輔助按鍵,指定想要執行哪一種允許的動作。拖曳管理員就會變更游標影像,告訴使用者一旦完成放下動作時將發生何種動作。意圖執行的動作是由 NativeDragEvent 物件的 dropAction 屬性所回報。拖曳手勢的動作設定僅為提供建議。參與傳輸的組件必須實作適當的行為。例如,為了完成移動動作,拖曳初始程式可能會移除拖曳的項目,而放下目標則加入該項目。

拖曳目標可藉由設定 NativeDragManager 類別的 dropAction 屬性,將放下動作限定為三種可能的動作之其中一種。如果使用者利用鍵盤試圖選擇另一種動作,NativeDragManager 便會顯示「不適用」游標形狀。請同時在 nativeDragEnter nativeDragOver 事件的處理常式中設定 dropAction 屬性。

下列範例說明如何實作 nativeDragEnter nativeDragOver 事件的事件處理常式。唯有當拖曳的剪貼簿物件包含文字格式資料時,此處理常式才接受拖入手勢。

import flash.desktop.NativeDragManager; 
import flash.events.NativeDragEvent; 
 
public function onDragIn(event:NativeDragEvent):void{ 
    NativeDragManager.dropAction = NativeDragActions.MOVE; 
    if(event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){ 
        NativeDragManager.acceptDragDrop(this); //'this' is the receiving component 
    } 
}

完成放下動作

當使用者在已接受手勢的互動式物件上放下拖曳的項目時,該互動式物件便會傳送 nativeDragDrop 事件。此事件的處理常式可以從事件物件的 clipboard 屬性擷取資料。

如果剪貼簿包含應用程式定義的格式,則拖曳管理員將傳回物件的參考還是已序列化的版本,取決於傳遞給 Clipboard 物件 getData() 方法的 transferMode 參數。

下列範例說明如何實作 nativeDragDrop 事件的事件處理常式:

import flash.desktop.Clipboard; 
import flash.events.NativeDragEvent; 
 
public function onDrop(event:NativeDragEvent):void { 
    if (event.clipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)) { 
    var text:String = 
        String(event.clipboard.getData(ClipboardFormats.TEXT_FORMAT,  
                                    ClipboardTransferMode.ORIGINAL_PREFERRED)); 
}

一旦結束事件處理常式,Clipboard 物件將不再有效。任何嘗試存取該物件或其資料的行為都會產生錯誤。

更新組件的視覺外觀

組件可以根據 NativeDragEvent 事件來更新視覺外觀。下表說明一般組件基於回應不同的事件所做的變更類型:

事件

說明

nativeDragStart

初始的互動式物件可以利用 nativeDragStart 事件,提供視覺回應指出拖曳手勢係源自該互動式物件。

nativeDragUpdate

初始的互動式物件可以利用 nativeDragUpdate 事件,在手勢期間更新其狀態。(Linux 版 AIR 沒有此事件。)

nativeDragEnter

可能的接收端互動式物件可以利用此事件取得焦點,或以視覺化方式指出其本身能否接受放下動作。

nativeDragOver

可能的接收端互動式物件可以利用此事件,回應滑鼠在該互動式物件內部移動的狀況。例如,指出滑鼠已進入街道地圖畫面之類複雜組件的「熱點」感應區。

nativeDragExit

可能的接收端互動式物件可以利用此事件,在拖曳手勢移出其邊界時還原狀態。

nativeDragComplete

初始的互動式物件可以利用此事件,更新其相關聯的資料模型。例如,從清單中移除項目,同時還原其視覺狀態。

在拖入手勢期間追蹤滑鼠位置

當拖曳手勢停留在某個組件上方時,該組件會傳送 nativeDragOver 事件。這些事件每隔幾毫秒將傳送一次,而且也會隨著滑鼠移動而傳送。 nativeDragOver 事件物件可以用來判斷滑鼠目前在組件上的位置。若接收端組件相當複雜,但並非由子組件所構成,則存取滑鼠位置或許會有幫助。例如,假設您的應用程式顯示了含有街道地圖的點陣圖,而您想要反白標示使用者已將資訊拖曳至地圖上的哪些區域,即可利用 nativeDragOver 事件所回報的滑鼠座標,追蹤滑鼠在地圖內的位置。