NativeDragManager  - AS3

套件	flash.desktop
類別	public class NativeDragManager
繼承	NativeDragManager Object

執行階段版本:

AIR 1.0

NativeDragManager 類別會協調拖放作業。使用原生拖放 API，您便可以允許使用者在 AIR 應用程式與原生作業系統之間、兩個應用程式之間或是單一應用程式內的組件之間拖曳資料。

可以傳輸的資料類型如下：

• 點陣圖
• 檔案
• 文字
• URL 字串
• 經過序列化的物件
• 物件參考 (只有在來源應用程式內才有效)

注意：所有 NativeDragManager 成員都必須是靜態成員。您不需要建立此類別的實體。

拖放作業是一種使用者介面手勢，它開始於使用者按一下可見的項目，並將它拖曳到其他地方。在拖曳手勢期間，顯示清單上的互動式物件會將原生拖曳事件當做移動手勢在 AIR 應用程式視窗之間傳送。這些事件的處理常式可以呼叫 NativeDragManager 類別的方法，指出是否可以將拖曳的項目放到物件上。接著，NativeDragManager 便會變更滑鼠指標來回應使用者。

AIR 描述檔支援：AIR for TV 裝置不支援此功能。此外，所有的行動裝置也都不支援。您可以使用 NativeDragManager.isSupported 屬性測試執行階段的支援狀況。如需有關跨多個描述檔之 API 支援的詳細資訊，請參閱 AIR 描述檔支援。

拖曳動作

拖放手勢通常用於三種類型的作業，稱為「動作」。由於這些動作的意義取決於應用程式內容，因此執行階段不會對這些動作強制執行任何行為指令。不過，適當地實作動作可以改善使用者的應用程式體驗。

可能的動作包括：

• 複製 — 產生資料的副本，讓原始資料維持不變 (在應用程式內拖曳物件時，請務必小心複製原始物件本身，而不是該物件的參考)。
• 移動 — 資料會從它的原始內容移到放置目標所定義的內容，例如將某個項目從一個清單移到另一個清單時。
• 連結 — 建立原始資料的參考或捷徑，將此項目留在它的原始內容中。

只要在開始拖曳作業的 NativeDragManager.doDrag() 呼叫中提供 allowedActions 參數，便可以針對拖曳手勢設定這些允許的動作。如果沒有提供 allowedActions 參數，表示允許所有的動作。可能的拖曳目標可以使用 NativeDragEvent 物件的 allowedActions 屬性來檢查所允許的動作，而且不應該接受只允許不相容動作的置放 (但是執行階段並不會強制這項處理)。

如果置放目標只會實作單一動作，此物件可以在 nativeDragEnter 和 nativeDragOver 事件的處理常式內設定 NativeDragManager 的 dropAction 屬性。在置放之前設定此屬性，不僅可允許拖曳管理員更新滑鼠指標以指出支援的動作，也可避免使用者使用輔助按鍵選擇不相容的動作。如果指定的動作不是屬於允許的動作，則不允許置放，即使目標會呼叫 acceptDrop() 方法亦然。

接受置放時，可能的置放目標應該指定透過設定 NativeDragManager.dropAction 屬性所選擇的動作，以回應 nativeDragDrop 事件。這個動作會回報給 nativeDragComplete 事件內的起始顯示物件。如果放下目標沒有設定任何動作，則會依照所允許動作的出現順序 (複製、移動、連結) 選取預設動作在事件中回報。初始物件會負責更新其內部狀態，以回應所選擇的動作。

這些動作名稱的字串常數是在 NativeDragActions 類別中定義。

事件序列

拖曳手勢一開始是在 mouseDown 或 mouseMove 事件處理常式內呼叫 NativeDragManager.doDrag() 方法，接著會進行下列事件序列以回應使用者的動作：

