jQuery UI API - 可排序小部件(Sortable Widget)
所屬類別
用法
描述:使用鼠標(biāo)調(diào)整列表中或者網(wǎng)格中元素的排序。
版本新增:1.0
依賴:
注釋:jQuery UI 可排序(Sortable)插件讓被選元素通過鼠標(biāo)拖拽進(jìn)行排序。
注釋:為了排序表格行,tbody
必須是可排序的(sortable),而不是 table
。
快速導(dǎo)航
選項(xiàng) | 方法 | 事件 |
---|---|---|
選項(xiàng) | 類型 | 描述 | 默認(rèn)值 |
---|---|---|---|
appendTo | jQuery 或 Element 或 Selector 或 String | 當(dāng)拖拽時,通過鼠標(biāo)移動的助手被追加到哪里(例如,解決 overlap/zIndex 問題)。 支持多個類型:
代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ appendTo: document.body }); 在初始化后,獲取或設(shè)置 // getter var appendTo = $( ".selector" ).sortable( "option", "appendTo" ); // setter $( ".selector" ).sortable( "option", "appendTo", document.body ); |
"parent" |
axis | String | 如果定義了該選項(xiàng),項(xiàng)目只能在水平或垂直方向上被拖拽??赡艿闹担?code>"x", "y" 。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ axis: "x" }); 在初始化后,獲取或設(shè)置 // getter var axis = $( ".selector" ).sortable( "option", "axis" ); // setter $( ".selector" ).sortable( "option", "axis", "x" ); |
false |
cancel | Selector | 防止從匹配選擇器的元素上開始排序。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ cancel: "a,button" }); 在初始化后,獲取或設(shè)置 // getter var cancel = $( ".selector" ).sortable( "option", "cancel" ); // setter $( ".selector" ).sortable( "option", "cancel", "a,button" ); |
"input, textarea, button, select, option" |
connectWith | Selector | 列表中的項(xiàng)目需被連接的其他 sortable 元素的選擇器。這是一個單向關(guān)系,如果您想要項(xiàng)目被雙向連接,必須在兩個 sortable 元素上都設(shè)置 connectWith 選項(xiàng)。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ connectWith: "#shopping-cart" }); 在初始化后,獲取或設(shè)置 // getter var connectWith = $( ".selector" ).sortable( "option", "connectWith" ); // setter $( ".selector" ).sortable( "option", "connectWith", "#shopping-cart" ); |
false |
containment | Element 或 Selector 或 String | 定義拖拽時,sortable 項(xiàng)目被約束的邊界。 注釋:為 containment 指定的元素必須有一個已計(jì)算的寬度和高度(盡管它不需要顯式)。例如,如果您有 支持多個類型:
代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ containment: "parent" }); 在初始化后,獲取或設(shè)置 // getter var containment = $( ".selector" ).sortable( "option", "containment" ); // setter $( ".selector" ).sortable( "option", "containment", "parent" ); |
false |
cursor | String | 定義當(dāng)排序時被顯示的光標(biāo)。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ cursor: "move" }); 在初始化后,獲取或設(shè)置 // getter var cursor = $( ".selector" ).sortable( "option", "cursor" ); // setter $( ".selector" ).sortable( "option", "cursor", "move" ); |
"auto" |
cursorAt | Object | 移動排序元素或助手(helper),這樣光標(biāo)總是出現(xiàn),以便從相同的位置進(jìn)行拖拽。坐標(biāo)可通過一個或兩個鍵的組合成一個哈希給出:{ top, left, right, bottom } 。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ cursorAt: { left: 5 } }); 在初始化后,獲取或設(shè)置 // getter var cursorAt = $( ".selector" ).sortable( "option", "cursorAt" ); // setter $( ".selector" ).sortable( "option", "cursorAt", { left: 5 } ); |
false |
delay | Integer | 鼠標(biāo)按下后直到排序開始的時間,以毫秒計(jì)。該選項(xiàng)可以防止點(diǎn)擊在某個元素上時不必要的拖拽。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ delay: 150 }); 在初始化后,獲取或設(shè)置 // getter var delay = $( ".selector" ).sortable( "option", "delay" ); // setter $( ".selector" ).sortable( "option", "delay", 150 ); |
0 |
disabled | Boolean | 如果設(shè)置為 true ,則禁用該 sortable。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ disabled: true }); 在初始化后,獲取或設(shè)置 // getter var disabled = $( ".selector" ).sortable( "option", "disabled" ); // setter $( ".selector" ).sortable( "option", "disabled", true ); |
false |
distance | Number | 鼠標(biāo)按下后排序開始前必須移動的距離,以像素計(jì)。如果指定了該選項(xiàng),排序只有在鼠標(biāo)拖拽超出指定距離時才會開始。該選項(xiàng)可以用于允許在一個手柄內(nèi)的元素上點(diǎn)擊。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ distance: 5 }); 在初始化后,獲取或設(shè)置 // getter var distance = $( ".selector" ).sortable( "option", "distance" ); // setter $( ".selector" ).sortable( "option", "distance", 5 ); |
1 |
dropOnEmpty | Boolean | 如果為 false ,從該 sortable 的項(xiàng)目不能被放置在空連接的 sortable 上(請查看 connectWith 選項(xiàng))。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ dropOnEmpty: false }); 在初始化后,獲取或設(shè)置 // getter var dropOnEmpty = $( ".selector" ).sortable( "option", "dropOnEmpty" ); // setter $( ".selector" ).sortable( "option", "dropOnEmpty", false ); |
true |
forceHelperSize | Boolean | 如果為 true ,強(qiáng)制助手(helper)有一個尺寸。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ forceHelperSize: true }); 在初始化后,獲取或設(shè)置 // getter var forceHelperSize = $( ".selector" ).sortable( "option", "forceHelperSize" ); // setter $( ".selector" ).sortable( "option", "forceHelperSize", true ); |
false |
forcePlaceholderSize | Boolean | 如果為 true ,強(qiáng)制占位符(placeholder)有一個尺寸。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ forcePlaceholderSize: true }); 在初始化后,獲取或設(shè)置 // getter var forcePlaceholderSize = $( ".selector" ).sortable( "option", "forcePlaceholderSize" ); // setter $( ".selector" ).sortable( "option", "forcePlaceholderSize", true ); |
false |
grid | Array | 對齊排序元素或助手(helper)到網(wǎng)格,每個 x 和 y 像素。數(shù)組形式必須是 [ x, y ] 。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ grid: [ 20, 10 ] }); 在初始化后,獲取或設(shè)置 // getter var grid = $( ".selector" ).sortable( "option", "grid" ); // setter $( ".selector" ).sortable( "option", "grid", [ 20, 10 ] ); |
false |
handle | Selector 或 Element | 如果指定了該選項(xiàng),則限制在指定的元素上開始排序。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ handle: ".handle" }); 在初始化后,獲取或設(shè)置 // getter var handle = $( ".selector" ).sortable( "option", "handle" ); // setter $( ".selector" ).sortable( "option", "handle", ".handle" ); |
false |
helper | String 或 Function() | 允許一個 helper 元素用于拖拽顯示。 支持多個類型:
代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ helper: "clone" }); 在初始化后,獲取或設(shè)置 // getter var helper = $( ".selector" ).sortable( "option", "helper" ); // setter $( ".selector" ).sortable( "option", "helper", "clone" ); |
"original" |
items | Selector | 指定元素內(nèi)的哪一個項(xiàng)目應(yīng)是 sortable。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ items: "> li" }); 在初始化后,獲取或設(shè)置 // getter var items = $( ".selector" ).sortable( "option", "items" ); // setter $( ".selector" ).sortable( "option", "items", "> li" ); |
"> *" |
opacity | Number | 當(dāng)排序時助手(helper)的不透明度。從 0.01 到 1 。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ opacity: 0.5 }); 在初始化后,獲取或設(shè)置 // getter var opacity = $( ".selector" ).sortable( "option", "opacity" ); // setter $( ".selector" ).sortable( "option", "opacity", 0.5 ); |
false |
placeholder | String | 要應(yīng)用的 class 名稱,否則為白色空白。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ placeholder: "sortable-placeholder" }); 在初始化后,獲取或設(shè)置 // getter var placeholder = $( ".selector" ).sortable( "option", "placeholder" ); // setter $( ".selector" ).sortable( "option", "placeholder", "sortable-placeholder" ); |
false |
revert | Boolean 或 Number | sortable 項(xiàng)目是否使用一個流暢的動畫還原到它的新位置。 支持多個類型:
代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ revert: true }); 在初始化后,獲取或設(shè)置 // getter var revert = $( ".selector" ).sortable( "option", "revert" ); // setter $( ".selector" ).sortable( "option", "revert", true ); |
false |
scroll | Boolean | 如果設(shè)置為 true ,當(dāng)?shù)竭_(dá)邊緣時頁面會滾動。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ scroll: false }); 在初始化后,獲取或設(shè)置 // getter var scroll = $( ".selector" ).sortable( "option", "scroll" ); // setter $( ".selector" ).sortable( "option", "scroll", false ); |
true |
scrollSensitivity | Number | 定義鼠標(biāo)距離邊緣多少距離時開始滾動。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ scrollSensitivity: 10 }); 在初始化后,獲取或設(shè)置 // getter var scrollSensitivity = $( ".selector" ).sortable( "option", "scrollSensitivity" ); // setter $( ".selector" ).sortable( "option", "scrollSensitivity", 10 ); |
20 |
scrollSpeed | Number | 當(dāng)鼠標(biāo)指針獲取到在 scrollSensitivity 距離內(nèi)時,窗體滾動的速度。如果 scroll 選項(xiàng)是 false 則忽略。代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ scrollSpeed: 40 }); 在初始化后,獲取或設(shè)置 // getter var scrollSpeed = $( ".selector" ).sortable( "option", "scrollSpeed" ); // setter $( ".selector" ).sortable( "option", "scrollSpeed", 40 ); |
20 |
tolerance | String | 指定用于測試項(xiàng)目被移動時是否覆蓋在另一個項(xiàng)目上的模式??赡艿闹担?br />
代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ tolerance: "pointer" }); 在初始化后,獲取或設(shè)置 // getter var tolerance = $( ".selector" ).sortable( "option", "tolerance" ); // setter $( ".selector" ).sortable( "option", "tolerance", "pointer" ); |
"intersect" |
zIndex | Integer | 當(dāng)被排序時,元素/助手(helper)的 Z-index。 代碼實(shí)例: 初始化帶有指定 $( ".selector" ).sortable({ zIndex: 9999 }); 在初始化后,獲取或設(shè)置 // getter var zIndex = $( ".selector" ).sortable( "option", "zIndex" ); // setter $( ".selector" ).sortable( "option", "zIndex", 9999 ); |
1000 |
方法 | 返回 | 描述 |
---|---|---|
cancel() | jQuery (plugin only) | 當(dāng)前排序開始時,取消一個在當(dāng)前 sortable 中的改變,且恢復(fù)到之前的狀態(tài)。在 stop 和 receive 回調(diào)函數(shù)中非常有用。
代碼實(shí)例: 調(diào)用 cancel 方法: $( ".selector" ).sortable( "cancel" ); |
destroy() | jQuery (plugin only) | 完全移除 sortable 功能。這會把元素返回到它的預(yù)初始化狀態(tài)。
代碼實(shí)例: 調(diào)用 destroy 方法: $( ".selector" ).sortable( "destroy" ); |
disable() | jQuery (plugin only) | 禁用 sortable。
代碼實(shí)例: 調(diào)用 disable 方法: $( ".selector" ).sortable( "disable" ); |
enable() | jQuery (plugin only) | 啟用 sortable。
代碼實(shí)例: 調(diào)用 enable 方法: $( ".selector" ).sortable( "enable" ); |
option( optionName ) | Object | 獲取當(dāng)前與指定的 optionName 關(guān)聯(lián)的值。
代碼實(shí)例: 調(diào)用該方法: var isDisabled = $( ".selector" ).sortable( "option", "disabled" ); |
option() | PlainObject | 獲取一個包含鍵/值對的對象,鍵/值對表示當(dāng)前 draggable 選項(xiàng)哈希。
代碼實(shí)例: 調(diào)用該方法: var options = $( ".selector" ).sortable( "option" ); |
option( optionName, value ) | jQuery (plugin only) | 設(shè)置與指定的 optionName 關(guān)聯(lián)的 sortable 選項(xiàng)的值。
代碼實(shí)例: 調(diào)用該方法: $( ".selector" ).sortable( "option", "disabled", true ); |
option( options ) | jQuery (plugin only) | 為 sortable 設(shè)置一個或多個選項(xiàng)。
代碼實(shí)例: 調(diào)用該方法: $( ".selector" ).sortable( "option", { disabled: true } ); |
refresh() | jQuery (plugin only) | 刷新 sortable 項(xiàng)目。觸發(fā)所有 sortable 項(xiàng)目重新加載,導(dǎo)致新的項(xiàng)目被認(rèn)可。
代碼實(shí)例: 調(diào)用 refresh 方法: $( ".selector" ).sortable( "refresh" ); |
refreshPositions() | jQuery (plugin only) | 刷新 sortable 項(xiàng)目的緩存位置。調(diào)用該方法刷新所有 sortable 的已緩存的項(xiàng)目位置。
代碼實(shí)例: 調(diào)用 refreshPositions 方法: $( ".selector" ).sortable( "refreshPositions" ); |
serialize( options ) | String | 序列化 sortable 的項(xiàng)目 id 為一個 form/ajax 可提交的字符串。調(diào)用該方法會產(chǎn)生一個可被追加到任何 url 中的哈希,以便簡單地把一個新的項(xiàng)目順序提交回服務(wù)器。默認(rèn)情況下,它通過每個項(xiàng)目的 注釋:如果序列化返回一個空的字符串,請確認(rèn)
代碼實(shí)例: 調(diào)用 serialize 方法: var sorted = $( ".selector" ).sortable( "serialize", { key: "sort" } ); |
toArray( options ) | Array | 序列化 sortable 的項(xiàng)目 id 為一個字符串的數(shù)組。
代碼實(shí)例: 調(diào)用 toArray 方法: var sortedIDs = $( ".selector" ).sortable( "toArray" ); |
widget() | jQuery | 返回一個包含 sortable 元素的 jQuery 對象。
代碼實(shí)例: 調(diào)用 widget 方法: var widget = $( ".selector" ).sortable( "widget" ); |
事件 | 類型 | 描述 |
---|---|---|
activate( event, ui ) | sortactivate | 當(dāng)使用被連接列表時觸發(fā)該事件,每個被連接列表在拖拽開始時接收它。
代碼實(shí)例: 初始化帶有指定 activate 回調(diào)的 sortable: $( ".selector" ).sortable({ activate: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortactivate 事件: $( ".selector" ).on( "sortactivate", function( event, ui ) {} ); |
beforeStop( event, ui ) | sortbeforestop | 當(dāng)排序停止時觸發(fā)該事件,除了當(dāng)占位符(placeholder)/助手(helper)仍然可用時。
代碼實(shí)例: 初始化帶有指定 beforeStop 回調(diào)的 sortable: $( ".selector" ).sortable({ beforeStop: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortbeforestop 事件: $( ".selector" ).on( "sortbeforestop", function( event, ui ) {} ); |
change( event, ui ) | sortchange | 在排序期間觸發(fā)該事件,除了當(dāng) DOM 位置改變時。
代碼實(shí)例: 初始化帶有指定 change 回調(diào)的 sortable: $( ".selector" ).sortable({ change: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortchange 事件: $( ".selector" ).on( "sortchange", function( event, ui ) {} ); |
create( event, ui ) | sortcreate | 當(dāng) droppable 被創(chuàng)建時觸發(fā)。
注意: 代碼實(shí)例: 初始化帶有指定 create 回調(diào)的 sortable: $( ".selector" ).sortable({ create: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortcreate 事件: $( ".selector" ).on( "sortcreate", function( event, ui ) {} ); |
deactivate( event, ui ) | sortdeactivate | 當(dāng)排序停止時觸發(fā)該事件,該事件傳播到所有可能的連接列表。。
代碼實(shí)例: 初始化帶有指定 deactivate 回調(diào)的 sortable: $( ".selector" ).sortable({ deactivate: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortdeactivate 事件: $( ".selector" ).on( "sortdeactivate", function( event, ui ) {} ); |
out( event, ui ) | sortout | 當(dāng)一個 sortable 項(xiàng)目從一個 sortable 列表移除時觸發(fā)該事件。 注釋:當(dāng)一個 sortable 項(xiàng)目被撤銷時也會觸發(fā)該事件。
代碼實(shí)例: 初始化帶有指定 out 回調(diào)的 sortable: $( ".selector" ).sortable({ out: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortout 事件: $( ".selector" ).on( "sortout", function( event, ui ) {} ); |
over( event, ui ) | sortover | 當(dāng)一個 sortable 項(xiàng)目移動到一個 sortable 列表時觸發(fā)該事件。
代碼實(shí)例: 初始化帶有指定 over 回調(diào)的 sortable: $( ".selector" ).sortable({ out: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortover 事件: $( ".selector" ).on( "sortout", function( event, ui ) {} ); |
receive( event, ui ) | sortreceive | 當(dāng)來自一個連接的 sortable 列表的一個項(xiàng)目被放置到另一個列表時觸發(fā)該事件。后者是事件目標(biāo)。
代碼實(shí)例: 初始化帶有指定 receive 回調(diào)的 sortable: $( ".selector" ).sortable({ receive: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortreceive 事件: $( ".selector" ).on( "sortreceive", function( event, ui ) {} ); |
remove( event, ui ) | sortremove | 當(dāng)來自一個連接的 sortable 列表的一個項(xiàng)目被放置到另一個列表時觸發(fā)該事件。前者是事件目標(biāo)。
代碼實(shí)例: 初始化帶有指定 remove 回調(diào)的 sortable: $( ".selector" ).sortable({ remove: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortremove 事件: $( ".selector" ).on( "sortremove", function( event, ui ) {} ); |
sort( event, ui ) | sort | 在排序期間觸發(fā)該事件。
代碼實(shí)例: 初始化帶有指定 sort 回調(diào)的 sortable: $( ".selector" ).sortable({ sort: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sort 事件: $( ".selector" ).on( "sort", function( event, ui ) {} ); |
start( event, ui ) | sortstart | 當(dāng)排序開始時觸發(fā)該事件。
代碼實(shí)例: 初始化帶有指定 start 回調(diào)的 sortable: $( ".selector" ).sortable({ start: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortstart 事件: $( ".selector" ).on( "sortstart", function( event, ui ) {} ); |
stop( event, ui ) | sortstop | 當(dāng)排序停止時觸發(fā)該事件。
代碼實(shí)例: 初始化帶有指定 stop 回調(diào)的 sortable: $( ".selector" ).sortable({ stop: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortstop 事件: $( ".selector" ).on( "sortstop", function( event, ui ) {} ); |
update( event, ui ) | sortupdate | 當(dāng)用戶停止排序且 DOM 位置改變時觸發(fā)該事件。
代碼實(shí)例: 初始化帶有指定 update 回調(diào)的 sortable: $( ".selector" ).sortable({ update: function( event, ui ) {} }); 綁定一個事件監(jiān)聽器到 sortupdate 事件: $( ".selector" ).on( "sortupdate", function( event, ui ) {} ); |
實(shí)例
一個簡單的 jQuery UI 可排序小部件(Sortable Widget)。
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>可排序小部件(Sortable Widget)演示</title> <link rel="stylesheet" rel="external nofollow" target="_blank" > <script src="http://code.jquery.com/jquery-1.10.2.js" rel="external nofollow" ></script> <script src="http://code.jquery.com/ui/1.10.4/jquery-ui.js" rel="external nofollow" ></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>
更多建議: