Sortable.js拖放排序JavaScript库

本文仅做翻译记录查看，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库。

特征

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

安装

通过npm

$ npm install sortablejs --save

使用

<ul id="items"><li>item 1</li><li>item 2</li><li>item 3</li>
</ul>

var el = document.getElementById('items');
var sortable = Sortable.create(el);

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

参数

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 starttouchStartThreshold: 0, // 像素，在多少像素移动范围内课取消延迟拖动事件。 px, how many pixels the point should move before cancelling a delayed drag eventdisabled: false, // 如果设置为true，则禁用排序。 Disables the sortable if set to true.store: null,  // @see Storeanimation: 150,  // 毫秒，排序时移动物品的动画速度，`0`则表示无动画。  ms, animation speed moving items when sorting, `0` — without animationhandle: ".my-handle",  // 列表项中拖动手柄选择，可以设置列表中item中的某个DOM节点为拖动的依据。 Drag handle selector within list itemsfilter: ".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 draggableghostClass: "sortable-ghost",  // 拖放时，提前预设DOM节点的class名称，可在此class下定义相应的样式。 Class name for the drop placeholderchosenClass: "sortable-chosen",  // 选中时的DOM节点的class名称，可在此class下定义相应的样式。Class name for the chosen itemdragClass: "sortable-drag",  // 拖放时的DOM节点的class名称，可在此class下定义相应的样式。Class name for the dragging itemdataIdAttr: 'data-id',forceFallback: false,  // 忽略HTML5 DnD行为并强制回退使用。ignore the HTML5 DnD behaviour and force the fallback to kick infallbackClass: "sortable-fallback",  //使用forceFallback时的克隆DOM元素的类名。 Class name for the cloned DOM Element when using forceFallbackfallbackOnBody: false,  // 将克隆的DOM元素追加到Document中Body 。Appends the cloned DOM Element into the Document's BodyfallbackTolerance: 0, // 以像素为单位指定鼠标在被视为拖动之前应移动多远。Specify in pixels how far the mouse should move before it's considered as a drag.scroll: true, // or HTMLElementscrollFn: function(offsetX, offsetY, originalEvent, touchEvt, hoverTargetEl) { ... }, // 如果你有自定义滚动条scrollFn可用于自动滚动 。if you have custom scrollbar scrollFn may be used for autoscrollingscrollSensitivity: 30, // 鼠标必须靠近边缘多少px才能开始滚动。px, how near the mouse must be to an edge to start scrolling.scrollSpeed: 10, // 滚动速度。pxsetData: function (/** DataTransfer */dataTransfer, /** HTMLElement*/dragEl) {dataTransfer.setData('Text', dragEl.textContent); // `dataTransfer` object of HTML5 DragEvent},// Element is chosenonChoose: function (/**Event*/evt) {evt.oldIndex;  // element index within parent},// Element dragging startedonStart: function (/**Event*/evt) {evt.oldIndex;  // element index within parent},// Element dragging endedonEnd: function (/**Event*/evt) {var itemEl = evt.item;  // dragged HTMLElementevt.to;    // target listevt.from;  // previous listevt.oldIndex;  // element's old index within old parentevt.newIndex;  // element's new index within new parent},// Element is dropped into the list from another listonAdd: function (/**Event*/evt) {// same properties as onEnd},// Changed sorting within listonUpdate: 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 listonRemove: function (/**Event*/evt) {// same properties as onEnd},// Attempt to drag a filtered elementonFilter: function (/**Event*/evt) {var itemEl = evt.item;  // HTMLElement receiving the `mousedown|tapstart` event.},// Event when you move an item in the list or between listsonMove: function (/**Event*/evt, /**Event*/originalEvent) {// Example: http://jsbin.com/tuyafe/1/edit?js,outputevt.dragged; // dragged HTMLElementevt.draggedRect; // TextRectangle {left, top, right и bottom}evt.related; // HTMLElement on which have guidedevt.relatedRect; // TextRectangleoriginalEvent.clientY; // mouse position// return false; — for cancel},// Called when creating a clone of elementonClone: function (/**Event*/evt) {var origEl = evt.item;var cloneEl = evt.clone;}
});

group

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

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

sort

在列表内排序。

delay

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

touchStartThreshold

此选项与fallbackTolerance选项类似。

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

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

3到5之间最好。

disabled

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

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

handle

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

<ul><li><span class="my-handle">::</span> list item text one<li><span class="my-handle">::</span> list item text two
</ul>

Sortable.create(el, {handle: ".my-handle"
});

.my-handle {cursor: move;cursor: -webkit-grabbing;
}

filter

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 buttonitem.parentNode.removeChild(item); // remove sortable item}else if (Sortable.utils.is(ctrl, ".js-edit")) {  // Click on edit link// ...}}
})

ghostClass

放置占位符的类名（默认sortable-ghost）。

.ghost {opacity: 0.4;
}

Sortable.create(list, {ghostClass: "ghost"
});

chosenClass

所选DOM节点的类名称（默认sortable-chosen）。

.chosen {color: #fff;background-color: #c00;
}

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[])

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

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

save()

保存当前排序

destroy()

完全删除可排序功能。

Store

保存和恢复排序。

<ul><li data-id="1">order</li><li data-id="2">save</li><li data-id="3">restore</li>
</ul>

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

<!-- 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组装插件，请执行以下步骤：

  cd Sortablenpm installgrunt jquery

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

  $("#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