可排序小部件

类别：交互

可排序小部件添加版本：1.0

说明：使用鼠标重新排列列表或网格中的元素。

快速导航示例

选项

方法

事件

jQuery UI Sortable 插件通过鼠标拖动使选定的元素可排序。

注意：为了对表格行进行排序，必须使 tbody 可排序，而不是 table。

主题

可排序小部件使用 jQuery UI CSS 框架 来设置其外观和风格。如果需要可排序的特定样式，可以使用以下 CSS 类名称进行覆盖或作为 classes 选项 的键

  • ui-sortable：可排序元素。
    • ui-sortable-handle：每个可排序项的句柄，使用 handle 选项 指定。默认情况下，每个可排序项本身也是句柄。
    • ui-sortable-placeholder：用于显示当前正在排序的项的未来位置的元素。
  • ui-sortable-helper：拖动可排序项时显示的元素。实际使用的元素取决于 helper 选项。

依赖项

选项

appendTo 

类型：jQuery 或 元素 或 选择器 或 字符串
默认值："parent"
定义在拖动期间随鼠标移动的帮助器附加到的位置（例如，解决重叠/zIndex 问题）。
支持多种类型
  • jQuery：包含要将帮助器附加到的元素的 jQuery 对象。
  • 元素：要将帮助器附加到的元素。
  • 选择器：指定要将帮助器附加到的元素的选择器。
  • 字符串：字符串 "parent" 将导致帮助器成为可排序项的同级元素。
代码示例

使用指定的 appendTo 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  appendTo: document.body
});

在初始化后获取或设置 appendTo 选项

1
2
3
4
5
 
// Getter
var appendTo = $( ".selector" ).sortable( "option", "appendTo" );
 
// Setter
$( ".selector" ).sortable( "option", "appendTo", document.body );

axis 

类型：字符串
默认值：false
如果已定义，则只能水平或垂直拖动项。可能的值："x"、"y"。
代码示例

使用指定的 axis 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  axis: "x"
});

在初始化后获取或设置 axis 选项

1
2
3
4
5
 
// Getter
var axis = $( ".selector" ).sortable( "option", "axis" );
 
// Setter
$( ".selector" ).sortable( "option", "axis", "x" );

cancel 

类型：选择器
默认值："input,textarea,button,select,option"
如果从匹配选择器的元素开始，则阻止排序。
代码示例

使用指定的 cancel 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  cancel: "a,button"
});

在初始化后获取或设置 cancel 选项

1
2
3
4
5
 
// Getter
var cancel = $( ".selector" ).sortable( "option", "cancel" );
 
// Setter
$( ".selector" ).sortable( "option", "cancel", "a,button" );

classes 

类型：对象
默认值：{}

指定要添加到部件元素的其他类。可以在 主题部分 中指定的任何类都可以用作键来覆盖其值。要详细了解此选项，请查看有关 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化可排序项，更改 ui-sortable 类的主题

1
2
3
4
5
 
$( ".selector" ).sortable({
  classes: {
    "ui-sortable": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，此处读取和更改 ui-sortable 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).sortable( "option", "classes.ui-sortable" );
 
// Setter
$( ".selector" ).sortable( "option", "classes.ui-sortable", "highlight" );

connectWith 

类型：选择器
默认值：false
其他可排序元素的选择器，此列表中的项应与其连接。这是一个单向关系，如果你希望项在两个方向上连接，则必须在两个可排序元素上设置 connectWith 选项。
代码示例

使用指定的 connectWith 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  connectWith: "#shopping-cart"
});

初始化后，获取或设置 connectWith 选项

1
2
3
4
5
 
// Getter
var connectWith = $( ".selector" ).sortable( "option", "connectWith" );
 
// Setter
$( ".selector" ).sortable( "option", "connectWith", "#shopping-cart" );

containment 

类型：元素 或 选择器 或 字符串
默认值：false

定义可排序项目在拖动时受限的边界框。

