sortable2

Sortable改良版

Sortable是一个用于可重新排序的拖放列表的JavaScript库.

演示: http://sortablejs.github.io/Sortable/

特征

• 支持触摸设备和 现代 浏览器（包括IE9）
• 可以从一个列表拖动到另一个列表或在同一列表中
• 移动项目时的CSS动画
• 支持拖动手柄和可选文本
• 智能自动滚动
• 高级交换检测
• 使用原生HTML5拖放API构建
• 支持任何CSS库，例如Bootstrap
• 简单的API
• 不需要jQuery

安装

通过 npm

$ npm install sortable2 --save

通过 bower:

$ bower install --save sortable2

用法

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

---

选项

var sortable = new Sortable(el, {
    //  或{name：“...”，pull：[true，false，'clone'，array]，put：[true，false，array]}
    group: "name",  
    //  在列表内排序
    sort: true,  
    // 以毫秒为单位定义何时开始排序  
    delay: 0, 
    // 仅在用户使用触摸时才会延迟 
    delayOnTouchOnly: false, 
    //  px，在取消延迟拖动事件之前该点应移动多少像素
    touchStartThreshold: 0, 
    // 如果设置为true ，则禁用sortable.
    disabled: false, 
    // @see 存储
    store: null,  
    // ms，排序时动画速度移动项目，“0” - 没有动画
    animation: 150,  
    // 缓动动画。默认为null。有关 示例，请参阅  https://easings.net/。
    easing: "cubic-bezier(1, 0, 0, 1)", 
    // 在列表项中拖动句柄选择器 
    handle: ".my-handle",  
    // 不会导致拖动的选择器（String或Function）   
    filter: ".ignore-elements",  
  //  触发`filter`时调用`event.preventDefault（） 
    preventOnFilter: true, 
    // 指定元素内的哪些项应该是可拖动的  
    draggable: ".item",  
    // drop placeholder的类名
    ghostClass: "sortable-ghost",  
    // 所选项目的类名称  
    chosenClass: "sortable-chosen",  
    // 拖动项的类名   
    dragClass: "sortable-drag",  
    dataIdAttr: 'data-id',
 
  // 交换区域的阈值
    swapThreshold: 1, 
    // 如果设置为true ，将始终使用反向交换区域 
    invertSwap: false, 
    // 反向交换区域的阈值（默认设置为swapThreshold值）
    invertedSwapThreshold: 1, 
    // 锁定拖拉方向
    direction: 'xy', 
 
  // 忽略HTML5 拖拉行为并强制回退   
    forceFallback: false,  
 
  // 使用forceFallback时克隆的DOM元素的类名   
    fallbackClass: "sortable-fallback",  
    // 将克隆的DOM元素追加到Document的Body中 
    fallbackOnBody: false,  
    // 像素为单位指定鼠标在被视为拖动之前应移动多远。  
    fallbackTolerance: 0, 
 
  // or HTMLElement
    scroll: true, 
    // 如果你有自定义滚动条scrollFn可用于自动滚动
    scrollFn: function(offsetX, offsetY, originalEvent, touchEvt, hoverTargetEl) { ... }, 
    // px, 鼠标必须靠近边缘才能开始滚动。  
    scrollSensitivity: 30, 
    // px
    scrollSpeed: 10, 
    //  将 autoscroll 应用于所有父元素，以便更轻松地移动
    bubbleScroll: true, 
 
    dragoverBubble: false,
     // 删除未显示的克隆元素，而不是仅隐藏它
    removeCloneOnHide: true,
    // px，distance mouse必须是空的sortable才能将drag元素插入其中  
    emptyInsertThreshold: 5, 
 
 
    setData: function (/** DataTransfer */dataTransfer, /** HTMLElement*/dragEl) {
        dataTransfer.setData('Text', dragEl.textContent); // HTML5 DragEvent的`dataTransfer`对象 
    },
 
    // 元素被选中
    onChoose: function (/**Event*/evt) {
        evt.oldIndex;  // 父元素索引
    },
 
    // 元素是非选择的
    onUnchoose: function(/**Event*/evt) {
        // 与onEnd相同的属性
    },
 
    // 元素拖动已开始
    onStart: function (/**Event*/evt) {
        evt.oldIndex;  // 父元素索引
    },
 
    // 元素拖动结束
    onEnd: function (/**Event*/evt) {
        var itemEl = evt.item;  // 拖动HTMLElement 
        evt.to;    // 目标列表    
        evt.from;  // 上一个清单  
        evt.oldIndex;  // 元素在旧父级中的旧索引  
        evt.newIndex;  // 元素在新父级中的新索引
        evt.oldDraggableIndex; // 元素在旧父元素中的旧索引，仅计算可拖动元素 
        evt.newDraggableIndex; // 元素在新父元素中的新索引，仅计算可拖动元素 
        evt.clone // 克隆元素 
        evt.pullMode;  // 当item在另一个sortable中时：`clone`如果克隆，`true`如果移动  
    },
 
    // 元素从另一个列表中放入列表中
    onAdd: function (/**Event*/evt) {
        // 与onEnd相同的属性
    },
 
    // 更改了列表中的排序
    onUpdate: function (/**Event*/evt) {
        // 与onEnd相同的属性
    },
 
    // 通过列表的任何更改调用（添加/更新/删除）
    onSort: function (/**Event*/evt) {
        // 与onEnd相同的属性
    },
 
    // 元素从列表中删除到另一个列表中
    onRemove: function (/**Event*/evt) {
        // 与onEnd相同的属性
    },
 
    // 尝试拖动已过滤的元素
    onFilter: function (/**Event*/evt) {
        var itemEl = evt.item;  //  HTMLElement接收 `mousedown|tapstart` 事件.
    },
 
    // 在列表中或列表之间移动项目时的事件
    onMove: function (/**Event*/evt, /**Event*/originalEvent) {
        evt.dragged; // 拖动HTMLElement 
        evt.draggedRect; // DOMRect {left, top, right, bottom}
        evt.related; // 引导的HTMLElement 
        evt.relatedRect; // DOMRect
        evt.willInsertAfter; // 如果Sortable默认情况下会在目标之后插入drag元素，则为true
        originalEvent.clientY; // 鼠标位置
        //  返回false;  - 取消
        //  返回-1;  - 在目标之前插入
        //  返回1;  - 插入目标后
    },
 
    // 在创建元素克隆时调用
    onClone: function (/**Event*/evt) {
        var origEl = evt.item;
        var cloneEl = evt.clone;
    },
 
    // 拖动元素更改位置时调用
    onChange: function(/**Event*/evt) {
        evt.newIndex // 最有可能使用此事件的原因是获取拖动元素的当前索引 
        // 与onEnd相同的属性
    }
});

