Sortable.js拖放排序JavaScript库

Myth丶恋晨 2022-05-14 12:54 274阅读 0赞

本文仅做翻译记录查看，GitHub原项目地址：  
[https://github.com/RubaXa/Sortable/][https_github.com_RubaXa_Sortable] ，建议将Sortable.js下载到本地，GitHub上的例子在复制到本地运行，在 [http://jsbin.com][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

## 使用 ##

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

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

## 参数 ##

### group ###

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

### 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将禁用用户的文本选择。这并不总是令人满意的。要允许文本选择，请定义拖动处理程序，该处理程序是允许拖动它的每个列表元素的区域。

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

<script src="https://cdn.jsdelivr.net/npm/sortablejs@1.6.1/Sortable.min.js"></script>
    
    
    
    <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

[https_github.com_RubaXa_Sortable]: https://github.com/RubaXa/Sortable/
[http_jsbin.com]: http://jsbin.com
[Link 1]: http://jsbin.com/qumuwe/edit?html,css,js,console,output