Droppable Widget · jQuery UI API 中文文檔 1.10

# Droppable Widget Categories: [Interactions](http://www.css88.com/jquery-ui-api/category/interactions/ "View all posts in Interactions") ## version added: 1.0 **Description:** 創建拖動元素的目標。 ## QuickNav[Examples](#entry-examples) ### Options + [accept](#option-accept) + [activeClass](#option-activeClass) + [addClasses](#option-addClasses) + [disabled](#option-disabled) + [greedy](#option-greedy) + [hoverClass](#option-hoverClass) + [scope](#option-scope) + [tolerance](#option-tolerance) ### Methods + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [option](#method-option) + [widget](#method-widget) ### Events + [activate](#event-activate) + [create](#event-create) + [deactivate](#event-deactivate) + [drop](#event-drop) + [out](#event-out) + [over](#event-over) jQuery UI拖放插件可以使所選元素可拖放（這意味著[draggables](/draggable/)拖動可以被拖放接受）。您可以指定哪個拖動被接受。 ### Dependencies（依賴性） * [UI Core](/category/ui-core/) * [Widget Factory](/jQuery.widget/) * [Mouse Interaction](/mouse/) ## Options ### accept**Type:** [Selector](http://api.jquery.com/Types/#Selector) or [Function](http://api.jquery.com/Types/#Function)() **Default:** `"*"`控制可拖動的元素被拖放接受。**支持多種類型：** * **Selector**: 一個選擇器可拖動的元素。 * **Function**: 函數將被調用頁面上的每一個可拖動的（傳遞給函數的第一個參數）。該函數必須返回`true`，如果可拖動應該接受。 **Code examples:** 使用指定的`accept`參數初始化一個droppable： ``` $( ".selector" ).droppable({ accept: ".special" }); ``` 在初始化后設置或者獲取`accept`參數： ``` // getter var accept = $( ".selector" ).droppable( "option", "accept" ); // setter $( ".selector" ).droppable( "option", "accept", ".special" ); ``` ### activeClass**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `false`如果指定了該參數,在被允許的draggable對象填充時,droppable會被添加上指定的樣式。**Code examples:** 使用指定的`activeClass` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ activeClass: "ui-state-highlight" }); ``` 在初始化后設置或者獲取`activeClass`參數： ``` // getter var activeClass = $( ".selector" ).droppable( "option", "activeClass" ); // setter $( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" ); ``` ### addClasses**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `true`如果設置為`false`, 可以防止`ui-droppable`類在進行時添加. 這可能會使在初始化數百個元素執行`.droppable()`時使性能得到理想的優化.**Code examples:** 使用指定的`addClasses` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ addClasses: false }); ``` 在初始化后設置或者獲取`addClasses`參數： ``` // getter var addClasses = $( ".selector" ).droppable( "option", "addClasses" ); // setter $( ".selector" ).droppable( "option", "addClasses", false ); ``` ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為 `true`將禁止拖放。**Code examples:** 使用指定的`disabled` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ disabled: true }); ``` 在初始化后設置或者獲取`disabled`參數： ``` // getter var disabled = $( ".selector" ).droppable( "option", "disabled" ); // setter $( ".selector" ).droppable( "option", "disabled", true ); ``` ### greedy**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`默認情況下，當一個元素被放到嵌套的放置（droppable）對象時，每個放置（droppable）對象都將接收到這個元素。然而，當設置這個選項為`true`時，任何父級的放置（droppable）對象不會接收元素。`drop`事件將依然會正常的泡沫，但`event.target`查看哪個放置（droppable）對象接受了拖動元素。**Code examples:** 使用指定的`greedy` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ greedy: true }); ``` 在初始化后設置或者獲取`greedy`參數： ``` // getter var greedy = $( ".selector" ).droppable( "option", "greedy" ); // setter $( ".selector" ).droppable( "option", "greedy", true ); ``` ### hoverClass**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `false`如果設置了該參數,將在一個被允許的拖動元素懸停在放置（droppable）對象上時，向放置（droppable）對象添加一個指定的樣式.**Code examples:** 使用指定的`hoverClass` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ hoverClass: "drop-hover" }); ``` 在初始化后設置或者獲取`hoverClass`參數： ``` // getter var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" ); // setter $( ".selector" ).droppable( "option", "hoverClass", "drop-hover" ); ``` ### scope**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `"default"`用來設置拖動（draggle）元素和放置（droppable）對象的集合, 除了droppable中的[`accept`](#option-accept)屬性指定的元素外,和放置（droppable）對象相同集合的放置（droppable）對象也被允許添加到放置（droppable）對象中.**Code examples:** 使用指定的`scope` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ scope: "tasks" }); ``` 在初始化后設置或者獲取`scope`參數： ``` // getter var scope = $( ".selector" ).droppable( "option", "scope" ); // setter $( ".selector" ).droppable( "option", "scope", "tasks" ); ``` ### tolerance**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `"intersect"`指定使用那種模式來測試一個拖動(draggable)元素"經過"一個放置（droppable）對象。允許使用的值: * `"fit"`: 拖動(draggable)元素完全重疊到放置（droppable）對象。 * `"intersect"`: 拖動(draggable)元素和放置（droppable）對象至少重疊50%。 * `"pointer"`: 鼠標重疊到放置（droppable）對象上。 * `"touch"`: 拖動(draggable)元素和放置（droppable）對象的任意重疊 **Code examples:** 使用指定的`tolerance` 參數初始化一個droppable： ``` $( ".selector" ).droppable({ tolerance: "fit" }); ``` 在初始化后設置或者獲取`tolerance`參數： ``` // getter var tolerance = $( ".selector" ).droppable( "option", "tolerance" ); // setter $( ".selector" ).droppable( "option", "tolerance", "fit" ); ``` ## Methods（方法） ### destroy() 完全移除拖放功能. 這將使元素返回到之前的初始化狀態. * 這個方法不接受任何參數 **Code examples:** 調用destroy 方法 ``` $( ".selector" ).droppable( "destroy" ); ``` ### disable() 禁用拖放。 * 這個方法不接受任何參數 **Code examples:** 調用disable 方法 ``` $( ".selector" ).droppable( "disable" ); ``` ### enable() 啟用拖放。 * 這個方法不接受任何參數 **Code examples:** 調用enable 方法 ``` $( ".selector" ).droppable( "enable" ); ``` ### option( optionName )Returns: [Object](http://api.jquery.com/Types/#Object) 通過指定的`optionName`獲取當前關聯的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要獲取值的選項名 **Code examples:** 調用這個方法： ``` var isDisabled = $( ".selector" ).droppable( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個對象，它包含表示當前droppable的選項hash的鍵/值對。 * 這個方法不接受任何參數 **Code examples:** 調用這個方法： ``` var options = $( ".selector" ).droppable( "option" ); ``` ### option( optionName, value ) 通過指定的`optionName`，設置droppable的相關選項值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置值的選項名。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要設置選項的值。 **Code examples:** 調用這個方法： ``` $( ".selector" ).droppable( "option", "disabled", true ); ``` ### option( options ) 為droppable設置一個或多個選項。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)設置的選項/值對的對象。 **Code examples:** 調用這個方法： ``` $( ".selector" ).droppable( "option", { disabled: true } ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個`jQuery` ，它包含了droppable元素。 * 這個方法不接受任何參數 **Code examples:** 調用widget 方法 ``` var widget = $( ".selector" ).droppable( "widget" ); ``` ## Events ### activate( event, ui )Type: `dropactivate` 這個事件會在任何允許的draggable對象開始拖動時觸發。它可以用來在你想讓droppable對象在可以被填充的時"亮起來"的時候。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **draggable**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表的拖動元素。 * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表被拖動元素的助手。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的CSS的position（位置）對象，如`{ top, left }`。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的偏移位置對象，如`{ top, left }`。 **Code examples:** 使用指定的activate 回調初始化一個droppable： ``` $( ".selector" ).droppable({ activate: function( event, ui ) {} }); ``` 綁定一個事件監聽到dropactivate事件: ``` $( ".selector" ).on( "dropactivate", function( event, ui ) {} ); ``` ### create( event, ui )Type: `dropcreate` 此事件會在droppable創建時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui`對象是空對象，包括是為了和其他事件的一致性。_ **Code examples:** 使用指定的create 回調初始化一個droppable： ``` $( ".selector" ).droppable({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽到dropcreate事件： ``` $( ".selector" ).on( "dropcreate", function( event, ui ) {} ); ``` ### deactivate( event, ui )Type: `dropdeactivate` 此事件會在任何允許的draggable對象停止拖動時觸發. * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **draggable**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表的拖動元素。 * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表被拖動元素的助手。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的CSS的position（位置）對象，如`{ top, left }`。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的偏移位置對象，如`{ top, left }`。 **Code examples:** 使用指定的deactivate 回調初始化一個droppable： ``` $( ".selector" ).droppable({ deactivate: function( event, ui ) {} }); ``` 綁定一個事件監聽到dropdeactivate事件： ``` $( ".selector" ).on( "dropdeactivate", function( event, ui ) {} ); ``` ### drop( event, ui )Type: `drop` 這個事件會在一個允許的拖動（draggable）元素填充進這個放置（droppable）對象時觸發.（基于[`tolerance`](#option-tolerance)選項）。（愚人碼頭注釋：回調函數中, $(this) 表示被填充的droppable對象. ui.draggable 表示draggable對象.） * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **draggable**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表的拖動元素。 * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表被拖動元素的助手。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的CSS的position（位置）對象，如`{ top, left }`。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的偏移位置對象，如`{ top, left }`。 **Code examples:** 使用指定的drop 回調初始化一個droppable： ``` $( ".selector" ).droppable({ drop: function( event, ui ) {} }); ``` 綁定一個事件監聽到drop事件： ``` $( ".selector" ).on( "drop", function( event, ui ) {} ); ``` ### out( event, ui )Type: `dropout` 此事件會在一個允許的拖動（draggable）元素離開這個放置（droppable）對象時觸發（基于[`tolerance`](#option-tolerance)選項）。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui`對象是空對象，包括是為了和其他事件的一致性。_ **Code examples:** 使用指定的out 回調初始化一個droppable： ``` $( ".selector" ).droppable({ out: function( event, ui ) {} }); ``` 綁定一個事件監聽到dropout事件： ``` $( ".selector" ).on( "dropout", function( event, ui ) {} ); ``` ### over( event, ui )Type: `dropover` 此事件會在一個允許的拖動（draggable）元素經過這個放置（droppable）對象時觸發（基于[`tolerance`](#option-tolerance)選項）。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **draggable**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表的拖動元素。 * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)一個jQuery對象代表被拖動元素的助手。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的CSS的position（位置）對象，如`{ top, left }`。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)當前可拖動助手的偏移位置對象，如`{ top, left }`。 **Code examples:** 使用指定的over 回調初始化一個droppable： ``` $( ".selector" ).droppable({ over: function( event, ui ) {} }); ``` 綁定一個事件監聽到dropover事件： ``` $( ".selector" ).on( "dropover", function( event, ui ) {} ); ``` ## Example: #### A pair of draggable and droppable elements. ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>droppable demo</title> <link rel="stylesheet" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css"> <style> #draggable { width: 100px; height: 100px; background: #ccc; } #droppable { position: absolute; left: 250px; top: 0; width: 125px; height: 125px; background: #999; color: #fff; padding: 10px; } </style> <script src="http://code.jquery.com/jquery-1.9.1.js"></script> <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.js"></script> </head> <body> <div id="droppable">Drop here</div> <div id="draggable">Drag me</div> <script> $( "#draggable" ).draggable(); $( "#droppable" ).droppable({ drop: function() { alert( "dropped" ); } }); </script> </body> </html> ```