---

group 选项

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

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

演示:

• https://jsbin.com/hijetos/edit?js,output
• https://jsbin.com/nacoyah/edit?js,output — 在pull和中使用复杂逻辑put
• https://jsbin.com/bifuyab/edit?js,output — 使用 revertClone: true

---

sort 选项

在列表内排序。

演示: https://jsbin.com/jayedig/edit?js,output

---

delay 选项

定义何时开始排序的时间（以毫秒为单位）。不幸的是，由于浏览器的限制，在本机拖放的IE或Edge上无法延迟。

演示: https://jsbin.com/zosiwah/edit?js,output

---

delayOnTouchOnly 选项

是否应仅在用户使用触摸时（例如，在移动设备上）应用延迟。在任何其他情况下都不会延迟。默认为 false.

---

swapThreshold 选项

交换区域将占用的目标的百分比，作为0和之间的浮点数1

阅读更多: https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction#swap-threshold

演示: http://sortablejs.github.io/Sortable#thresholds

---

invertSwap 选项

设置为true将交换区域设置为目标的两侧，以便对“介于”项目之间进行排序

演示: http://sortablejs.github.io/Sortable#thresholds

---

invertedSwapThreshold 选项

反转交换区域将占用的目标百分比，作为0和之间的浮点数1。如果没有给出，将默认为 swapThreshold.

Read more: https://github.com/SortableJS/Sortable/wiki/Swap-Thresholds-and-Direction#dealing-with-swap-glitching

---

direction 选项

拖拉方向排序

---

touchStartThreshold 选项

此选项与fallbackTolerance选项类似。

delay设置此选项后，即使您的手指没有移动， 某些具有非常敏感触摸显示屏的手机（如Samsung Galaxy S8）也会触发不需要的触摸移动事件，从而导致排序无法触发。 此选项设置在取消延迟排序之前必须发生的最小指针移动

