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