可排序小部件(Sortable Widget)
jQuery UI API - 可排序小部件(Sortable Widget)
所属类别
用法
描述:使用鼠标调整列表中或者网格中元素的排序。
版本新增:1.0
依赖:
注释:jQuery UI 可排序(Sortable)插件让被选元素通过鼠标拖拽进行排序。
注释:为了排序表格行,tbody必须是可排序的(sortable),而不是table。
快速导航
选项 | 方法 | 事件 |
---|---|---|
选项 | 类型 | 描述 | 默认值 |
---|---|---|---|
appendTo | jQuery 或 Element 或 Selector 或 String |
当拖拽时,通过鼠标移动的助手被追加到哪里(例如,解决 overlap/zIndex 问题)。 支持多个类型:
代码实例: 初始化带有指定appendTo选项的 sortable: $( ".selector" ).sortable({ appendTo: document.body }); 在初始化后,获取或设置appendTo选项: // getter var appendTo = $( ".selector" ).sortable( "option", "appendTo" ); // setter $( ".selector" ).sortable( "option", "appendTo", document.body ); |
"parent" |
axis | String |
如果定义了该选项,项目只能在水平或垂直方向上被拖拽。可能的值:"x","y"。 代码实例: 初始化带有指定axis选项的 sortable: $( ".selector" ).sortable({ axis: "x" }); 在初始化后,获取或设置axis选项: // getter var axis = $( ".selector" ).sortable( "option", "axis" ); // setter $( ".selector" ).sortable( "option", "axis", "x" ); |
false |
cancel | Selector |
防止从匹配选择器的元素上开始排序。 代码实例: 初始化带有指定cancel选项的 sortable: $( ".selector" ).sortable({ cancel: "a,button" }); 在初始化后,获取或设置cancel选项: // getter var cancel = $( ".selector" ).sortable( "option", "cancel" ); // setter $( ".selector" ).sortable( "option", "cancel", "a,button" ); |
"input, textarea, button, select, option" |
connectWith | Selector |
列表中的项目需被连接的其他 sortable 元素的选择器。这是一个单向关系,如果您想要项目被双向连接,必须在两个 sortable 元素上都设置connectWith选项。 代码实例: 初始化带有指定connectWith选项的 sortable: $( ".selector" ).sortable({ connectWith: "#shopping-cart" }); 在初始化后,获取或设置connectWith选项: // getter var connectWith = $( ".selector" ).sortable( "option", "connectWith" ); // setter $( ".selector" ).sortable( "option", "connectWith", "#shopping-cart" ); |
false |
containment | Element 或 Selector 或 String |
定义拖拽时,sortable 项目被约束的边界。 注释:为 containment 指定的元素必须有一个已计算的宽度和高度(尽管它不需要显式)。例如,如果您有float: leftsortable 子元素,并指定了containment: "parent",请确保在 sortable/parent 容器上有float: left,否则它将有height: 0,导致未定义的行为。 支持多个类型:
代码实例: 初始化带有指定containment选项的 sortable: $( ".selector" ).sortable({ containment: "parent" }); 在初始化后,获取或设置containment选项: // getter var containment = $( ".selector" ).sortable( "option", "containment" ); // setter $( ".selector" ).sortable( "option", "containment", "parent" ); |
false |
cursor | String |
定义当排序时被显示的光标。 代码实例: 初始化带有指定cursor选项的 sortable: $( ".selector" ).sortable({ cursor: "move" }); 在初始化后,获取或设置cursor选项: // getter var cursor = $( ".selector" ).sortable( "option", "cursor" ); // setter $( ".selector" ).sortable( "option", "cursor", "move" ); |
"auto" |
cursorAt | Object |
移动排序元素或助手(helper),这样光标总是出现,以便从相同的位置进行拖拽。坐标可通过一个或两个键的组合成一个哈希给出:{ top, left, right, bottom }。 代码实例: 初始化带有指定cursorAt选项的 sortable: $( ".selector" ).sortable({ cursorAt: { left: 5 } }); 在初始化后,获取或设置cursorAt选项: // getter var cursorAt = $( ".selector" ).sortable( "option", "cursorAt" ); // setter $( ".selector" ).sortable( "option", "cursorAt", { left: 5 } ); |
false |
delay | Integer |
鼠标按下后直到排序开始的时间,以毫秒计。该选项可以防止点击在某个元素上时不必要的拖拽。 代码实例: 初始化带有指定delay选项的 sortable: $( ".selector" ).sortable({ delay: 150 }); 在初始化后,获取或设置delay选项: // getter var delay = $( ".selector" ).sortable( "option", "delay" ); // setter $( ".selector" ).sortable( "option", "delay", 150 ); |
0 |
disabled | Boolean |
如果设置为true,则禁用该 sortable。 代码实例: 初始化带有指定disabled选项的 sortable: $( ".selector" ).sortable({ disabled: true }); 在初始化后,获取或设置disabled选项: // getter var disabled = $( ".selector" ).sortable( "option", "disabled" ); // setter $( ".selector" ).sortable( "option", "disabled", true ); |
false |
distance | Number |
鼠标按下后排序开始前必须移动的距离,以像素计。如果指定了该选项,排序只有在鼠标拖拽超出指定距离时才会开始。该选项可以用于允许在一个手柄内的元素上点击。 代码实例: 初始化带有指定distance选项的 sortable: $( ".selector" ).sortable({ distance: 5 }); 在初始化后,获取或设置distance选项: // getter var distance = $( ".selector" ).sortable( "option", "distance" ); // setter $( ".selector" ).sortable( "option", "distance", 5 ); |
1 |
dropOnEmpty | Boolean |
如果为false,从该 sortable 的项目不能被放置在空连接的 sortable 上(请查看connectWith选项)。 代码实例: 初始化带有指定dropOnEmpty选项的 sortable: $( ".selector" ).sortable({ dropOnEmpty: false }); 在初始化后,获取或设置dropOnEmpty选项: // getter var dropOnEmpty = $( ".selector" ).sortable( "option", "dropOnEmpty" ); // setter $( ".selector" ).sortable( "option", "dropOnEmpty", false ); |
true |
forceHelperSize | Boolean |
如果为true,强制助手(helper)有一个尺寸。 代码实例: 初始化带有指定forceHelperSize选项的 sortable: $( ".selector" ).sortable({ forceHelperSize: true }); 在初始化后,获取或设置forceHelperSize选项: // getter var forceHelperSize = $( ".selector" ).sortable( "option", "forceHelperSize" ); // setter $( ".selector" ).sortable( "option", "forceHelperSize", true ); |
false |
forcePlaceholderSize | Boolean |
如果为true,强制占位符(placeholder)有一个尺寸。 代码实例: 初始化带有指定forcePlaceholderSize选项的 sortable: $( ".selector" ).sortable({ forcePlaceholderSize: true }); 在初始化后,获取或设置forcePlaceholderSize选项: // getter var forcePlaceholderSize = $( ".selector" ).sortable( "option", "forcePlaceholderSize" ); // setter $( ".selector" ).sortable( "option", "forcePlaceholderSize", true ); |
false |
grid | Array |
对齐排序元素或助手(helper)到网格,每个 x 和 y 像素。数组形式必须是[ x, y ]。 代码实例: 初始化带有指定grid选项的 sortable: $( ".selector" ).sortable({ grid: [ 20, 10 ] }); 在初始化后,获取或设置grid选项: // getter var grid = $( ".selector" ).sortable( "option", "grid" ); // setter $( ".selector" ).sortable( "option", "grid", [ 20, 10 ] ); |
false |
handle | Selector 或 Element |
如果指定了该选项,则限制在指定的元素上开始排序。 代码实例: 初始化带有指定handle选项的 sortable: $( ".selector" ).sortable({ handle: ".handle" }); 在初始化后,获取或设置handle选项: // getter var handle = $( ".selector" ).sortable( "option", "handle" ); // setter $( ".selector" ).sortable( "option", "handle", ".handle" ); |
false |
helper | String 或 Function() |
允许一个 helper 元素用于拖拽显示。 支持多个类型:
代码实例: 初始化带有指定helper选项的 sortable: $( ".selector" ).sortable({ helper: "clone" }); 在初始化后,获取或设置helper选项: // getter var helper = $( ".selector" ).sortable( "option", "helper" ); // setter $( ".selector" ).sortable( "option", "helper", "clone" ); |
"original" |
items | Selector |
指定元素内的哪一个项目应是 sortable。 代码实例: 初始化带有指定items选项的 sortable: $( ".selector" ).sortable({ items: "> li" }); 在初始化后,获取或设置items选项: // getter var items = $( ".selector" ).sortable( "option", "items" ); // setter $( ".selector" ).sortable( "option", "items", "> li" ); |
"> *" |
opacity | Number |
当排序时助手(helper)的不透明度。从0.01到1。 代码实例: 初始化带有指定opacity选项的 sortable: $( ".selector" ).sortable({ opacity: 0.5 }); 在初始化后,获取或设置opacity选项: // getter var opacity = $( ".selector" ).sortable( "option", "opacity" ); // setter $( ".selector" ).sortable( "option", "opacity", 0.5 ); |
false |
placeholder | String |
要应用的 class 名称,否则为白色空白。 代码实例: 初始化带有指定placeholder选项的 sortable: $( ".selector" ).sortable({ placeholder: "sortable-placeholder" }); 在初始化后,获取或设置placeholder选项: // getter var placeholder = $( ".selector" ).sortable( "option", "placeholder" ); // setter $( ".selector" ).sortable( "option", "placeholder", "sortable-placeholder" ); |
false |
revert | Boolean 或 Number |
sortable 项目是否使用一个流畅的动画还原到它的新位置。 支持多个类型:
代码实例: 初始化带有指定revert选项的 sortable: $( ".selector" ).sortable({ revert: true }); 在初始化后,获取或设置revert选项: // getter var revert = $( ".selector" ).sortable( "option", "revert" ); // setter $( ".selector" ).sortable( "option", "revert", true ); |
false |
scroll | Boolean |
如果设置为true,当到达边缘时页面会滚动。 代码实例: 初始化带有指定scroll选项的 sortable: $( ".selector" ).sortable({ scroll: false }); 在初始化后,获取或设置scroll选项: // getter var scroll = $( ".selector" ).sortable( "option", "scroll" ); // setter $( ".selector" ).sortable( "option", "scroll", false ); |
true |
scrollSensitivity | Number |
定义鼠标距离边缘多少距离时开始滚动。 代码实例: 初始化带有指定scrollSensitivity选项的 sortable: $( ".selector" ).sortable({ scrollSensitivity: 10 }); 在初始化后,获取或设置scrollSensitivity选项: // getter var scrollSensitivity = $( ".selector" ).sortable( "option", "scrollSensitivity" ); // setter $( ".selector" ).sortable( "option", "scrollSensitivity", 10 ); |
20 |
scrollSpeed | Number |
当鼠标指针获取到在scrollSensitivity距离内时,窗体滚动的速度。如果scroll选项是false则忽略。 代码实例: 初始化带有指定scrollSpeed选项的 sortable: $( ".selector" ).sortable({ scrollSpeed: 40 }); 在初始化后,获取或设置scrollSpeed选项: // getter var scrollSpeed = $( ".selector" ).sortable( "option", "scrollSpeed" ); // setter $( ".selector" ).sortable( "option", "scrollSpeed", 40 ); |
20 |
tolerance | String |
指定用于测试项目被移动时是否覆盖在另一个项目上的模式。可能的值:
代码实例: 初始化带有指定tolerance选项的 sortable: $( ".selector" ).sortable({ tolerance: "pointer" }); 在初始化后,获取或设置tolerance选项: // getter var tolerance = $( ".selector" ).sortable( "option", "tolerance" ); // setter $( ".selector" ).sortable( "option", "tolerance", "pointer" ); |
"intersect" |
zIndex | Integer |
当被排序时,元素/助手(helper)的 Z-index。 代码实例: 初始化带有指定zIndex选项的 sortable: $( ".selector" ).sortable({ zIndex: 9999 }); 在初始化后,获取或设置zIndex选项: // getter var zIndex = $( ".selector" ).sortable( "option", "zIndex" ); // setter $( ".selector" ).sortable( "option", "zIndex", 9999 ); |
1000 |
方法 | 返回 | 描述 |
---|---|---|
cancel() | jQuery (plugin only) |
当前排序开始时,取消一个在当前 sortable 中的改变,且恢复到之前的状态。在 stop 和 receive 回调函数中非常有用。
代码实例: 调用 cancel 方法: $( ".selector" ).sortable( "cancel" ); |
destroy() | jQuery (plugin only) |
完全移除 sortable 功能。这会把元素返回到它的预初始化状态。
代码实例: 调用 destroy 方法: $( ".selector" ).sortable( "destroy" ); |
disable() | jQuery (plugin only) |
禁用 sortable。
代码实例: 调用 disable 方法: $( ".selector" ).sortable( "disable" ); |
enable() | jQuery (plugin only) |
启用 sortable。
代码实例: 调用 enable 方法: $( ".selector" ).sortable( "enable" ); |
option( optionName ) | Object |
获取当前与指定的optionName关联的值。
代码实例: 调用该方法: var isDisabled = $( ".selector" ).sortable( "option", "disabled" ); |
option() | PlainObject |
获取一个包含键/值对的对象,键/值对表示当前 draggable 选项哈希。
代码实例: 调用该方法: var options = $( ".selector" ).sortable( "option" ); |
option( optionName, value ) | jQuery (plugin only) |
设置与指定的optionName关联的 sortable 选项的值。
代码实例: 调用该方法: $( ".selector" ).sortable( "option", "disabled", true ); |
option( options ) | jQuery (plugin only) |
为 sortable 设置一个或多个选项。
代码实例: 调用该方法: $( ".selector" ).sortable( "option", { disabled: true } ); |
refresh() | jQuery (plugin only) |
刷新 sortable 项目。触发所有 sortable 项目重新加载,导致新的项目被认可。
代码实例: 调用 refresh 方法: $( ".selector" ).sortable( "refresh" ); |
refreshPositions() | jQuery (plugin only) |
刷新 sortable 项目的缓存位置。调用该方法刷新所有 sortable 的已缓存的项目位置。
代码实例: 调用 refreshPositions 方法: $( ".selector" ).sortable( "refreshPositions" ); |
serialize( options ) | 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"。
代码实例: 调用 serialize 方法: var sorted = $( ".selector" ).sortable( "serialize", { key: "sort" } ); |
toArray( options ) | Array |
序列化 sortable 的项目id为一个字符串的数组。
代码实例: 调用 toArray 方法: var sortedIDs = $( ".selector" ).sortable( "toArray" ); |
widget() | jQuery |
返回一个包含 sortable 元素的jQuery对象。
代码实例: 调用 widget 方法: var widget = $( ".selector" ).sortable( "widget" ); |
事件 | 类型 | 描述 |
---|---|---|
activate( event, ui ) | sortactivate |
当使用被连接列表时触发该事件,每个被连接列表在拖拽开始时接收它。
代码实例: 初始化带有指定 activate 回调的 sortable: $( ".selector" ).sortable({ activate: function( event, ui ) {} }); 绑定一个事件监听器到 sortactivate 事件: $( ".selector" ).on( "sortactivate", function( event, ui ) {} ); |
beforeStop( event, ui ) | sortbeforestop |
当排序停止时触发该事件,除了当占位符(placeholder)/助手(helper)仍然可用时。
代码实例: 初始化带有指定 beforeStop 回调的 sortable: $( ".selector" ).sortable({ beforeStop: function( event, ui ) {} }); 绑定一个事件监听器到 sortbeforestop 事件: $( ".selector" ).on( "sortbeforestop", function( event, ui ) {} ); |
change( event, ui ) | sortchange |
在排序期间触发该事件,除了当 DOM 位置改变时。
代码实例: 初始化带有指定 change 回调的 sortable: $( ".selector" ).sortable({ change: function( event, ui ) {} }); 绑定一个事件监听器到 sortchange 事件: $( ".selector" ).on( "sortchange", function( event, ui ) {} ); |
create( event, ui ) | sortcreate |
当 droppable 被创建时触发。
注意:ui对象是空的,这里包含它是为了与其他事件保持一致性。 代码实例: 初始化带有指定 create 回调的 sortable: $( ".selector" ).sortable({ create: function( event, ui ) {} }); 绑定一个事件监听器到 sortcreate 事件: $( ".selector" ).on( "sortcreate", function( event, ui ) {} ); |
deactivate( event, ui ) | sortdeactivate |
当排序停止时触发该事件,该事件传播到所有可能的连接列表。。
代码实例: 初始化带有指定 deactivate 回调的 sortable: $( ".selector" ).sortable({ deactivate: function( event, ui ) {} }); 绑定一个事件监听器到 sortdeactivate 事件: $( ".selector" ).on( "sortdeactivate", function( event, ui ) {} ); |
out( event, ui ) | sortout |
当一个 sortable 项目从一个 sortable 列表移除时触发该事件。 注释:当一个 sortable 项目被撤销时也会触发该事件。
代码实例: 初始化带有指定 out 回调的 sortable: $( ".selector" ).sortable({ out: function( event, ui ) {} }); 绑定一个事件监听器到 sortout 事件: $( ".selector" ).on( "sortout", function( event, ui ) {} ); |
over( event, ui ) | sortover |
当一个 sortable 项目移动到一个 sortable 列表时触发该事件。
代码实例: 初始化带有指定 over 回调的 sortable: $( ".selector" ).sortable({ out: function( event, ui ) {} }); 绑定一个事件监听器到 sortover 事件: $( ".selector" ).on( "sortout", function( event, ui ) {} ); |
receive( event, ui ) | sortreceive |
当来自一个连接的 sortable 列表的一个项目被放置到另一个列表时触发该事件。后者是事件目标。
代码实例: 初始化带有指定 receive 回调的 sortable: $( ".selector" ).sortable({ receive: function( event, ui ) {} }); 绑定一个事件监听器到 sortreceive 事件: $( ".selector" ).on( "sortreceive", function( event, ui ) {} ); |
remove( event, ui ) | sortremove |
当来自一个连接的 sortable 列表的一个项目被放置到另一个列表时触发该事件。前者是事件目标。
代码实例: 初始化带有指定 remove 回调的 sortable: $( ".selector" ).sortable({ remove: function( event, ui ) {} }); 绑定一个事件监听器到 sortremove 事件: $( ".selector" ).on( "sortremove", function( event, ui ) {} ); |
sort( event, ui ) | sort |
在排序期间触发该事件。
代码实例: 初始化带有指定 sort 回调的 sortable: $( ".selector" ).sortable({ sort: function( event, ui ) {} }); 绑定一个事件监听器到 sort 事件: $( ".selector" ).on( "sort", function( event, ui ) {} ); |
start( event, ui ) | sortstart |
当排序开始时触发该事件。
代码实例: 初始化带有指定 start 回调的 sortable: $( ".selector" ).sortable({ start: function( event, ui ) {} }); 绑定一个事件监听器到 sortstart 事件: $( ".selector" ).on( "sortstart", function( event, ui ) {} ); |
stop( event, ui ) | sortstop |
当排序停止时触发该事件。
代码实例: 初始化带有指定 stop 回调的 sortable: $( ".selector" ).sortable({ stop: function( event, ui ) {} }); 绑定一个事件监听器到 sortstop 事件: $( ".selector" ).on( "sortstop", function( event, ui ) {} ); |
update( event, ui ) | sortupdate |
当用户停止排序且 DOM 位置改变时触发该事件。
代码实例: 初始化带有指定 update 回调的 sortable: $( ".selector" ).sortable({ update: function( event, ui ) {} }); 绑定一个事件监听器到 sortupdate 事件: $( ".selector" ).on( "sortupdate", function( event, ui ) {} ); |
实例
一个简单的 jQuery UI 可排序小部件(Sortable Widget)。
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <title>可排序小部件(Sortable Widget)演示</title> <link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css"> <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> <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>