Sortable Widget · jQuery UI API 中文文檔 1.10

# Sortable 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 + [appendTo](#option-appendTo) + [axis](#option-axis) + [cancel](#option-cancel) + [connectWith](#option-connectWith) + [containment](#option-containment) + [cursor](#option-cursor) + [cursorAt](#option-cursorAt) + [delay](#option-delay) + [disabled](#option-disabled) + [distance](#option-distance) + [dropOnEmpty](#option-dropOnEmpty) + [forceHelperSize](#option-forceHelperSize) + [forcePlaceholderSize](#option-forcePlaceholderSize) + [grid](#option-grid) + [handle](#option-handle) + [helper](#option-helper) + [items](#option-items) + [opacity](#option-opacity) + [placeholder](#option-placeholder) + [revert](#option-revert) + [scroll](#option-scroll) + [scrollSensitivity](#option-scrollSensitivity) + [scrollSpeed](#option-scrollSpeed) + [tolerance](#option-tolerance) + [zIndex](#option-zIndex) ### Methods + [cancel](#method-cancel) + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [option](#method-option) + [refresh](#method-refresh) + [refreshPositions](#method-refreshPositions) + [serialize](#method-serialize) + [toArray](#method-toArray) + [widget](#method-widget) ### Events + [activate](#event-activate) + [beforeStop](#event-beforeStop) + [change](#event-change) + [create](#event-create) + [deactivate](#event-deactivate) + [out](#event-out) + [over](#event-over) + [receive](#event-receive) + [remove](#event-remove) + [sort](#event-sort) + [start](#event-start) + [stop](#event-stop) + [update](#event-update) jQuery UI 可排序（Sortable）插件讓被被選擇的元素通過鼠標拖拽進行排序。 _注意：為了排序表格中的行，`tbody`元素必須作為sortable（可排序元素），而不是在`table`。_ ### Dependencies * [UI Core](/category/ui-core/) * [Widget Factory](/jQuery.widget/) * [Mouse Interaction](/mouse/) ## Options ### appendTo**Type:** [jQuery](http://api.jquery.com/Types/#jQuery) or [Element](http://api.jquery.com/Types/#Element) or [Selector](http://api.jquery.com/Types/#Selector) or [String](http://api.jquery.com/Types/#String) **Default:** `"parent"`確定可移動的輔助元素在拖動時可以被添加到何處 (例如, 解決重疊/ zIndex問題)。**支持多種類型:** * **jQuery**: 一個 jQuery 對象，包含輔助（helper）元素要追加到的元素。 * **Element**: 要被追加輔助（helper）元素的元素。 * **Selector**: 一個選擇器，指定哪個元素要追加輔助（helper）元素。 * **String**:字符串`"parent"`將促使助手（helper）成為 sortable 項目的同級。 **Code examples:** 使用指定的 `appendTo` 參數初始化 sortable : ``` $( ".selector" ).sortable({ appendTo: document.body }); ``` 在初始化后設置或者獲取 `appendTo` 參數： ``` // getter var appendTo = $( ".selector" ).sortable( "option", "appendTo" ); // setter $( ".selector" ).sortable( "option", "appendTo", document.body ); ``` ### axis**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `false`如果定義了該參數, 元素可以在水平或垂直方向上實現拖動. 允許使用的值:`"x"`, `"y"`。**Code examples:** 使用指定的 `axis` 參數初始化 sortable : ``` $( ".selector" ).sortable({ axis: "x" }); ``` 在初始化后設置或者獲取 `axis` 參數： ``` // getter var axis = $( ".selector" ).sortable( "option", "axis" ); // setter $( ".selector" ).sortable( "option", "axis", "x" ); ``` ### cancel**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `"input,textarea,button,select,option"`對符合選擇器匹配規則的元素不進行排序。**Code examples:** 使用指定的 `cancel` 參數初始化 sortable : ``` $( ".selector" ).sortable({ cancel: "a,button" }); ``` 在初始化后設置或者獲取 `cancel` 參數： ``` // getter var cancel = $( ".selector" ).sortable( "option", "cancel" ); // setter $( ".selector" ).sortable( "option", "cancel", "a,button" ); ``` ### connectWith**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `false`列表中的項目需被連接的另一個 sortable 元素的選擇器。這是一個單向關系，如果您想要項目被雙向連接，必須在兩個 sortable 元素上都設置 `connectWith` 選項。**Code examples:** 使用指定的 `connectWith` 參數初始化 sortable : ``` $( ".selector" ).sortable({ connectWith: "#shopping-cart" }); ``` 在初始化后設置或者獲取 `connectWith` 參數： ``` // getter var connectWith = $( ".selector" ).sortable( "option", "connectWith" ); // setter $( ".selector" ).sortable( "option", "connectWith", "#shopping-cart" ); ``` ### containment**Type:** [Element](http://api.jquery.com/Types/#Element) or [Selector](http://api.jquery.com/Types/#Selector) or [String](http://api.jquery.com/Types/#String) **Default:** `false` 定義一個邊界，限制拖動范圍在指定的DOM元素內。注意：為限制拖動范圍，指定的元素必須有一個可計算的寬度和高度（但不一定是顯式的）。例如，如果你的sortable元素的子元素有`float: left`樣式，并且指定`containment: "parent"`，那么sortable/parent容器必須要有`float: left`樣式，或者他將有`height: 0`樣式，導致不確定的行為。 **支持多種類型:** * **Element**: 一個用來作為容器的元素。 * **Selector**:一個選擇器指定的元素，這個元素用來作為容器 * **String**: 一個字符串指定的元素，這個元素用來作為容器。可能的值: `"parent"`, `"document"`, `"window"`。 **Code examples:** 使用指定的 `containment` 參數初始化 sortable : ``` $( ".selector" ).sortable({ containment: "parent" }); ``` 在初始化后設置或者獲取 `containment` 參數： ``` // getter var containment = $( ".selector" ).sortable( "option", "containment" ); // setter $( ".selector" ).sortable( "option", "containment", "parent" ); ``` ### cursor**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `"auto"`定義排序拖動時的鼠標指針樣式.**Code examples:** 使用指定的 `cursor` 參數初始化 sortable : ``` $( ".selector" ).sortable({ cursor: "move" }); ``` 在初始化后設置或者獲取 `cursor` 參數： ``` // getter var cursor = $( ".selector" ).sortable( "option", "cursor" ); // setter $( ".selector" ).sortable( "option", "cursor", "move" ); ``` ### cursorAt**Type:** [Object](http://api.jquery.com/Types/#Object) **Default:** `false`移動排序元素或助手（helper），這樣光標總是出現，以便從相同的位置進行拖拽。坐標可通過一個或兩個鍵的組合成一個哈希給出： `{ top, left, right, bottom }`。**Code examples:** 使用指定的 `cursorAt` 參數初始化 sortable : ``` $( ".selector" ).sortable({ cursorAt: { left: 5 } }); ``` 在初始化后設置或者獲取 `cursorAt` 參數： ``` // getter var cursorAt = $( ".selector" ).sortable( "option", "cursorAt" ); // setter $( ".selector" ).sortable( "option", "cursorAt", { left: 5 } ); ``` ### delay**Type:** [Integer](http://api.jquery.com/Types/#Integer) **Default:** `0`在排序拖動開始多少毫秒后元素才開始移動. 這可以防止意外的點擊造成元素的拖動.**Code examples:** 使用指定的 `delay` 參數初始化 sortable : ``` $( ".selector" ).sortable({ delay: 150 }); ``` 在初始化后設置或者獲取 `delay` 參數： ``` // getter var delay = $( ".selector" ).sortable( "option", "delay" ); // setter $( ".selector" ).sortable( "option", "delay", 150 ); ``` ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為`true`，將禁用sortable。**Code examples:** 使用指定的 `disabled` 參數初始化 sortable : ``` $( ".selector" ).sortable({ disabled: true }); ``` 在初始化后設置或者獲取 `disabled` 參數： ``` // getter var disabled = $( ".selector" ).sortable( "option", "disabled" ); // setter $( ".selector" ).sortable( "option", "disabled", true ); ``` ### distance**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `1`設置當排序拖動開始多少個像素之后元素才開始移動.以像素計。如果指定了該參數, 排序不會馬上開始,直到鼠標移動達到了指定的像素值.**Code examples:** 使用指定的 `distance` 參數初始化 sortable : ``` $( ".selector" ).sortable({ distance: 5 }); ``` 在初始化后設置或者獲取 `distance` 參數： ``` // getter var distance = $( ".selector" ).sortable( "option", "distance" ); // setter $( ".selector" ).sortable( "option", "distance", 5 ); ``` ### dropOnEmpty**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `true`如果為`false`，這個sortable中項不能拖動到一個空的sortable中。(查看[`connectWith`](#option-connectWith) 選項.**Code examples:** 使用指定的 `dropOnEmpty` 參數初始化 sortable : ``` $( ".selector" ).sortable({ dropOnEmpty: false }); ``` 在初始化后設置或者獲取 `dropOnEmpty` 參數： ``` // getter var dropOnEmpty = $( ".selector" ).sortable( "option", "dropOnEmpty" ); // setter $( ".selector" ).sortable( "option", "dropOnEmpty", false ); ``` ### forceHelperSize**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果為`true`, 強迫輔助元素（helper）有一個尺寸大小。**Code examples:** 使用指定的 `forceHelperSize` 參數初始化 sortable : ``` $( ".selector" ).sortable({ forceHelperSize: true }); ``` 在初始化后設置或者獲取 `forceHelperSize` 參數： ``` // getter var forceHelperSize = $( ".selector" ).sortable( "option", "forceHelperSize" ); // setter $( ".selector" ).sortable( "option", "forceHelperSize", true ); ``` ### forcePlaceholderSize**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果為`true`, 強迫占位符（placeholder）有一個尺寸大小。**Code examples:** 使用指定的 `forcePlaceholderSize` 參數初始化 sortable : ``` $( ".selector" ).sortable({ forcePlaceholderSize: true }); ``` 在初始化后設置或者獲取 `forcePlaceholderSize` 參數： ``` // getter var forcePlaceholderSize = $( ".selector" ).sortable( "option", "forcePlaceholderSize" ); // setter $( ".selector" ).sortable( "option", "forcePlaceholderSize", true ); ``` ### grid**Type:** [Array](http://api.jquery.com/Types/#Array) **Default:** `false`設置排序對象或者輔助對象（helper）有一個x和y邊距,(單位:像素). 數組值: `[ x, y ]`。**Code examples:** 使用指定的 `grid` 參數初始化 sortable : ``` $( ".selector" ).sortable({ grid: [ 20, 10 ] }); ``` 在初始化后設置或者獲取 `grid` 參數： ``` // getter var grid = $( ".selector" ).sortable( "option", "grid" ); // setter $( ".selector" ).sortable( "option", "grid", [ 20, 10 ] ); ``` ### handle**Type:** [Selector](http://api.jquery.com/Types/#Selector) or [Element](http://api.jquery.com/Types/#Element) **Default:** `false`如果設定了此參數,那么拖動會在對象內指定的元素上開始.**Code examples:** 使用指定的 `handle` 參數初始化 sortable : ``` $( ".selector" ).sortable({ handle: ".handle" }); ``` 在初始化后設置或者獲取 `handle` 參數： ``` // getter var handle = $( ".selector" ).sortable( "option", "handle" ); // setter $( ".selector" ).sortable( "option", "handle", ".handle" ); ``` ### helper**Type:** [String](http://api.jquery.com/Types/#String) or [Function](http://api.jquery.com/Types/#Function)() **Default:** `"original"`允許使用一個輔助元素來進行拖動時展示. 所提供的函數在拖動時接受事件和對象元素, 并且需要返回一個DOMElement對象用來當作輔助對象.**允許使用的值：** * **String**:如果設置為`"clone"`，那么這個元素將被克隆，并且克隆出來的元素將被拖動。 * **Function**: 一個函數，將返回拖拽時要使用的 DOMElement。函數接收事件，且元素正被排序。 **Code examples:** 使用指定的 `helper` 參數初始化 sortable : ``` $( ".selector" ).sortable({ helper: "clone" }); ``` 在初始化后設置或者獲取 `helper` 參數： ``` // getter var helper = $( ".selector" ).sortable( "option", "helper" ); // setter $( ".selector" ).sortable( "option", "helper", "clone" ); ``` ### items**Type:** [Selector](http://api.jquery.com/Types/#Selector) **Default:** `"> *"`指定元素內的哪一個項目應是 sortable。**Code examples:** 使用指定的 `items` 參數初始化 sortable : ``` $( ".selector" ).sortable({ items: "> li" }); ``` 在初始化后設置或者獲取 `items` 參數： ``` // getter var items = $( ".selector" ).sortable( "option", "items" ); // setter $( ".selector" ).sortable( "option", "items", "> li" ); ``` ### opacity**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `false`當排序時助手（helper）的不透明度。從`0.01` 到 `1`。**Code examples:** 使用指定的 `opacity` 參數初始化 sortable : ``` $( ".selector" ).sortable({ opacity: 0.5 }); ``` 在初始化后設置或者獲取 `opacity` 參數： ``` // getter var opacity = $( ".selector" ).sortable( "option", "opacity" ); // setter $( ".selector" ).sortable( "option", "opacity", 0.5 ); ``` ### placeholder**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `false`要應用的 class 名稱，否則為白色空白。**Code examples:** 使用指定的 `placeholder` 參數初始化 sortable : ``` $( ".selector" ).sortable({ placeholder: "sortable-placeholder" }); ``` 在初始化后設置或者獲取 `placeholder` 參數： ``` // getter var placeholder = $( ".selector" ).sortable( "option", "placeholder" ); // setter $( ".selector" ).sortable( "option", "placeholder", "sortable-placeholder" ); ``` ### revert**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [Number](http://api.jquery.com/Types/#Number) **Default:** `false`sortable 項目是否使用一個流暢的動畫還原到它的新位置。**支持多個類型：** * **Boolean**:當設置為 `true`，該項目將會使用動畫，動畫使用默認的持續時間。 * **Number**: 動畫的持續時間，以毫秒計。 **Code examples:** 使用指定的 `revert` 參數初始化 sortable : ``` $( ".selector" ).sortable({ revert: true }); ``` 在初始化后設置或者獲取 `revert` 參數： ``` // getter var revert = $( ".selector" ).sortable( "option", "revert" ); // setter $( ".selector" ).sortable( "option", "revert", true ); ``` ### scroll**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `true`如果設置為 `true`，當到達邊緣時頁面會滾動。**Code examples:** 使用指定的 `scroll` 參數初始化 sortable : ``` $( ".selector" ).sortable({ scroll: false }); ``` 在初始化后設置或者獲取 `scroll` 參數： ``` // getter var scroll = $( ".selector" ).sortable( "option", "scroll" ); // setter $( ".selector" ).sortable( "option", "scroll", false ); ``` ### scrollSensitivity**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `20`定義鼠標距離邊緣多少距離時開始滾動。**Code examples:** 使用指定的 `scrollSensitivity` 參數初始化 sortable : ``` $( ".selector" ).sortable({ scrollSensitivity: 10 }); ``` 在初始化后設置或者獲取 `scrollSensitivity` 參數： ``` // getter var scrollSensitivity = $( ".selector" ).sortable( "option", "scrollSensitivity" ); // setter $( ".selector" ).sortable( "option", "scrollSensitivity", 10 ); ``` ### scrollSpeed**Type:** [Number](http://api.jquery.com/Types/#Number) **Default:** `20`當鼠標指針獲取到在 [`scrollSensitivity`](#option-scrollSensitivity) 距離內時，窗體滾動的速度。如果 scroll 選項是 false 則忽略。**Code examples:** 使用指定的 `scrollSpeed` 參數初始化 sortable : ``` $( ".selector" ).sortable({ scrollSpeed: 40 }); ``` 在初始化后設置或者獲取 `scrollSpeed` 參數： ``` // getter var scrollSpeed = $( ".selector" ).sortable( "option", "scrollSpeed" ); // setter $( ".selector" ).sortable( "option", "scrollSpeed", 40 ); ``` ### tolerance**Type:** [String](http://api.jquery.com/Types/#String) **Default:** `"intersect"`指定用于測試項目被移動時是否覆蓋在另一個項目上的模式。可能的值： * `"intersect"`：項目至少 50% 重疊在其他項目上。 * `"pointer"`：鼠標指針重疊在其他項目上。 **Code examples:** 使用指定的 `tolerance` 參數初始化 sortable : ``` $( ".selector" ).sortable({ tolerance: "pointer" }); ``` 在初始化后設置或者獲取 `tolerance` 參數： ``` // getter var tolerance = $( ".selector" ).sortable( "option", "tolerance" ); // setter $( ".selector" ).sortable( "option", "tolerance", "pointer" ); ``` ### zIndex**Type:** [Integer](http://api.jquery.com/Types/#Integer) **Default:** `1000`當被排序時，元素/助手（helper）元素的 Z-index。**Code examples:** 使用指定的 `zIndex` 參數初始化 sortable : ``` $( ".selector" ).sortable({ zIndex: 9999 }); ``` 在初始化后設置或者獲取 `zIndex` 參數： ``` // getter var zIndex = $( ".selector" ).sortable( "option", "zIndex" ); // setter $( ".selector" ).sortable( "option", "zIndex", 9999 ); ``` ## Methods ### cancel() 當前排序開始時，取消一個在當前 sortable 中的改變，且恢復到之前的狀態。在 stop 和 receive 回調函數中非常有用。 * 該方法不接受任何參數。 **Code examples:** 調用 cancel 方法： ``` $( ".selector" ).sortable( "cancel" ); ``` ### destroy() 完全移除 sortable 功能。這會把元素返回到它的預初始化狀態。 * 該方法不接受任何參數。 **Code examples:** 調用 destroy 方法： ``` $( ".selector" ).sortable( "destroy" ); ``` ### disable() 禁用 sortable。 * 該方法不接受任何參數。 **Code examples:** 調用 disable 方法： ``` $( ".selector" ).sortable( "disable" ); ``` ### enable() 啟用 sortable。 * 該方法不接受任何參數。 **Code examples:** 調用 enable 方法： ``` $( ".selector" ).sortable( "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" ).sortable( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個包含鍵/值對的對象，鍵/值對表示當前 sortable 選項哈希。 * 該方法不接受任何參數。 **Code examples:** 調用該方法： ``` var options = $( ".selector" ).sortable( "option" ); ``` ### option( optionName, value ) 設置與指定的 `optionName` 關聯的 sortable 選項的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置的選項的名稱。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要為選項設置的值。 **Code examples:** 調用該方法： ``` $( ".selector" ).sortable( "option", "disabled", true ); ``` ### option( options ) 為 sortable 設置一個或多個選項。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的 option-value 對。 **Code examples:** 調用該方法： ``` $( ".selector" ).sortable( "option", { disabled: true } ); ``` ### refresh() 刷新 sortable 項目。觸發所有 sortable 項目重新加載，導致新的項目被認可。 * 該方法不接受任何參數。 **Code examples:** 調用 refresh 方法： ``` $( ".selector" ).sortable( "refresh" ); ``` ### refreshPositions() 刷新 sortable 項目的緩存位置。調用該方法刷新所有 sortable 的已緩存的項目位置。 * 該方法不接受任何參數。 **Code examples:** 調用 refreshPositions 方法： ``` $( ".selector" ).sortable( "refreshPositions" ); ``` ### serialize( options )Returns: [String](http://api.jquery.com/Types/#String) 序列化 sortable 的項目 `id` 為一個 form/ajax 可提交的字符串。調用該方法會產生一個可被追加到任何 url 中的哈希，以便簡單地把一個新的項目順序提交回服務器。默認情況下，它通過每個項目的 `id` 進行工作，id 格式為 `"setname_number"`，且它會產生一個形如 `"setname[]=number&setname[]=number"` 的哈希。注釋：如果序列化返回一個空的字符串，請確認 `id` 屬性包含一個下劃線（_）。形式必須是 `"set_number"`。例如，一個 `id` 屬性為 `"foo_1"`、`"foo_5"`、`"foo_2"` 的 3 元素列表將序列化為 `"foo[]=1&foo[]=5&foo[]=2"`。您可以使用下劃線（_）、等號（=）或連字符（-）來分隔集合和數字。例如，`"foo=1"`、`"foo-1"`、`"foo_1"` 所有都序列化為 `"foo[]=1"`。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要自定義序列化的選項。 * **key**（默認值：`屬性中分隔符前面的部分`）類型：String 描述：把 `part1[]` 替換為指定的值。 * **attribute**（默認值：`"id"`）類型：String 描述：值要使用的屬性名稱。 * **expression**（默認值：`/(.+)[-=_](.+)/`）類型：RegExp 描述：用于把屬性值分隔為鍵和值兩部分的正則表達式。 **Code examples:** 調用 serialize 方法： ``` var sorted = $( ".selector" ).sortable( "serialize", { key: "sort" } ); ``` ### toArray( options )Returns: [Array](http://api.jquery.com/Types/#Array) 序列化 sortable 的項目 id 為一個字符串的數組。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要自定義序列化的選項。 * **attribute** (default: `"id"`)Type: [String](http://api.jquery.com/Types/#String)值要使用的屬性名稱。 **Code examples:** 調用 toArray 方法： ``` var sortedIDs = $( ".selector" ).sortable( "toArray" ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個包含 sortable 元素的 `jQuery` 對象。 * 該方法不接受任何參數。 **Code examples:** 調用 widget 方法： ``` var widget = $( ".selector" ).sortable( "widget" ); ``` ## Events ### activate( event, ui )Type: `sortactivate` 當使用被連接列表時觸發該事件，每個被連接列表在拖拽開始時接收它。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 activate 回調的 sortable： ``` $( ".selector" ).sortable({ activate: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortactivate 事件： ``` $( ".selector" ).on( "sortactivate", function( event, ui ) {} ); ``` ### beforeStop( event, ui )Type: `sortbeforestop` 當排序停止時觸發該事件，除了當占位符（placeholder）/助手（helper）仍然可用時。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 beforeStop 回調的 sortable： ``` $( ".selector" ).sortable({ beforeStop: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortbeforestop 事件： ``` $( ".selector" ).on( "sortbeforestop", function( event, ui ) {} ); ``` ### change( event, ui )Type: `sortchange` 在排序期間觸發該事件，除了當 DOM 位置改變時。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 change 回調的 sortable： ``` $( ".selector" ).sortable({ change: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortchange 事件： ``` $( ".selector" ).on( "sortchange", function( event, ui ) {} ); ``` ### create( event, ui )Type: `sortcreate` 當 droppable 被創建時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。_ **Code examples:** 使用指定的 create 回調的 sortable： ``` $( ".selector" ).sortable({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortcreate 事件： ``` $( ".selector" ).on( "sortcreate", function( event, ui ) {} ); ``` ### deactivate( event, ui )Type: `sortdeactivate` 當排序停止時觸發該事件，該事件傳播到所有可能的連接列表。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 deactivate 回調的 sortable： ``` $( ".selector" ).sortable({ deactivate: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortdeactivate 事件： ``` $( ".selector" ).on( "sortdeactivate", function( event, ui ) {} ); ``` ### out( event, ui )Type: `sortout` 當一個 sortable 項目從一個 sortable 列表移除時觸發該事件。 _Note: 當一個 sortable 項目被撤銷時也會觸發該事件。_ * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 out 回調的 sortable： ``` $( ".selector" ).sortable({ out: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortout 事件： ``` $( ".selector" ).on( "sortout", function( event, ui ) {} ); ``` ### over( event, ui )Type: `sortover` 當一個 sortable 項目移動到一個 sortable 列表時觸發該事件。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 over 回調的 sortable： ``` $( ".selector" ).sortable({ over: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortover 事件： ``` $( ".selector" ).on( "sortover", function( event, ui ) {} ); ``` ### receive( event, ui )Type: `sortreceive` 當來自一個連接的 sortable 列表的一個項目被放置到另一個列表時觸發該事件。后者是事件目標。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 receive 回調的 sortable： ``` $( ".selector" ).sortable({ receive: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortreceive 事件： ``` $( ".selector" ).on( "sortreceive", function( event, ui ) {} ); ``` ### remove( event, ui )Type: `sortremove` 當來自一個連接的 sortable 列表的一個項目被放置到另一個列表時觸發該事件。前者是事件目標。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 remove 回調的 sortable： ``` $( ".selector" ).sortable({ remove: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortremove 事件： ``` $( ".selector" ).on( "sortremove", function( event, ui ) {} ); ``` ### sort( event, ui )Type: `sort` 在排序期間觸發該事件。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 sort 回調的 sortable： ``` $( ".selector" ).sortable({ sort: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sort 事件： ``` $( ".selector" ).on( "sort", function( event, ui ) {} ); ``` ### start( event, ui )Type: `sortstart` 當排序開始時觸發該事件。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 start 回調的 sortable： ``` $( ".selector" ).sortable({ start: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortstart 事件： ``` $( ".selector" ).on( "sortstart", function( event, ui ) {} ); ``` ### stop( event, ui )Type: `sortstop` 當排序停止時觸發該事件。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 stop 回調的 sortable： ``` $( ".selector" ).sortable({ stop: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortstop 事件： ``` $( ".selector" ).on( "sortstop", function( event, ui ) {} ); ``` ### update( event, ui )Type: `sortupdate` 當用戶停止排序且 DOM 位置改變時觸發該事件。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) * **helper**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被排序的助手（helper）。 * **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示當前被拖拽的元素。 * **offset**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前的絕對位置，表示為 `{ top, left }`。 * **position**Type: [Object](http://api.jquery.com/Types/#Object)助手（helper）的當前位置，表示為 `{ top, left }`. * **originalPosition**Type: [Object](http://api.jquery.com/Types/#Object)元素的原始位置，表示為`{ top, left }`. * **sender**Type: [jQuery](http://api.jquery.com/Types/#jQuery)如果從一個 sortable 移動到另一個 sortable，項目來自的那個 * **placeholder**Type: [jQuery](http://api.jquery.com/Types/#jQuery)jQuery 對象，表示被作為占位符使用的元素。 **Code examples:** 使用指定的 update 回調的 sortable： ``` $( ".selector" ).sortable({ update: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 sortupdate 事件： ``` $( ".selector" ).on( "sortupdate", function( event, ui ) {} ); ``` ## Example: #### A simple jQuery UI Sortable. ``` <!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>sortable demo</title> <link rel="stylesheet" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css"> <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> <ul id="sortable"> <li>Item 1</li> <li>Item 2</li> <li>Item 3</li> <li>Item 4</li> <li>Item 5</li> </ul> <script>$("#sortable").sortable();</script> </body> </html> ```