DIV CSS 佈局教程網

jQuery UI Draggable 拖曳外掛中文文件
編輯:JQuery特效代碼     

jQuery UI 的 Draggable 讓任何元素都能被滑鼠拖曳,是做出浮動視窗、看板、排序介面的基礎元件。本文整理它的選項、事件與方法,並標註各項的實務用途。

基本用法

$(".selector").draggable();

初始化後,元素會被加上 ui-draggable 樣式;拖曳過程中則加上 ui-draggable-dragging,可用來客製拖曳中的外觀。若需要的是完整的「拖放」(有放置目標),則要搭配 Droppable 外掛。

所有回呼函式都接受兩個參數:event(原生瀏覽器事件)與 ui(jQuery UI 物件)。ui 的常用屬性有:
ui.helper:正在拖動的元素包裝物件,ui.helper.context 可取得原生 DOM。
ui.position:相對於父元素的偏移,形如 {top, left}。
ui.offset:相對於瀏覽器可視區域左上角的偏移。兩者數值可能不同,因為 body 預設帶有 margin。

常用選項

axis(預設 false):限制拖曳方向。"x" 只能水平,"y" 只能垂直。

$(".selector").draggable({ axis: "x" });

containment(預設 false):限制可拖動的範圍。可傳 "parent"(限父容器內)、"document"(限文件內,超出會出現捲軸)、"window"(限視窗內,不出捲軸)、選擇器、元素,或 [x1, y1, x2, y2] 格式的座標陣列。

handle(預設 false):指定「用哪裡來拖」。這是最實用的選項之一——把視窗的標題列設為 handle,就只有抓標題列能拖動視窗,內容區仍可正常選取文字。該元素必須是可拖動元素的子元素。

$("#window").draggable({ handle: "#title" });

cancel(預設 ":input, option"):指定「哪裡不能拖」。清單中的按鈕、輸入框、下拉選單預設已被排除,避免干擾操作。

helper(預設 "original"):拖曳時跟著滑鼠移動的是什麼。"original" 是元素本身移動,"clone" 則是複製一個出來移動、原元素留在原位。也可傳函式,回傳自訂的 DOM 元素。

opacity:拖曳時 helper 的不透明度,0 到 1 之間。0.35 是常見設定,能讓底層內容透出來。

grid:[x, y] 格式的像素格線,讓元素以固定間距跳動移動。[50, 20] 代表每次水平 50px、垂直 20px。

delay / distance:防止誤觸的兩道防線。delay 是按住幾毫秒後才算有效拖曳,distance 是滑鼠必須移動幾像素才算有效。觸控裝置上建議把 distance 調大一點,避免與捲動手勢衝突。

revert / revertDuration:放開滑鼠後是否回到原處。true 一定回歸,"valid" 表示只有成功放入 droppable 時才不回歸,"invalid" 反之。revertDuration 是回歸動畫的毫秒數,預設 500。

scope(預設 "default"):與 Droppable 的搭配用的命名空間。只有 scope 相同的 draggable 與 droppable 才能互相放置,即使 droppable 的 accept 設為 "*" 也一樣受此限制。

snap / snapMode / snapTolerance:吸附功能。snap: true 等同 ".ui-draggable";snapMode 可為 "inner"(在目標內部吸附)、"outer"(外部)、"both";snapTolerance 是距離目標邊緣幾像素時觸發吸附,預設 20。

stack:{group: '.selector', min: 50} 格式,讓同一組元素中「目前正在拖的那個永遠在最上層」。做卡片或視窗管理時非常有用,省去自己維護 z-index 的麻煩。

zIndex:拖曳時 helper 的層級。

scroll / scrollSensitivity / scrollSpeed:拖曳到容器邊緣時是否自動捲動、多靠近才觸發(預設 20px)、每次捲多少(預設 20px)。

addClasses(預設 true):是否加上 ui-draggable 樣式。一次初始化數百個元素時設為 false 可提升效能,但不影響拖曳中的 ui-draggable-dragging 樣式。

iframeFix:解決拖曳時滑鼠移入 iframe 導致 mousemove 中斷的問題。設為 true 會對所有 iframe 加上遮罩,也可傳選擇器只處理特定的。

refreshPositions:設為 true 時每次 mousemove 都重新計算所有 droppable 的位置。效能開銷大,只在動態變化的版面中才需要,一般情況應保持 false。

cursor / cursorAt:cursor 設定拖曳時的滑鼠樣式(元素本身必須支援該樣式);cursorAt 以 {top, left, right, bottom} 指定滑鼠相對元素左上角的偏移位置。

事件

start(類型 dragstart):拖曳開始。
drag(類型 drag):拖曳過程中滑鼠移動。
stop(類型 dragstop):拖曳結束。

兩種綁定方式:

// 初始化時設定
$(".selector").draggable({
    start: function (event, ui) { console.log(ui.position); }
});

// 事後動態綁定(事件名即事件類型)
$(".selector").bind('drag', function (event, ui) {
    console.log(ui.offset);
});

方法

$(".selector").draggable("destroy");   // 完全移除,回到初始化前的狀態
$(".selector").draggable("disable");    // 暫時停用
$(".selector").draggable("enable");     // 恢復可用
$(".selector").draggable("option", "axis");        // 讀取選項
$(".selector").draggable("option", "axis", "y");   // 設定選項

一個實用的組合範例

$("#win").draggable({
    handle: "#winTitle",        // 只能抓標題列拖
    containment: "window",      // 不可拖出視窗
    opacity: 0.75,              // 拖曳時半透明
    stack: { group: ".win", min: 100 },   // 目前正在拖的在最上層
    revert: "invalid"           // 放到無效位置會弹回
});

這組設定幾乎就是「可拖曳視窗」的標準配方:標題列為把手、限制在視窗內、半透明提示、自動管理層級、無效位置弹回。

版本提醒

本文描述的是 jQuery UI 1.7 系列的行為。後續版本中,$.browser 等相依 API 已被移除,jQuery UI 也自 1.12 起逐步擺脫這類依賴;1.13 之後官方開始提供不含 jQuery 依賴的獨立版本。若在新專案中使用,建議直接採用目前的穩定版並查閱對應版本的官方文件,因為少數選項的預設值與名稱曾有調整。另外,拖曳功能在觸控裝置上的體驗需要搭配 touchstart/touchend 處理(或使用 jQuery UI Touch Punch 這類補丁),而純滑鼠實作在行動裝置上是完全無法操作的。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved