# jQuery UI API - 可放置小部件（Droppable Widget） ## 所屬類別 [交互（Interactions）](ref-interactions.html) ## 用法 **描述：**為可拖拽小部件創建目標。 **版本新增：**1.0 **依賴：** * [UI 核心（UI Core）](ref-ui-core.html) * [部件庫（Widget Factory）](api-jQuery-widget.html) * [鼠標交互（Mouse Interaction）](api-mouse.html) **注釋：**jQuery UI 可放置（Droppable）插件讓被選元素可放置（意味著它們在拖拽后接受被放置）。您可以逐個指定哪一個 draggable 會接受。 ### 快速導航 | 選項 | 方法 | 事件 | | --- | --- | --- | | [accept](#option-accept)[activeClass](#option-activeClass)[addClasses](#option-addClasses)[disabled](#option-disabled)[greedy](#option-greedy)[hoverClass](#option-hoverClass)[scope](#option-scope)[tolerance](#option-tolerance) | [destroy](#method-destroy)[disable](#method-disable)[enable](#method-enable)[option](#method-option)[widget](#method-widget) | [activate](#event-activate)[create](#event-create)[deactivate](#event-deactivate)[drop](#event-drop)[out](#event-out)[over](#event-over) | #### accept **類型**：Selector 或 Function() **描述**：控制哪個可拖拽（draggable）元素可被 droppable 接受。 **支持多個類型：** * **Selector**：一個選擇器，指定哪個可拖拽（draggable）元素可被 droppable 接受。 * **Function()**：一個函數，將被頁面上每個 draggable 調用（作為第一個參數傳遞給函數）。如果 draggable 被接受，該函數必須返回 `true`。 **代碼實例：** 初始化帶有指定 `accept` 選項的 droppable： ``` $( ".selector" ).droppable({ accept: ".special" }); ``` 在初始化后，獲取或設置 `accept` 選項： ``` // getter var accept = $( ".selector" ).droppable( "option", "accept" ); // setter $( ".selector" ).droppable( "option", "accept", ".special" ); ``` **默認值**："*" #### activeClass **類型**：String **描述**：如果指定了該選項，當一個可接受的 draggable 被拖拽時，class 將被添加到 droppable。 **代碼實例：** 初始化帶有指定 `activeClass` 選項的 droppable： ``` $( ".selector" ).droppable({ activeClass: "ui-state-highlight" }); ``` 在初始化后，獲取或設置 `activeClass` 選項： ``` // getter var activeClass = $( ".selector" ).droppable( "option", "activeClass" ); // setter $( ".selector" ).droppable( "option", "activeClass", "ui-state-highlight" ); ``` **默認值**：false #### addClasses **類型**：Boolean **描述**：如果設置為 `false`，將防止 `ui-droppable` class 被添加。這在數百個元素上調用 `.droppable()` 時有助于性能優化。 **代碼實例：** 初始化帶有指定 `addClasses` 選項的 droppable： ``` $( ".selector" ).droppable({ addClasses: false }); ``` 在初始化后，獲取或設置 `addClasses` 選項： ``` // getter var addClasses = $( ".selector" ).droppable( "option", "addClasses" ); // setter $( ".selector" ).droppable( "option", "addClasses", false ); ``` **默認值**：true #### disabled **類型**：Boolean **描述**：如果設置為 `true`，則禁用該 droppable。 **代碼實例：** 初始化帶有指定 `disabled` 選項的 droppable： ``` $( ".selector" ).droppable({ disabled: true }); ``` 在初始化后，獲取或設置 `disabled` 選項： ``` // getter var disabled = $( ".selector" ).droppable( "option", "disabled" ); // setter $( ".selector" ).droppable( "option", "disabled", true ); ``` **默認值**：false #### greedy **類型**：Boolean **描述**：默認情況下，當一個元素被放置在嵌套是 droppable 上時，每個 droppable 將接收該元素。然而，通過設置該選項為 `true`，任何父元素的 droppable 將無法接收該元素。 `drop` 事件仍將照常，但會檢查 `event.target` 以便查看哪個 droppable 接收 draggable 元素。 **代碼實例：** 初始化帶有指定 `greedy` 選項的 droppable： ``` $( ".selector" ).droppable({ greedy: true }); ``` 在初始化后，獲取或設置 `greedy` 選項： ``` // getter var greedy = $( ".selector" ).droppable( "option", "greedy" ); // setter $( ".selector" ).droppable( "option", "greedy", true ); ``` **默認值**：false #### hoverClass **類型**：String **描述**：如果指定了該選項，當一個可接受 draggable 被覆蓋在 droppable 上時，class 將被添加到 droppable。 **代碼實例：** 初始化帶有指定 `hoverClass` 選項的 droppable： ``` $( ".selector" ).droppable({ hoverClass: "drop-hover" }); ``` 在初始化后，獲取或設置 `hoverClass` 選項： ``` // getter var hoverClass = $( ".selector" ).droppable( "option", "hoverClass" ); // setter $( ".selector" ).droppable( "option", "hoverClass", "drop-hover" ); ``` **默認值**：false #### scope **類型**：String **描述**：用于組合配套 draggable 和 droppable 項，除了 droppable 的 `accept` 選項之外。一個與 droppable 帶有相同的 `scope` 值的 draggable 會被該 droppable 接受。 **代碼實例：** 初始化帶有指定 `scope` 選項的 droppable： ``` $( ".selector" ).droppable({ scope: "tasks" }); ``` 在初始化后，獲取或設置 `scope` 選項： ``` // getter var scope = $( ".selector" ).droppable( "option", "scope" ); // setter $( ".selector" ).droppable( "option", "scope", "tasks" ); ``` **默認值**："default" #### tolerance **類型**：String **描述**：指定用于測試一個 draggable 是否覆蓋在一個 droppable 上的模式。可能的值： * `"fit"`：draggable 完全重疊在 droppable 上。 * `"intersect"`：draggable 重疊在 droppable 上，兩個方向上至少 50%。 * `"pointer"`：鼠標指針重疊在 droppable 上。 * `"touch"`：draggable 重疊在 droppable 上，任何數量皆可。 **代碼實例：** 初始化帶有指定 `tolerance` 選項的 droppable： ``` $( ".selector" ).droppable({ tolerance: "fit" }); ``` 在初始化后，獲取或設置 `tolerance` 選項： ``` // getter var tolerance = $( ".selector" ).droppable( "option", "tolerance" ); // setter $( ".selector" ).droppable( "option", "tolerance", "fit" ); ``` **默認值**："intersect" #### 方法 #### destroy() **類型**：jQuery (plugin only) **描述**：完全移除 droppable 功能。這會把元素返回到它的預初始化狀態。 * 該方法不接受任何參數。 **代碼實例：** 調用 destroy 方法： ``` $( ".selector" ).droppable( "destroy" ); ``` #### disable() **類型**：jQuery (plugin only) **描述**：禁用 droppable。 * 該方法不接受任何參數。 **代碼實例：** 調用 disable 方法： ``` $( ".selector" ).droppable( "disable" ); ``` #### enable() **類型**：jQuery (plugin only) **描述**：啟用 droppable。 * 該方法不接受任何參數。 **代碼實例：** 調用 enable 方法： ``` $( ".selector" ).droppable( "enable" ); ``` #### option( optionName ) **類型**：Object **描述**：獲取當前與指定的 `optionName` 關聯的值。 * **optionName** 類型：String 描述：要獲取的選項的名稱。 **代碼實例：** 調用該方法： ``` var isDisabled = $( ".selector" ).droppable( "option", "disabled" ); ``` #### option() **類型**：PlainObject **描述**：獲取一個包含鍵/值對的對象，鍵/值對表示當前 droppable 選項哈希。 * 該方法不接受任何參數。 **代碼實例：** 調用該方法： ``` var options = $( ".selector" ).droppable( "option" ); ``` #### option( optionName, value ) **類型**：jQuery (plugin only) **描述**：設置與指定的 `optionName` 關聯的 droppable 選項的值。 * **optionName** 類型：String 描述：要設置的選項的名稱。 * **value** 類型：Object 描述：要為選項設置的值。 **代碼實例：** 調用該方法： ``` $( ".selector" ).droppable( "option", "disabled", true ); ``` #### option( options ) **類型**：jQuery (plugin only) **描述**：為 droppable 設置一個或多個選項。 * **options** 類型：Object 描述：要設置的 option-value 對。 **代碼實例：** 調用該方法： ``` $( ".selector" ).droppable( "option", { disabled: true } ); ``` #### widget() **類型**：jQuery **描述**：返回一個包含 droppable 元素的 `jQuery` 對象。 * 該方法不接受任何參數。 **代碼實例：** 調用 widget 方法： ``` var widget = $( ".selector" ).droppable( "widget" ); ``` #### 事件 #### activate( event, ui ) **類型**：dropactivate **描述**：當一個可接受的 draggable 開始拖拽時觸發。如果您想讓 droppable 被放置時"點亮"，該選項就可以派上用場。 * **event** 類型：Event * **ui** 類型：Object * **draggable** 類型：jQuery 描述：jQuery 對象，表示 draggable 元素。 * **helper** 類型：jQuery 描述：jQuery 對象，表示被拖拽的助手（helper）。 * **position** 類型：Object 描述：draggable 助手（helper）的當前 CSS 位置，比如 `{ top, left }` 對象。 * **offset** 類型：Object 描述：draggable 助手（helper）的當前偏移位置，比如 `{ top, left }` 對象。 **代碼實例：** 初始化帶有指定 activate 回調的 droppable： ``` $( ".selector" ).droppable({ activate: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 dropactivate 事件： ``` $( ".selector" ).on( "dropactivate", function( event, ui ) {} ); ``` #### create( event, ui ) **類型**：dropcreate **描述**：當 droppable 被創建時觸發。 * **event** 類型：Event * **ui** 類型：Object 注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。 **代碼實例：** 初始化帶有指定 create 回調的 droppable： ``` $( ".selector" ).droppable({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 dropcreate 事件： ``` $( ".selector" ).on( "dropcreate", function( event, ui ) {} ); ``` #### deactivate( event, ui ) **類型**：dropdeactivate **描述**：當一個可接受的 draggable 停止拖拽時觸發。 * **event** 類型：Event * **ui** 類型：Object * **draggable** 類型：jQuery 描述：jQuery 對象，表示 draggable 元素。 * **helper** 類型：jQuery 描述：jQuery 對象，表示被拖拽的助手（helper）。 * **position** 類型：Object 描述：draggable 助手（helper）的當前 CSS 位置，比如 `{ top, left }` 對象。 * **offset** 類型：Object 描述：draggable 助手（helper）的當前偏移位置，比如 `{ top, left }` 對象。 **代碼實例：** 初始化帶有指定 deactivate 回調的 droppable： ``` $( ".selector" ).droppable({ deactivate: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 dropdeactivate 事件： ``` $( ".selector" ).on( "dropdeactivate", function( event, ui ) {} ); ``` #### drop( event, ui ) **類型**：drop **描述**：當一個可接受的 draggable 被放置在 droppable（基于 `[tolerance](#option-tolerance)` 選項）上時觸發。 * **event** 類型：Event * **ui** 類型：Object * **draggable** 類型：jQuery 描述：jQuery 對象，表示 draggable 元素。 * **helper** 類型：jQuery 描述：jQuery 對象，表示被拖拽的助手（helper）。 * **position** 類型：Object 描述：draggable 助手（helper）的當前 CSS 位置，比如 `{ top, left }` 對象。 * **offset** 類型：Object 描述：draggable 助手（helper）的當前偏移位置，比如 `{ top, left }` 對象。 **代碼實例：** 初始化帶有指定 drop 回調的 droppable： ``` $( ".selector" ).droppable({ drop: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 drop 事件： ``` $( ".selector" ).on( "drop", function( event, ui ) {} ); ``` #### out( event, ui ) **類型**：dropout **描述**：當 droppable 被拖拽出 droppable（基于 `[tolerance](#option-tolerance)` 選項）時觸發。 * **event** 類型：Event * **ui** 類型：Object 注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。 **代碼實例：** 初始化帶有指定 out 回調的 droppable： ``` $( ".selector" ).droppable({ out: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 dropout 事件： ``` $( ".selector" ).on( "dropout", function( event, ui ) {} ); ``` #### over( event, ui ) **類型**：dropover **描述**：當一個可接受的 draggable 被拖拽在 droppable（基于 `[tolerance](#option-tolerance)` 選項）上時觸發。 * **event** 類型：Event * **ui** 類型：Object * **draggable** 類型：jQuery 描述：jQuery 對象，表示 draggable 元素。 * **helper** 類型：jQuery 描述：jQuery 對象，表示被拖拽的助手（helper）。 * **position** 類型：Object 描述：draggable 助手（helper）的當前 CSS 位置，比如 `{ top, left }` 對象。 * **offset** 類型：Object 描述：draggable 助手（helper）的當前偏移位置，比如 `{ top, left }` 對象。 **代碼實例：** 初始化帶有指定 over 回調的 droppable： ``` $( ".selector" ).droppable({ over: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 dropover 事件： ``` $( ".selector" ).on( "dropover", function( event, ui ) {} ); ``` ## 實例 一對 draggable 和 droppable 元素。 ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>可放置小部件（Droppable Widget）演示</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/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="//code.jquery.com/jquery-1.10.2.js"></script> <script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script> </head> <body> <div id="droppable">請放置到這里！</div> <div id="draggable">請拖拽我！</div> <script> $( "#draggable" ).draggable(); $( "#droppable" ).droppable({ drop: function() { alert( "dropped" ); } }); </script> </body> </html> ```