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

使用

<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

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