Sortable.js拖放排序JavaScript库

柯琛

2023-12-01

本文仅做翻译记录查看，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 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）以及接收元素。

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"); // 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

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

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