文章目录
  1. 1. 特征
  2. 2. 安装
  3. 3. 使用
  4. 4. 参数
    1. 4.1. group
    2. 4.2. sort
    3. 4.3. delay
    4. 4.4. touchStartThreshold
    5. 4.5. disabled
    6. 4.6. handle
    7. 4.7. filter
    8. 4.8. ghostClass
    9. 4.9. chosenClass
    10. 4.10. forceFallback
    11. 4.11. fallbackTolerance
    12. 4.12. scroll
    13. 4.13. scrollFn
    14. 4.14. scrollSensitivity
    15. 4.15. scrollSpeed
  5. 5. 事件对象
    1. 5.1. move —- event object
  6. 6. Method
    1. 6.1. option(name:String[, value:]):
    2. 6.2. closest(el:String[, selector:HTMLElement]):HTMLElement|null
    3. 6.3. toArray():String[]
    4. 6.4. sort(order:String[])
    5. 6.5. save()
    6. 6.6. destroy()
    7. 6.7. Store
  7. 7. 静态方法和属性
    1. 7.1. Sortable.create(el:HTMLElement[, options:Object]):Sortable
    2. 7.2. Sortable.active:Sortable
    3. 7.3. Sortable.utils
  8. 8. CDN
  9. 9. jQuery compatibility

本文仅做翻译记录查看,GitHub原项目地址:
https://github.com/RubaXa/Sortable/ ,建议将Sortable.js下载到本地,GitHub上的例子在复制到本地运行,在 http://jsbin.com 上运行很多时候会报Sortable is not defined 的错误。

Sortable.js是用于在现代浏览器和触摸设备上重新拖放排序列表的JavaScript库,支持jQuery,Meteor,AngularJS,React,Polymer,Knockout和兼容任何CSS库。

特征

  1. 支持触摸设备和现代浏览器(包括IE9)
  2. 可以从一个列表拖动到另一个列表或在同一列表中
  3. 移动项目时的CSS动画
  4. 支持拖动手柄和可选文本
  5. 智能自动滚动
  6. 使用原生HTML5拖放API构建
  7. 支持任何CSS库
  8. 简单的API
  9. 不基于jQuery(但同样也支持)

安装

通过npm

1
$ npm install sortablejs --save

使用

1
2
3
4
5
<ul id="items">
<li>item 1</li>
<li>item 2</li>
<li>item 3</li>
</ul>
1
2
var el = document.getElementById('items');
var sortable = Sortable.create(el);

您可以使用列表及其元素的任何元素,而不仅仅是ul/ li。这是div例子