3 到 5 是最佳值.

---

disabled 选项

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

演示: https://jsbin.com/sewokud/edit?js,output

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

---

handle 选项

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

演示: https://jsbin.com/numakuh/edit?html,js,output

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

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

.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).

演示: https://jsbin.com/henuyiw/edit?css,js,output

.ghost {
  opacity: 0.4;
}

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

---

chosenClass 选项

所选项目的类名称（默认sortable-chosen）.

演示: https://jsbin.com/hoqufox/edit?css,js,output

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

Sortable.create(list, {
  delay: 500,
  chosenClass: "chosen"
});

---

forceFallback 选项

如果设置为true，即使我们使用HTML5浏览器，也将使用非HTML5浏览器的后备。 这使我们有可能测试旧浏览器的行为，即使在较新的浏览器中，也可以使Drag'n Drop在桌面，移动和旧浏览器之间更加一致。 最重要的是，Fallback总是生成该DOM元素的副本，并附加fallbackClass选项中定义的类。此行为控制此“拖动”元素的外观.

演示: https://jsbin.com/sibiput/edit?html,css,js,output

---

fallbackTolerance 选项

模拟本机阻力阈值。 以像素为单位指定鼠标在被视为拖动之前应移动多远。如果项目也可以在链接列表中单击，则非常有用。 当用户在可排序元素中单击时，在您按下的时间和释放时间之间，您的手移动一点并不罕见。 仅当您将指针移动超过某个公差时才会开始拖动，这样您每次单击时都不会意外地开始拖动.

3 到 5 是最佳值.

---

scroll 选项

如果设置为true，则页面（或可排序区域）在到达边缘时滚动.

演示:

• window: https://jsbin.com/dosilir/edit?js,output
• overflow: hidden: https://jsbin.com/xecihez/edit?html,js,output

---

scrollFn 选项

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

---

scrollSensitivity 选项

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

---

scrollSpeed 选项

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

---

bubbleScroll 选项

如果设置为true，则普通autoscroll函数也将应用于用户拖动的元素的所有父元素.

演示: https://jsbin.com/kesewor/edit?html,js,output

---

dragoverBubble 选项

如果设置为true，则dragover事件将冒泡到父排序。 适用于后备和本地dragover事件。默认情况下， 它是false，但Sortable只会在元素插入父Sortable后停止冒泡，或者可以插入父Sortable，但不是在特定时间（由于动画等）

---

removeCloneOnHide 选项

如果设置为false，则通过将其CSS display属性设置为隐藏克隆 none。默认情况下，此选项是true，意味着Sortable将在DOM被隐藏时从DOM中删除克隆元素。

---

emptyInsertThreshold 选项

鼠标必须是空的可排序的距离（以像素为单位），同时拖动要插入到可排序的拖动元素。默认为5。设置为0禁用此功能.

Demo: https://jsbin.com/becavoj/edit?js,output

---

事件对象 (演示)

• to:HTMLElement — 目标元素
• from:HTMLElement — 拖动元素
• item:HTMLElement — 拖动dom
• clone:HTMLElement
• oldIndex:Number|undefined — 父级中的旧索引
• newIndex:Number|undefined — 父级内的新索引
• oldDraggableIndex: Number|undefined — 父级中的旧索引，仅计算可拖动元素
• newDraggableIndex: Number|undefined — 父级内的新索引，仅计算可拖动元素
• pullMode:String|Boolean|undefined — 拖拉模式,拖动到另一个可排序（"clone", true, or false），否则未定义

move 事件对象

• to:HTMLElement
• from:HTMLElement
• dragged:HTMLElement
• draggedRect:DOMRect
• related:HTMLElement — 引导的元素
• relatedRect:DOMRect
• willInsertAfter:Boolean — true 如果将元素插入目标之后（或false之前

---

方法

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()

保存当前排序 (see store)

destroy()

完全删除可排序功能.

---

存储

保存和恢复排序.

<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 — 获取一个函数并返回一个始终具有特定上下文的新函数
• 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) — 在每个元素中添加或删除一个类
• detectDirection(el:HTMLElement):String — 拖动方向:x或y获取xy