jq Sortable的使用

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

$ npm install sortablejs --save

• 1

使用

<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 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。

var sortable = Sortable.create(list); document.getElementById("switcher").onclick = function () { var state = sortable.option("disabled"); // get sortable.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 button item.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

• 1
• 2

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 Sortable npm install grunt 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

参考：https://blog.csdn.net/fxss5201/article/details/82528189