Sortable Widget · jQuery UI API 中文文档

# Sortable Widget # 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> ```