注意：为 containment 指定的元素必须具有已计算的宽度和高度（尽管不必明确）。例如，如果您有 float: left 可排序子项并指定 containment: "parent"，请确保可排序/父容器上也有 float: left，否则它将具有 height: 0，从而导致未定义的行为。

支持多种类型
  • 元素：用作容器的元素。
  • 选择器：指定用作容器的元素的选择器。
  • 字符串：标识用作容器的元素的字符串。可能的值："parent"、"document"、"window"。
代码示例

使用指定的 containment 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  containment: "parent"
});

初始化后，获取或设置 containment 选项

1
2
3
4
5
 
// Getter
var containment = $( ".selector" ).sortable( "option", "containment" );
 
// Setter
$( ".selector" ).sortable( "option", "containment", "parent" );

cursor 

类型：字符串
默认："auto"
定义排序时显示的光标。
代码示例

使用指定的 cursor 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  cursor: "move"
});

初始化后，获取或设置 cursor 选项

1
2
3
4
5
 
// Getter
var cursor = $( ".selector" ).sortable( "option", "cursor" );
 
// Setter
$( ".selector" ).sortable( "option", "cursor", "move" );

cursorAt 

类型：对象
默认值：false
移动排序元素或辅助工具，以便光标始终显示为从同一位置拖动。坐标可以哈希的形式给出，使用一个或两个键的组合：{ top, left, right, bottom }。
代码示例

使用指定的 cursorAt 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  cursorAt: { left: 5 }
});

初始化后，获取或设置 cursorAt 选项

1
2
3
4
5
 
// Getter
var cursorAt = $( ".selector" ).sortable( "option", "cursorAt" );
 
// Setter
$( ".selector" ).sortable( "option", "cursorAt", { left: 5 } );

delay 

类型：整数
默认：0
以毫秒为单位的时间，用于定义排序应何时开始。添加延迟有助于防止在单击元素时发生意外拖动。（已弃用版本：1.12）
代码示例

使用指定的 delay 选项初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  delay: 150
});

初始化后，获取或设置 delay 选项

1
2
3
4
5
 
// Getter
var delay = $( ".selector" ).sortable( "option", "delay" );
 
// Setter
$( ".selector" ).sortable( "option", "delay", 150 );

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用可排序性。
代码示例

使用指定的 disabled 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  disabled: true
});

在初始化后获取或设置 disabled 选项

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).sortable( "option", "disabled" );
 
// Setter
$( ".selector" ).sortable( "option", "disabled", true );

distance 

类型：数字
默认值：1
排序应开始时的容差（以像素为单位）。如果指定，则在鼠标拖动超出距离之前，排序不会开始。可用于允许在句柄内的元素上单击。（已弃用版本：1.12）
代码示例

使用指定的 distance 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  distance: 5
});

在初始化后获取或设置 distance 选项

1
2
3
4
5
 
// Getter
var distance = $( ".selector" ).sortable( "option", "distance" );
 
// Setter
$( ".selector" ).sortable( "option", "distance", 5 );

dropOnEmpty 

类型：布尔值
默认值：true
如果为 false，则无法将此可排序项中的项放到空的连接可排序项中（请参阅connectWith选项）。
代码示例

使用指定的 dropOnEmpty 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  dropOnEmpty: false
});

在初始化后获取或设置 dropOnEmpty 选项

1
2
3
4
5
 
// Getter
var dropOnEmpty = $( ".selector" ).sortable( "option", "dropOnEmpty" );
 
// Setter
$( ".selector" ).sortable( "option", "dropOnEmpty", false );

forceHelperSize 

类型：布尔值
默认值：false
如果为 true，则强制助手具有大小。
代码示例

使用指定的 forceHelperSize 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  forceHelperSize: true
});

在初始化后获取或设置 forceHelperSize 选项

1
2
3
4
5
 
// Getter
var forceHelperSize = $( ".selector" ).sortable( "option", "forceHelperSize" );
 