• nativeDragStart 事件 — 當呼叫 NativeDragManager.doDrag() 時，當做參數傳給此方法的互動式物件就會變成初始程式物件，並傳送 nativeDragStart 事件。
• nativeDragUpdate 事件 — 當拖曳作業進行時，初始程式物件會繼續傳送 nativeDragUpdate 事件。
• nativeDragEnter、nativeDragOver 事件 — 當拖曳手勢在互動式物件上方傳遞時，該物件會傳送 nativeDragEnter 事件。當拖曳手勢仍然在互動式物件上方時，它會繼續傳送 nativeDragOver 事件。為了回應這些事件的其中一個，當做可能置放目標的物件應該檢查事件物件的屬性，以決定它是否可以接受置放。如果資料格式和允許的動作都正確，則這些事件的事件處理常式必須呼叫 NativeDragManager.acceptDrop()，傳入當做置放目標之顯示物件的參考 (通常是傳送 nativeDragEnter 或 nativeDragOver 事件的物件)。然後，使用者可以將拖曳的項目放到目標上。
• nativeDragExit 事件 — 當拖曳手勢從互動式物件傳遞時，此物件會傳送 nativeDragExit 事件。如果已先呼叫 NativeDragManager.acceptDrop() 方法將該物件指定為拖曳目標，則該呼叫將不再有效，而且如果此手勢重新進入互動式物件，就必須再次呼叫 acceptDrop()。
• nativeDragDrop 事件 -- 當使用者在該物件上方放開滑鼠按鈕時，目標顯示物件會傳送 nativeDragDrop 事件。此事件的處理常式可以存取該事件物件之 transferable 屬性中的資料，而且應該設定 NativeDragManager.dropAction 屬性，告知初始程式物件應該採取哪個動作。
• nativeDragComplete -- 當使用者在結束拖曳手勢後放開滑鼠，初始程式物件都會傳送 nativeDragComplete 事件 (不管是否已接受該放置動作本身)。此事件的處理常式可以檢查該事件物件的 dropAction 屬性，以判斷其內部資料狀態應該進行何種修改 (如果要的話)，例如從清單中移除已拖曳出的項目。如果 dropAction 為 NativeDragActions.NONE，則不會將拖曳的項目放在可用的目標上。

應用程式之間的手勢

當拖曳手勢從非 AIR 應用程式視窗進入 AIR 應用程式視窗時，將沒有初始程式物件傳送 nativeDragStart 或 nativeDragComplete 事件。手勢期間傳送的這些事件，在其他方面都將遵循的模式，與在相同 AIR 應用程式中開始和結束之手勢的事件相同。

當拖曳手勢離開 AIR 應用程式視窗時，就沒有目標物件可傳送 nativeDragEnter、nativeDragOver 或 nativeDragDrop 事件。初始程式物件仍然會傳送 nativeDragComplete 事件，此事件會報告原生作業系統設定的拖曳動作 (如果該放下動作不被接受，則為 none)。

當拖曳手勢從某個 AIR 應用程式移至其他應用程式時，一如往常，初始程式和目標物件都會在其個別的應用程式中傳送事件。

傳輸資訊

在拖放手勢期間，所傳輸的資料都包含在 Clipboard 物件中。資料物件會透過開始拖曳手勢的 NativeDragManager.doDrag() 方法加入拖曳作業。可能的放下目標可以透過原生拖曳事件物件的 clipboard 屬性存取 Clipboard 物件。一旦拖曳作業開始，就只能在 NativeDragEvent 的事件處理常式中存取 Clipboard 物件。任何其他嘗試存取此物件的動作都會產生執行階段錯誤。

安全性考量

初始程式和可能之目標物件的安全執行程序可判斷如何存取正在拖曳的資料。如果這兩個物件都在相同的安全執行程序中，便可以從任何 NativeDragEvent 物件存取此資料。不過，如果初始程式和目標物件不在相同的安全執行程序中，則只能在 nativeDragDrop 事件之事件處理常式的目標安全執行程序中存取此資料。其他原生拖曳事件處理常式仍可以存取事件 clipboard 屬性中所參考的 Clipboard 物件，以判斷可使用何種資料格式；但是，呼叫 clipboard.getData() 方法會產生安全性錯誤。

相關 API 元素

---