jQuery UI Sortable 是經典拖拽排序庫。本文系統整理所有選項、事件、方法,附帶實戰配置範例(跨列表拖拽、網格對齊、動畫回彈、滾動容器、自定義手柄),適合直接複製調參。
| 選項 | 類型 | 預設 | 說明 |
|---|---|---|---|
| appendTo | String | 'parent' | 輔助元素掛載容器,解決 z-index 遮蓋 |
| axis | 'x'|'y'|false | false | 限制拖拽方向 |
| cancel | Selector | ':input,button' | 禁止拖拽的元素(如輸入框) |
| connectWith | Selector | false | 連接其他 sortable 列表,實現跨列表拖拽 |
| containment | Selector/Element | false | 限制拖拽範圍('parent', 'document', 'window') |
| cursor | String | 'auto' | 拖拽時游標樣式 |
| cursorAt | Object | false | 游標相對輔助元素位置 `{top, left}` |
| delay | Integer | 0 | 延遲啟動 ms,防誤觸 |
| distance | Integer | 1 | 最小拖拽距離觸發排序 px |
| dropOnEmpty | Boolean | true | 允許拖入空列表 |
| forceHelperSize | Boolean | false | 強制輔助元素有尺寸 |
| forcePlaceholderSize | Boolean | false | 強制佔位符有尺寸 |
| grid | [x, y] | false | 網格對齊步進 |
| handle | Selector/Element | false | 拖拽手柄(如 '.drag-handle') |
| helper | 'original'|'clone'|Function | 'original' | 輔助元素類型,clone 可避免原元素位移 |
| items | Selector | '> *' | 可排序子元素選取器 |
| opacity | Float | false | 輔助元素透明度 |
| placeholder | String | false | 佔位符 CSS 類別 |
| revert | Boolean/Integer | false | 放置時動畫回彈 ms |
| scroll | Boolean | true | 邊緣自動滾動容器 |
| scrollSensitivity | Integer | 20 | 觸發滾動邊距 px |
| scrollSpeed | Integer | 20 | 滾動速度 px/ms |
| tolerance | 'intersect'|'pointer' | 'intersect' | 判定重疊方式:50%面積 或 指標重疊 |
| zIndex | Integer | 1000 | 輔助元素 z-index |
所有回調接收 `(event, ui)`,`ui` 物件屬性:
| 事件 | 觸發時機 |
|---|---|
| create | 初始化完成 |
| start | 開始拖拽 |
| sort | 拖拽中 (高頻,慎做重運算) |
| change | DOM 位置實際改變時 |
| beforeStop | 放置前,佔位符尚在 |
| stop | 拖拽結束 |
| update | 順序實際改變且停止時 (最常用於存檔) |
| receive | 接收來自其他列表的元素 |
| remove | 元素被拖離到其他列表 |
| over/out | 進入/離開其他 sortable 區域 |
| activate/deactivate | 連接列表啟用/停用 |
$('#task-list').sortable({
axis: 'y',
handle: '.drag-handle',
placeholder: 'ui-state-highlight',
forcePlaceholderSize: true,
tolerance: 'pointer',
revert: 150,
scroll: true,
scrollSensitivity: 40,
update: function(e, ui) {
const order = $(this).sortable('toArray', { attribute: 'data-id' });
saveOrderToServer(order); // AJAX 儲存新順序
}
}).disableSelection(); // 禁止文字選取干擾
$('#list').sortable('enable'); // 啟用
$('#list').sortable('disable'); // 停用
$('#list').sortable('refresh'); // 重新掃描 items (動態增刪後必呼叫)
$('#list').sortable('toArray'); // 取得項目 id 陣列
$('#list').sortable('serialize'); // 序列化為 'id[]=1&id[]=2...' 供後端
jQuery UI Sortable 文檔詳盡但庫體積大、停止維護。新專案推薦 SortableJS,舊專案維護時本文參數表可速查。