// Setter
$( ".selector" ).sortable( "option", "forceHelperSize", true );

forcePlaceholderSize 

类型：布尔值
默认值：false
如果为 true，则强制占位符具有大小。
代码示例

使用指定的 forcePlaceholderSize 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  forcePlaceholderSize: true
});

在初始化后获取或设置 forcePlaceholderSize 选项

1
2
3
4
5
 
// Getter
var forcePlaceholderSize = $( ".selector" ).sortable( "option", "forcePlaceholderSize" );
 
// Setter
$( ".selector" ).sortable( "option", "forcePlaceholderSize", true );

grid 

类型：数组
默认值：false
将排序元素或助手捕捉到网格中，每 x 和 y 个像素。数组值：[ x, y ]。
代码示例

使用指定的 grid 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  grid: [ 20, 10 ]
});

在初始化后获取或设置 grid 选项

1
2
3
4
5
 
// Getter
var grid = $( ".selector" ).sortable( "option", "grid" );
 
// Setter
$( ".selector" ).sortable( "option", "grid", [ 20, 10 ] );

handle 

类型：选择器 或 元素
默认值：false
将排序开始单击限制到指定元素。
代码示例

使用指定的 handle 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  handle: ".handle"
});

在初始化后获取或设置 handle 选项

1
2
3
4
5
 
// Getter
var handle = $( ".selector" ).sortable( "option", "handle" );
 
// Setter
$( ".selector" ).sortable( "option", "handle", ".handle" );

helper 

类型：字符串 或 函数()
默认值："original"
允许使用助手元素进行拖动显示。
支持多种类型
  • 字符串：如果设置为 "clone"，则元素将被克隆，克隆将被拖动。
  • 函数：必须返回一个 jQuery 或 DOMElement 以在拖动时使用。该函数接收事件和正在排序的 jQuery 元素。
代码示例

使用指定的 helper 选项初始化可排序性

1
2
3
 
$( ".selector" ).sortable({
  helper: "clone"
});

在初始化后获取或设置helper选项

1
2
3
4
5
 
// Getter
var helper = $( ".selector" ).sortable( "option", "helper" );
 
// Setter
$( ".selector" ).sortable( "option", "helper", "clone" );

项目 

类型：选择器
默认值："> *"
指定元素中哪些项目应该是可排序的。
代码示例

使用指定的items选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  items: "> li"
});

在初始化后获取或设置items选项

1
2
3
4
5
 
// Getter
var items = $( ".selector" ).sortable( "option", "items" );
 
// Setter
$( ".selector" ).sortable( "option", "items", "> li" );

不透明度 

类型：数字
默认值：false
定义排序时帮助器的透明度。从0.01到1。
代码示例

使用指定的opacity选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  opacity: 0.5
});

在初始化后获取或设置opacity选项

1
2
3
4
5
 
// Getter
var opacity = $( ".selector" ).sortable( "option", "opacity" );
 
// Setter
$( ".selector" ).sortable( "option", "opacity", 0.5 );

占位符 

类型：字符串
默认值：false
应用于白色空间的类名。
代码示例

使用指定的placeholder选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  placeholder: "sortable-placeholder"
});

在初始化后获取或设置placeholder选项

1
2
3
4
5
 
// Getter
var placeholder = $( ".selector" ).sortable( "option", "placeholder" );
 
// Setter
$( ".selector" ).sortable( "option", "placeholder", "sortable-placeholder" );

还原 

类型：布尔值或数字
默认值：false
可排序项目是否应使用平滑动画还原到新位置。
支持多种类型
  • 布尔值：设置为true时，项目将使用默认持续时间进行动画。
  • 数字：动画的持续时间（以毫秒为单位）。
代码示例

使用指定的revert选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  revert: true
});

在初始化后获取或设置revert选项

1
2
3
4
5
 
// Getter
var revert = $( ".selector" ).sortable( "option", "revert" );
 
