آموزش جامع Sortable.js

📚معرفی و شروع سریع

Sortable.js یک کتابخانه مستقل برای ایجاد لیست‌های قابل مرتب‌سازی با Drag & Drop است. بدون jQuery، با پشتیبانی از Touch موبایل و سازگار با همه فریم‌ورک‌ها.

<!-- فایل محلی -->
<script src="Sortable.min.js"></script>

// ساده‌ترین استفاده
var el = document.getElementById('myList');
Sortable.create(el, {
  animation:   150,          // انیمیشن ms
  ghostClass:  'ghost-cls', // کلاس placeholder
  chosenClass: 'chosen-cls' // کلاس هنگام کشیدن
});

// یا با new
var sortable = new Sortable(el, { animation: 150 });

⚙تنظیمات پایه

var sortable = Sortable.create(listEl, {
  animation:   200,
  handle:      '.handle',    // فقط از دستگیره
  ghostClass:  'ghost-cls',
  chosenClass: 'chosen-cls',
  dragClass:   'drag-cls',
  delay:       100,          // ۱۰۰ms تأخیر (مفید برای موبایل)
  forceFallback: true
});

🔗گروه‌بندی (group)

با گزینه group می‌توانید چند لیست را به هم متصل کنید تا آیتم‌ها بین آن‌ها جابجا شوند.

// نام گروه مشترک
Sortable.create(document.getElementById('list-a'), {
  group: 'shared', animation: 150
});
Sortable.create(document.getElementById('list-b'), {
  group: 'shared', animation: 150
});

// تنظیمات پیشرفته گروه
Sortable.create(listEl, {
  group: {
    name: 'myGroup',
    pull: true,          // true | false | 'clone'
    put:  true           // true | false | ['groupName']
  }
});

📋حالت Clone

با pull: 'clone' آیتم‌ها کپی می‌شوند و نسخه اصلی در لیست منبع باقی می‌ماند.

Sortable.create(sourceList, {
  group: { name: 'clone-g', pull: 'clone', put: false },
  sort: false,     // منبع مرتب نمی‌شود
  animation: 150
});
Sortable.create(targetList, {
  group: { name: 'clone-g', pull: true, put: true },
  animation: 150
});

// سفارشی‌سازی کلون
Sortable.create(sourceList, {
  group: { name: 'g', pull: 'clone' },
  onClone: function(evt) {
    evt.clone.textContent += ' (کپی)';
    evt.clone.style.color = '#e74c3c';
  }
});

🚫Filter و Disabled

// آیتم‌های .no-drag قابل کشیدن نیستند
Sortable.create(listEl, {
  animation: 150,
  filter: '.no-drag',
  onFilter: function(evt) {
    // شیک کردن آیتم قفل‌شده
    evt.item.style.transform = 'translateX(-6px)';
    setTimeout(function(){ evt.item.style.transform = ''; }, 150);
  }
});

// غیرفعال / فعال کردن
sortable.option('disabled', true);   // غیرفعال
sortable.option('disabled', false);  // فعال

// draggable — عکس filter
Sortable.create(listEl, { draggable: '.sortable-item' });

📡رویدادها (Callbacks)

Sortable.create(listEl, {
  animation: 150,
  dataIdAttr: 'data-id',

  onStart: function(evt) {
    console.log('شروع — index:', evt.oldIndex);
  },
  onEnd: function(evt) {
    console.log('از', evt.oldIndex, 'به', evt.newIndex);
  },
  onSort: function() {
    var order = sortable.toArray();  // ['id1','id2',...]
    console.log('ترتیب جدید:', order);
  }
});

⚡API و متدها

var sortable = Sortable.create(listEl, { animation: 150, dataIdAttr: 'data-id' });

// toArray — آرایه data-id ها به ترتیب فعلی
var order = sortable.toArray(); // ['id3','id1','id2']

// sort — مرتب‌سازی برنامه‌نویسی
sortable.sort(['id1', 'id2', 'id3']);

// option — خواندن / تنظیم گزینه
sortable.option('animation');          // خواندن
sortable.option('disabled', true);     // تنظیم
sortable.option('animation', 300);    // تنظیم

// destroy — حذف کامل
sortable.destroy();

// Sortable.get — گرفتن instance از element
var instance = Sortable.get(document.getElementById('myList'));

📋تخته Kanban

ترکیب group و چند لیست Sortable برای ساختن یک تخته Kanban واقعی مثل Trello:

// هر ستون = یک Sortable با group مشترک
['todo', 'doing', 'done'].forEach(function(col) {
  Sortable.create(document.getElementById('col-' + col), {
    group:       'kanban',
    animation:   200,
    ghostClass:  'ghost-class',
    chosenClass: 'chosen-class',
    onAdd: function(evt) {
      updateColumnCounts(); // آپدیت شمارنده ستون
    }
  });
});

🔗یکپارچه‌سازی

React — با useRef و useEffect

// React
import { useEffect, useRef } from 'react';
import Sortable from 'sortablejs';

function SortableList({ items, onReorder }) {
  const listRef = useRef(null);

  useEffect(() => {
    const sortable = Sortable.create(listRef.current, {
      animation: 150,
      onEnd: (evt) => {
        onReorder(evt.oldIndex, evt.newIndex);
      }
    });
    return () => sortable.destroy(); // cleanup
  }, []);

  return <ul ref={listRef}>
    {items.map(item => <li key={item.id} data-id={item.id}>{item.text}</li>)}
  </ul>;
}

Vue 3 — با onMounted

import { onMounted, onUnmounted, ref } from 'vue';
import Sortable from 'sortablejs';

setup() {
  const listEl = ref(null);
  let sortable;

  onMounted(() => {
    sortable = Sortable.create(listEl.value, { animation: 150 });
  });
  onUnmounted(() => sortable.destroy());
  return { listEl };
}

ذخیره ترتیب در سرور

Sortable.create(listEl, {
  animation: 150,
  dataIdAttr: 'data-id',
  onSort: function() {
    var order = sortable.toArray();
    fetch('/api/save-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ order })
    });
  }
});

🔥بهترین شیوه‌ها

🚀زمین بازی کد (Playground)

با Sortable.js لیست‌ها را Drag & Drop کن. مرتب‌سازی، جابجایی بین دو لیست و رویدادها را امتحان کن. نسخهٔ ۱.۱۵.۲ آفلاین بارگذاری می‌شود.