参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
var sortable = new Sortable(el, {
group: "name", // or { name: "...", pull: [true, false, clone], put: [true, false, array] }
sort: true, //在列表内支持排序。 sorting inside list
delay: 0, // 时间以毫秒为单位来定义排序应该何时开始。 time in milliseconds to define when the sorting should start
touchStartThreshold: 0, // 像素,在多少像素移动范围内课取消延迟拖动事件。 px, how many pixels the point should move before cancelling a delayed drag event
disabled: false, // 如果设置为true,则禁用排序。 Disables the sortable if set to true.
store: null, // @see Store
animation: 150, // 毫秒,排序时移动物品的动画速度,`0`则表示无动画。 ms, animation speed moving items when sorting, `0` — without animation
handle: ".my-handle", // 列表项中拖动手柄选择,可以设置列表中item中的某个DOM节点为拖动的依据。 Drag handle selector within list items
filter: ".ignore-elements", // 选择不支持拖动的选择器(String或Function)。 Selectors that do not lead to dragging (String or Function)
preventOnFilter: true, // 触发`filter`时调用`event.preventDefault()`。 Call `event.preventDefault()` when triggered `filter`
draggable: ".item", // 指定元素中的哪些项应该是可拖动的。 Specifies which items inside the element should be draggable
ghostClass: "sortable-ghost", // 拖放时,提前预设DOM节点的class名称,可在此class下定义相应的样式。 Class name for the drop placeholder
chosenClass: "sortable-chosen", // 选中时的DOM节点的class名称,可在此class下定义相应的样式。Class name for the chosen item
dragClass: "sortable-drag", // 拖放时的DOM节点的class名称,可在此class下定义相应的样式。Class name for the dragging item
dataIdAttr: 'data-id',

forceFallback: false, // 忽略HTML5 DnD行为并强制回退使用。ignore the HTML5 DnD behaviour and force the fallback to kick in

fallbackClass: "sortable-fallback", //使用forceFallback时的克隆DOM元素的类名。 Class name for the cloned DOM Element when using forceFallback
fallbackOnBody: false, // 将克隆的DOM元素追加到Document中Body 。Appends the cloned DOM Element into the Document's Body
fallbackTolerance: 0, // 以像素为单位指定鼠标在被视为拖动之前应移动多远。Specify in pixels how far the mouse should move before it's considered as a drag.

scroll: true, // or HTMLElement
scrollFn: function(offsetX, offsetY, originalEvent, touchEvt, hoverTargetEl) { ... }, // 如果你有自定义滚动条scrollFn可用于自动滚动 。if you have custom scrollbar scrollFn may be used for autoscrolling
scrollSensitivity: 30, // 鼠标必须靠近边缘多少px才能开始滚动。px, how near the mouse must be to an edge to start scrolling.
scrollSpeed: 10, // 滚动速度。px

setData: function (/** DataTransfer */dataTransfer, /** HTMLElement*/dragEl) {
dataTransfer.setData('Text', dragEl.textContent); // `dataTransfer` object of HTML5 DragEvent
},

// Element is chosen
onChoose: function (/**Event*/evt) {
evt.oldIndex; // element index within parent
},

// Element dragging started
onStart: function (/**Event*/evt) {
evt.oldIndex; // element index within parent
},

// Element dragging ended
onEnd: function (/**Event*/evt) {
var itemEl = evt.item; // dragged HTMLElement
evt.to; // target list
evt.from; // previous list
evt.oldIndex; // element's old index within old parent
evt.newIndex; // element's new index within new parent
},

// Element is dropped into the list from another list
onAdd: function (/**Event*/evt) {
// same properties as onEnd
},

// Changed sorting within list
onUpdate: function (/**Event*/evt) {
// same properties as onEnd
},

// Called by any change to the list (add / update / remove)
onSort: function (/**Event*/evt) {
// same properties as onEnd
},

// Element is removed from the list into another list
onRemove: function (/**Event*/evt) {
// same properties as onEnd
},

// Attempt to drag a filtered element
onFilter: function (/**Event*/evt) {
var itemEl = evt.item; // HTMLElement receiving the `mousedown|tapstart` event.
},

// Event when you move an item in the list or between lists
onMove: function (/**Event*/evt, /**Event*/originalEvent) {
// Example: http://jsbin.com/tuyafe/1/edit?js,output
evt.dragged; // dragged HTMLElement
evt.draggedRect; // TextRectangle {left, top, right и bottom}
evt.related; // HTMLElement on which have guided
evt.relatedRect; // TextRectangle
originalEvent.clientY; // mouse position
// return false; — for cancel
},

// Called when creating a clone of element
onClone: function (/**Event*/evt) {
var origEl = evt.item;
var cloneEl = evt.clone;
}
});

group

要将元素从一个列表拖动到另一个列表,两个列表必须具有相同的group值。您还可以定义列表是否可以放弃,提供和保留副本(clone)以及接收元素。

  1. name:String–组名
  2. pull:true|false|'clone'|function–从列表中移动的能力。clone - 复制项目,而不是移动。
  3. put: true|false|["foo", "bar"]|function –是否可以从其他列表添加元素,或者可以从中获取元素的组名称数组。
  4. revertClone: boolean–移动到另一个列表后,将克隆元素恢复到初始位置。

sort

在列表内排序。

delay

定义何时开始排序的时间(以毫秒为单位)。

touchStartThreshold

此选项与fallbackTolerance选项类似。

delay设置此选项后,即使您的手指没有移动,一些具有非常敏感触摸显示屏的手机(如三星Galaxy S8)也会触发不需要的触摸移动事件,从而导致排序无法触发。

此选项设置在取消延迟排序之前必须发生的最小指针移动。

3到5之间最好。

disabled

如果设置为 true,则禁用sortable。

1
2
3
4
5
6
var sortable = Sortable.create(list);

document.getElementById("switcher").onclick = function () {
var state = sortable.option("disabled"); // get
sortable.option("disabled", !state); // set
};