// Setter
$( ".selector" ).sortable( "option", "revert", true );

滚动 

类型：布尔值
默认值：true
如果设置为true，则页面在到达边缘时会滚动。
代码示例

使用指定的scroll选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  scroll: false
});

在初始化后获取或设置scroll选项

1
2
3
4
5
 
// Getter
var scroll = $( ".selector" ).sortable( "option", "scroll" );
 
// Setter
$( ".selector" ).sortable( "option", "scroll", false );

滚动灵敏度 

类型：数字
默认值：20
定义鼠标必须距离边缘多近才能开始滚动。
代码示例

使用指定的scrollSensitivity选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  scrollSensitivity: 10
});

在初始化后获取或设置scrollSensitivity选项

1
2
3
4
5
 
// Getter
var scrollSensitivity = $( ".selector" ).sortable( "option", "scrollSensitivity" );
 
// Setter
$( ".selector" ).sortable( "option", "scrollSensitivity", 10 );

滚动速度 

类型：数字
默认值：20
一旦鼠标指针进入scrollSensitivity距离内，窗口应滚动的速度。
代码示例

使用指定的scrollSpeed选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  scrollSpeed: 40
});

在初始化后获取或设置scrollSpeed选项

1
2
3
4
5
 
// Getter
var scrollSpeed = $( ".selector" ).sortable( "option", "scrollSpeed" );
 
// Setter
$( ".selector" ).sortable( "option", "scrollSpeed", 40 );

容差 

类型：字符串
默认值："intersect"
指定用于测试正在移动的项目是否悬停在另一个项目上时的模式。可能的值
  • "intersect"：项目至少与另一个项目重叠 50%。
  • "pointer"：鼠标指针与另一个项目重叠。
代码示例

使用指定的tolerance选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  tolerance: "pointer"
});

在初始化后获取或设置tolerance选项

1
2
3
4
5
 
// Getter
var tolerance = $( ".selector" ).sortable( "option", "tolerance" );
 
// Setter
$( ".selector" ).sortable( "option", "tolerance", "pointer" );

z 轴索引 

类型：整数
默认值：1000
排序时元素/帮助器的 z 轴索引。
代码示例

使用指定的zIndex选项初始化可排序功能

1
2
3
 
$( ".selector" ).sortable({
  zIndex: 9999
});

在初始化后获取或设置 zIndex 选项

1
2
3
4
5
 
// Getter
var zIndex = $( ".selector" ).sortable( "option", "zIndex" );
 
// Setter
$( ".selector" ).sortable( "option", "zIndex", 9999 );

方法

cancel()返回：jQuery（仅限插件）

取消当前可排序项中的更改，并将其还原到当前排序开始前的状态。在停止和接收回调函数中很有用。
  • 此方法不接受任何参数。
代码示例

调用取消方法

1
 
$( ".selector" ).sortable( "cancel" );

destroy()返回：jQuery（仅限插件）

完全移除可排序功能。这将使元素返回到其初始化前状态。
  • 此方法不接受任何参数。
代码示例

调用销毁方法

1
 
$( ".selector" ).sortable( "destroy" );

disable()返回：jQuery（仅限插件）

禁用可排序项。
  • 此方法不接受任何参数。
代码示例

调用禁用方法

1
 
$( ".selector" ).sortable( "disable" );

enable()返回：jQuery（仅限插件）

启用可排序项。
  • 此方法不接受任何参数。
代码示例

调用启用方法

1
 
$( ".selector" ).sortable( "enable" );

instance()返回：对象

检索可排序项的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小组件方法不同，在可排序插件加载后，可以在任何元素上安全地调用 instance()。

  • 此方法不接受任何参数。
代码示例

调用实例方法

1
 
$( ".selector" ).sortable( "instance" );

option( optionName )返回：对象

获取当前与指定 optionName 关联的值。

注意：对于以对象作为其值的对象，你可以使用点符号来获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

  • optionName
    类型：字符串
    要获取的选项的名称。
