萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery UI Sortable 拖拽排序完整參數與事件詳解:從入門到進階

jQuery UI Sortable 是經典拖拽排序庫。本文系統整理所有選項、事件、方法,附帶實戰配置範例(跨列表拖拽、網格對齊、動畫回彈、滾動容器、自定義手柄),適合直接複製調參。

核心選項速查表

選項類型預設說明
appendToString'parent'輔助元素掛載容器,解決 z-index 遮蓋
axis'x'|'y'|falsefalse限制拖拽方向
cancelSelector':input,button'禁止拖拽的元素(如輸入框)
connectWithSelectorfalse連接其他 sortable 列表,實現跨列表拖拽
containmentSelector/Elementfalse限制拖拽範圍('parent', 'document', 'window')
cursorString'auto'拖拽時游標樣式
cursorAtObjectfalse游標相對輔助元素位置 `{top, left}`
delayInteger0延遲啟動 ms,防誤觸
distanceInteger1最小拖拽距離觸發排序 px
dropOnEmptyBooleantrue允許拖入空列表
forceHelperSizeBooleanfalse強制輔助元素有尺寸
forcePlaceholderSizeBooleanfalse強制佔位符有尺寸
grid[x, y]false網格對齊步進
handleSelector/Elementfalse拖拽手柄(如 '.drag-handle')
helper'original'|'clone'|Function'original'輔助元素類型,clone 可避免原元素位移
itemsSelector'> *'可排序子元素選取器
opacityFloatfalse輔助元素透明度
placeholderStringfalse佔位符 CSS 類別
revertBoolean/Integerfalse放置時動畫回彈 ms
scrollBooleantrue邊緣自動滾動容器
scrollSensitivityInteger20觸發滾動邊距 px
scrollSpeedInteger20滾動速度 px/ms
tolerance'intersect'|'pointer''intersect'判定重疊方式:50%面積 或 指標重疊
zIndexInteger1000輔助元素 z-index

事件回調參數

所有回調接收 `(event, ui)`,`ui` 物件屬性:

  • `ui.helper` - 輔助元素 jQuery 物件
  • `ui.position` - 相對父元素位置 `{top, left}`
  • `ui.offset` - 相對文檔位置 `{top, left}`
  • `ui.item` - 當前拖拽的原始元素
  • `ui.placeholder` - 佔位符元素
  • `ui.sender` - 來源 sortable (跨列表時)

關鍵事件

事件觸發時機
create初始化完成
start開始拖拽
sort拖拽中 (高頻,慎做重運算)
changeDOM 位置實際改變時
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...' 供後端

現代替代方案

  • SortableJS:零依賴、支援觸控、Tree/多欄/動畫、框架無關,現代首選。
  • @dnd-kit (React)、Vue Draggable:框架深度整合、TypeScript、無障礙。
  • HTML5 Drag & Drop API:原生、無依賴,但 API 反直覺、行為怪異(需 `draggable=true`、`dataTransfer`)。

jQuery UI Sortable 文檔詳盡但庫體積大、停止維護。新專案推薦 SortableJS,舊專案維護時本文參數表可速查。

copyright © 萬盛學電腦網 all rights reserved