handle

要使列表项可拖动,Sortable将禁用用户的文本选择。这并不总是令人满意的。要允许文本选择,请定义拖动处理程序,该处理程序是允许拖动它的每个列表元素的区域。

1
2
3
4
<ul>
<li><span class="my-handle">::</span> list item text one
<li><span class="my-handle">::</span> list item text two
</ul>
1
2
3
Sortable.create(el, {
handle: ".my-handle"
});
1
2
3
4
.my-handle {
cursor: move;
cursor: -webkit-grabbing;
}

filter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Sortable.create(list, {
filter: ".js-remove, .js-edit",
onFilter: function (evt) {
var item = evt.item,
ctrl = evt.target;

if (Sortable.utils.is(ctrl, ".js-remove")) { // Click on remove button
item.parentNode.removeChild(item); // remove sortable item
}
else if (Sortable.utils.is(ctrl, ".js-edit")) { // Click on edit link
// ...
}
}
})

ghostClass

放置占位符的类名(默认sortable-ghost)。

1
2
3
.ghost {
opacity: 0.4;
}
1
2
3
Sortable.create(list, {
ghostClass: "ghost"
});

chosenClass

所选DOM节点的类名称(默认sortable-chosen)。

1
2
3
4
.chosen {
color: #fff;
background-color: #c00;
}
1
2
3
4
Sortable.create(list, {
delay: 500,
chosenClass: "chosen"
});

forceFallback

如果设置为true,则即使我们使用HTML5浏览器,也将使用非HTML5浏览器的后备。这使我们有可能测试旧浏览器的行为,即使在较新的浏览器中,也可以使Drag’n Drop在桌面,移动和旧浏览器之间更加一致。

最重要的是,Fallback总是生成该DOM元素的副本,并附加fallbackClass在选项中定义的类。此行为控制此“拖动”元素的外观。

fallbackTolerance

模拟本机阻力阈值。以像素为单位指定鼠标在被视为拖动之前应移动多远。如果项目也可以在链接列表中单击,则非常有用。

当用户在可排序元素中单击时,在您按下的时间和释放时间之间移动一点并不常见。仅当您将指针移动超过某个公差时才会开始拖动,这样您每次单击时都不会意外地开始拖动。

3到5之间最好。

scroll

如果设置为true,则页面(或可排序区域)在到达边缘时滚动。

scrollFn

定义将用于自动滚动的功能。默认情况下使用el.scrollTop / el.scrollLeft。有自定义滚动条和专用滚动功能时很有用。

scrollSensitivity

定义鼠标必须靠近边缘以开始滚动的方式。

scrollSpeed

鼠标指针进入scrollSensitivity距离后窗口应滚动的速度。

事件对象

  • to:HTMLElement — list,其中移动了元素。
  • from:HTMLElement — 之前存在的list
  • item:HTMLElement — 拖动元素
  • clone:HTMLElement
  • oldIndex:Number|undefined — 父级中的旧索引
  • newIndex:Number|undefined — 父级中的新索引

move —- event object

  • to:HTMLElement
  • from:HTMLElement
  • dragged:HTMLElement
  • draggedRect:TextRectangle
  • related:HTMLElement — 指导的元素
  • relatedRect:TextRectangle

Method

option(name:String[, value:]):

获取或设置选项。

closest(el:String[, selector:HTMLElement]):HTMLElement|null

对于集合中的每个元素,通过测试元素本身并遍历DOM树中的祖先来获取与选择器匹配的第一个元素。

toArray():String[]

将可排序项data-id的(dataIdAttr选项)序列化为字符串数组。

sort(order:String[])

根据数组对元素进行排序。

1
2
var order = sortable.toArray();
sortable.sort(order.reverse()); // apply

save()

保存当前排序

destroy()

完全删除可排序功能。

Store

保存和恢复排序。

1
2
3
4
5
<ul>
<li data-id="1">order</li>
<li data-id="2">save</li>
<li data-id="3">restore</li>
</ul>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Sortable.create(el, {
group: "localStorage-example",
store: {
/**
* Get the order of elements. Called once during initialization.
* @param {Sortable} sortable
* @returns {Array}
*/
get: function (sortable) {
var order = localStorage.getItem(sortable.options.group.name);
return order ? order.split('|') : [];
},

/**
* Save the order of elements. Called onEnd (when the item is dropped).
* @param {Sortable} sortable
*/
set: function (sortable) {
var order = sortable.toArray();
localStorage.setItem(sortable.options.group.name, order.join('|'));
}
}
})