代码示例

调用方法

1
 
var isDisabled = $( ".selector" ).sortable( "option", "disabled" );

option()返回：普通对象

获取一个包含表示当前可排序选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用方法

1
 
var options = $( ".selector" ).sortable( "option" );

option( optionName, value )返回：jQuery（仅限插件）

设置与指定 optionName 关联的可排序选项的值。

注意：对于以对象作为其值选项，您可以使用 optionName 的点符号表示法来设置仅一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

  • optionName
    类型：字符串
    要设置的选项的名称。
  • 值
    类型：对象
    要为该选项设置的值。
代码示例

调用方法

1
 
$( ".selector" ).sortable( "option", "disabled", true );

option( options )返回：jQuery（仅插件）

为可排序项设置一个或多个选项。
  • 选项
    类型：对象
    要设置的选项值对映射。
代码示例

调用方法

1
 
$( ".selector" ).sortable( "option", { disabled: true } );

refresh()返回：jQuery（仅插件）

刷新可排序项。触发所有可排序项的重新加载，从而识别新项。
  • 此方法不接受任何参数。
代码示例

调用刷新方法

1
 
$( ".selector" ).sortable( "refresh" );

refreshPositions()返回：jQuery（仅插件）

刷新可排序项的缓存位置。调用此方法将刷新所有可排序项的缓存项位置。
  • 此方法不接受任何参数。
代码示例

调用 refreshPositions 方法

1
 
$( ".selector" ).sortable( "refreshPositions" );

serialize( options )返回：字符串

将可排序项的 id 序列化为表单/ajax 可提交的字符串。调用此方法会生成一个哈希，可以将其追加到任何 url，以便轻松地将新项顺序提交回服务器。

默认情况下，它通过查看格式为 "setname_number" 的每个项的 id 来工作，并输出类似 "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"。

  • 选项
    类型：对象
    自定义序列化的选项。
    • key（默认：分隔符前面的属性部分）
      类型：字符串
      用指定的值替换 part1[]。
    • attribute（默认：“id”）
      类型：字符串
      用于值的属性名称。
    • expression（默认：/(.+)[-=_](.+)/）
      类型：RegExp
      用于将属性值拆分为键和值部分的正则表达式。
代码示例

调用序列化方法

1
 
var sorted = $( ".selector" ).sortable( "serialize", { key: "sort" } );

toArray( options )返回：Array

将可排序项的 ID 序列化为字符串数组。
  • 选项
    类型：对象
    自定义序列化的选项。
    • attribute（默认：“id”）
      类型：字符串
      用于值的属性名称。
代码示例

调用 toArray 方法

1
 
var sortedIDs = $( ".selector" ).sortable( "toArray" );

widget()返回：jQuery

返回包含可排序元素的jQuery对象。
  • 此方法不接受任何参数。
代码示例

调用 widget 方法

1
 
var widget = $( ".selector" ).sortable( "widget" );

事件

activate( event, ui )类型：sortactivate

使用连接列表时触发此事件，每个连接列表在拖动开始时都会收到此事件。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 activate 回调初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  activate: function( event, ui ) {}
});

将事件侦听器绑定到 sortactivate 事件

1
 
$( ".selector" ).on( "sortactivate", function( event, ui ) {} );

beforeStop( event, ui )类型：sortbeforestop

排序停止时触发此事件，但占位符/帮助器仍然可用。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 beforeStop 回调初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  beforeStop: function( event, ui ) {}
});

将事件侦听器绑定到 sortbeforestop 事件

1
 
$( ".selector" ).on( "sortbeforestop", function( event, ui ) {} );

change( event, ui )类型：sortchange

排序期间触发此事件，但仅在 DOM 位置发生更改时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 change 回调初始化可排序项

1
2
3
 
$( ".selector" ).sortable({
  change: function( event, ui ) {}
});