静态方法和属性

Sortable.create(el:HTMLElement[, options:Object]):Sortable

创建新实例。

Sortable.active:Sortable

链接到活动实例。

Sortable.utils

  • on(el:HTMLElement, event:String, fn:Function) — 附加事件处理函数
  • off(el:HTMLElement, event:String, fn:Function) — 删除事件处理程序
  • css(el:HTMLElement):Object — 获取所有CSS属性的值
  • css(el:HTMLElement, prop:String):Mixed — 获取样式属性的值
  • css(el:HTMLElement, prop:String, value:String) — 设置一个CSS属性
  • css(el:HTMLElement, props:Object) — 设置更多CSS属性
  • find(ctx:HTMLElement, tagName:String[, iterator:Function]):Array — 按标签名称获取元素
  • bind(ctx:Mixed, fn:Function):Function — T获取一个函数并返回一个始终具有特定上下文的函数
  • is(el:HTMLElement, selector:String):Boolean — 针对选择器检查当前匹配的元素集
  • closest(el:HTMLElement, selector:String[, ctx:HTMLElement]):HTMLElement|Null — 对于集合中的每个元素,通过测试元素本身并遍历DOM树中的祖先来获取与选择器匹配的第一个元素
  • clone(el:HTMLElement):HTMLElement — 创建匹配元素集的深层副本
  • toggleClass(el:HTMLElement, name:String, state:Boolean) — 从每个元素添加或删除一个类

CDN

1
2
3
4
5
6
<!-- jsDelivr :: Sortable (https://www.jsdelivr.com/package/npm/sortablejs) -->
<script src="https://cdn.jsdelivr.net/npm/sortablejs@1.6.1/Sortable.min.js"></script>


<!-- jsDelivr :: Sortable :: Latest (https://www.jsdelivr.com/package/npm/sortablejs) -->
<script src="https://cdn.jsdelivr.net/npm/sortablejs@latest/Sortable.min.js"></script>

jQuery compatibility

要为jQuery组装插件,请执行以下步骤:

1
2
3
cd Sortable
npm install
grunt jquery

现在您可以使用jquery.fn.sortable.js:(
或者jquery.fn.sortable.min.js如果您运行grunt jquery:min)

1
2
3
4
5
6
7
8
9
$("#list").sortable({ /* options */ }); // init

$("#list").sortable("widget"); // get Sortable instance

$("#list").sortable("destroy"); // destroy Sortable instance

$("#list").sortable("{method-name}"); // call an instance method

$("#list").sortable("{method-name}", "foo", "bar"); // call an instance method with parameters

And grunt jquery:mySortableFunc → jquery.fn.mySortableFunc.js

文章目录
  1. 1. 特征
  2. 2. 安装
  3. 3. 使用
  4. 4. 参数
    1. 4.1. group
    2. 4.2. sort
    3. 4.3. delay
    4. 4.4. touchStartThreshold
    5. 4.5. disabled
    6. 4.6. handle
    7. 4.7. filter
    8. 4.8. ghostClass
    9. 4.9. chosenClass
    10. 4.10. forceFallback
    11. 4.11. fallbackTolerance
    12. 4.12. scroll
    13. 4.13. scrollFn
    14. 4.14. scrollSensitivity
    15. 4.15. scrollSpeed
  5. 5. 事件对象
    1. 5.1. move —- event object
  6. 6. Method
    1. 6.1. option(name:String[, value:]):
    2. 6.2. closest(el:String[, selector:HTMLElement]):HTMLElement|null
    3. 6.3. toArray():String[]
    4. 6.4. sort(order:String[])
    5. 6.5. save()
    6. 6.6. destroy()
    7. 6.7. Store
  7. 7. 静态方法和属性
    1. 7.1. Sortable.create(el:HTMLElement[, options:Object]):Sortable
    2. 7.2. Sortable.active:Sortable
    3. 7.3. Sortable.utils
  8. 8. CDN
  9. 9. jQuery compatibility