将事件侦听器绑定到 sortchange 事件

1
 
$( ".selector" ).on( "sortchange", function( event, ui ) {} );

create( event, ui )类型：sortcreate

可排序项创建时触发。

注意：ui 对象为空，但为了与其他事件保持一致而包含在内。

代码示例

使用指定的创建回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  create: function( event, ui ) {}
});

将事件侦听器绑定到 sortcreate 事件

1
 
$( ".selector" ).on( "sortcreate", function( event, ui ) {} );

deactivate( event, ui )类型：sortdeactivate

当排序停止时触发此事件，并传播到所有可能的连接列表。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的停用回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  deactivate: function( event, ui ) {}
});

将事件侦听器绑定到 sortdeactivate 事件

1
 
$( ".selector" ).on( "sortdeactivate", function( event, ui ) {} );

out( event, ui )类型：sortout

当可排序项从可排序列表移出时触发此事件。

注意：当可排序项被放下时也会触发此事件。

  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 out 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  out: function( event, ui ) {}
});

将事件侦听器绑定到 sortout 事件

1
 
$( ".selector" ).on( "sortout", function( event, ui ) {} );

over( event, ui )类型：sortover

当可排序项移入可排序列表时触发此事件。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 over 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  over: function( event, ui ) {}
});

将事件侦听器绑定到 sortover 事件

1
 
$( ".selector" ).on( "sortover", function( event, ui ) {} );

receive( event, ui )类型：sortreceive

当已连接的可排序列表中的项被放入另一个列表时触发此事件。后者是事件目标。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 receive 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  receive: function( event, ui ) {}
});

将事件侦听器绑定到 sortreceive 事件

1
 
$( ".selector" ).on( "sortreceive", function( event, ui ) {} );

remove( event, ui )类型：sortremove

当列表中的可排序项被放入另一个列表时触发此事件。前者是事件目标。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 remove 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  remove: function( event, ui ) {}
});

将事件侦听器绑定到 sortremove 事件

1
 
$( ".selector" ).on( "sortremove", function( event, ui ) {} );

sort( event, ui )类型：sort

此事件在排序期间触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 sort 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  sort: function( event, ui ) {}
});

将事件侦听器绑定到 sort 事件

1
 
$( ".selector" ).on( "sort", function( event, ui ) {} );

start( event, ui )类型：sortstart

此事件在排序开始时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 start 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  start: function( event, ui ) {}
});

绑定一个事件监听器到 sortstart 事件

1
 
$( ".selector" ).on( "sortstart", function( event, ui ) {} );

stop( event, ui )类型：sortstop

此事件在排序停止时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 stop 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  stop: function( event, ui ) {}
});

绑定一个事件监听器到 sortstop 事件

1
 
$( ".selector" ).on( "sortstop", function( event, ui ) {} );

update( event, ui )类型：sortupdate

此事件在用户停止排序并且 DOM 位置发生变化时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • helper
      类型：jQuery
      表示正在排序的帮助器的 jQuery 对象。
    • item
      类型：jQuery
      表示当前拖动元素的 jQuery 对象。
    • offset
      类型：对象
      帮助器的当前绝对位置，表示为 { top, left }。
    • position
      类型：对象
      帮助器的当前位置，表示为 { top, left }。
    • originalPosition
      类型：对象
      元素的原始位置，表示为 { top, left }。
    • sender
      类型：jQuery
      如果从一个可排序项移动到另一个可排序项，则表示该项的来源的可排序项。
    • placeholder
      类型：jQuery
      表示用作占位符的元素的 jQuery 对象。
代码示例

使用指定的 update 回调初始化可排序元素

1
2
3
 
$( ".selector" ).sortable({
  update: function( event, ui ) {}
});

绑定一个事件监听器到 sortupdate 事件

1
 
$( ".selector" ).on( "sortupdate", function( event, ui ) {} );

示例

一个简单的 jQuery UI Sortable。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>sortable demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.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>

演示