DIV CSS 佈局教程網

jQuery UI Draggable 插件中文文件:選項、事件與方法完整解析
編輯:JQuery特效代碼     

jQuery UI 的 Draggable 插件讓指定元素可以用滑鼠拖曳。它會為元素加上 ui-draggable 類別,拖曳過程中再加上 ui-draggable-dragging,方便你用 CSS 給不同的視覺回饋。若你要的不只是「拖得動」,而是完整的拖放(drag & drop)行為,還需要搭配 Droppable 插件,由它提供放置目標。

回呼函式的參數

所有回呼(start、stop、drag 等)都接受兩個參數:

event:瀏覽器原生事件物件。

ui:一個包含以下常用屬性的 ui 物件:

ui.helper:正在拖動的元素的 jQuery 包裝物件,ui.helper.context 可取得原生 DOM 元素。

ui.position:相對於父元素(若為頂層則是 body)的偏移,形如 {top, left},可用 ui.position.top 取得目前偏移。

ui.offset:相對於瀏覽器內容區域左上角的偏移。注意是內容區域,而非 body——body 在預設情況下本身就帶有邊界偏移,兩者並不相同。

常用選項

addClasses(Boolean,預設 true):是否為元素加上 ui-draggable 樣式。一次初始化數百個元素時,關掉它可以省下可觀的效能,但不影響拖曳過程中的 ui-draggable-dragging。

$('.selector').draggable({ addClasses: false });

appendTo(Element / Selector,預設 'parent'):指定拖曳過程中 helper 的所屬容器。預設與原元素同層。

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

cancel(Selector,預設 ':input, option'):指定哪些子元素不可作為拖曳起點,避免在輸入框或下拉選單上按下時誤觸拖曳。

containment(Selector / Element / String / Array,預設 false):限制可拖動的範圍。字串形式有 'parent'(限父容器內)、'document'(整個文件,超出視窗時會出現捲軸)、'window'(限目前視窗內容區域,不會產生捲軸);陣列形式 [x1, y1, x2, y2] 以「起始水平、起始垂直、結束水平、結束垂直」劃出一個矩形區域,座標相對於視窗內容區左上角。

cursor(String,預設 'auto'):拖曳過程中的滑鼠樣式。若元素本身不支援該 cursor,會退回顯示元素預設的樣式。

cursorAt(Object,預設 false):滑鼠在 helper 上的顯示位置。設為 {left: 8, top: 8} 時,滑鼠會固定出現在距左上角各 8 像素處,拖起來手感比較像「抓著一個角」。

delay(毫秒,預設 0):從按下左鍵到實際開始拖動的延遲時間。按住超過這個時間才算有效拖曳,可用來避免誤點。

distance(像素,預設 1):從按下左鍵到開始拖動所需的滑鼠位移。同樣是防誤觸的手段,設定 5 到 10 通常手感最好。

grid([x, y],預設 false):以格線方式移動,每次位移固定為指定的像素量,適合對齊式的版面配置。

handle(Selector / Element,預設 false):指定拖曳把手。若希望整個視窗只有標題列可以拖,就把 handle 指向標題元素;該元素必須是 draggable 的後代。

helper(String / Function,預設 'original'):'original' 讓元素本身移動,'clone' 則複製一個分身移動、原件留在原位;也可以傳入函式回傳自訂的 DOM 元素。

iframeFix(Boolean / Selector,預設 false):避免拖曳時滑鼠移到 iframe 上造成 mousemove 中斷。設為 true 會攔住頁面上所有 iframe,也可指定選擇器只處理特定的。

opacity(Float,預設 false):helper 的不透明度,設 0.35 左右能讓底層內容隱約可見,是常見的做法。

refreshPositions(Boolean,預設 false):設為 true 時每次 mousemove 都重新計算所有 droppable 的位置。能解決動態版面下放置判斷失準的問題,但成本很高,非必要不要開。

revert(Boolean / 'valid' / 'invalid',預設 false):拖完是否回到原處。true 一律回歸;'invalid' 表示只有成功放入 droppable 時才留在新位置;'valid' 則相反。

revertDuration(毫秒,預設 500):回歸動畫的時間,revert 為 false 時無效。

scope(String,預設 'default'):分組用的命名空間,需與 droppable 的 accept 搭配。只有 scope 相同的 draggable 與 droppable 才能配對:

$('#draggable_a').draggable({ scope: 'a' });
$('#draggable_b').draggable({ scope: 'b' });
$('#droppable_a').droppable({ scope: 'a' });
$('#droppable_b').droppable({ scope: 'b' });

droppable 的 accept 預設是 '*',看似什麼都能放,但 scope 不同就不行。即使不特別設定,所有元素仍有名為 default 的 scope。

scroll(Boolean,預設 true):拖曳超出容器時自動出現捲軸。scrollSensitivity(預設 20)是滑鼠距容器邊多近時開始滾動,scrollSpeed(預設 20)是每次滾動的像素數。

snap(Boolean / Selector,預設 false):吸附。設為 true 等同指定 .ui-draggable,靠近目標時自動吸過去。snapMode 可為 'inner'(在目標內部吸附)、'outer'(外部)、'both'(預設);snapTolerance(預設 20)是距離多少像素時觸發吸附。

stack({group, min},預設 false):讓被拖動的元素始終顯示在最上層。group 是共用的選擇器,min 指定 z-index 的下限:

$('.selector').draggable({ stack: { group: 'products', min: 50 } });

zIndex(Integer,預設 false):helper 的 z-index 明確值。

事件

start(dragstart):拖曳開始。drag:拖曳中滑鼠移動。stop(dragstop):拖曳結束。三者回呼都收到 event、ui,並以 this 指向被拖動的 DOM 元素。

// 初始化時設定
$('.selector').draggable({
    start: function(event, ui) { alert(this); },
    drag:  function(event, ui) { alert(this); },
    stop:  function(event, ui) { alert(this); }
});

// 動態綁定,事件名即事件型別
$(".selector").bind('dragstart', function(event, ui) { alert(this); });
$(".selector").bind('drag',      function(event, ui) { alert(this); });
$(".selector").bind('dragstop',  function(event, ui) { alert(this); });

方法

destroy:完全移除拖曳功能,讓元素回到初始化之前的狀態。

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

disable / enable:暫時關閉或恢復拖曳能力,外觀樣式會一併切換。

option:取得或設定選項。第二個參數是選項名,有第三個參數就是設定,沒有就是取得。

var axis = $('.selector').draggable('option', 'axis');
$('.selector').draggable('option', 'axis', 'x');

選項速查

addClasses 決定是否加樣式類別;appendTo 決定 helper 掛在哪裡;axis 決定拖曳方向;cancel 與 handle 一組,前者劃出不可拖的區域,後者指定拖曳把手;connectToSortable 需與 sortable 搭配使用;containment 划定活動範圍;cursor 與 cursorAt 控制滑鼠外觀與位置;delay 與 distance 用來過濾誤觸;grid 決定移動的最小單位;helper 決定跟著滑鼠走的是誰;iframeFix 處理與 iframe 的層疊事件;opacity 控制 helper 透明度;refreshPositions 讓每次移動都重算放置位置;revert 與 revertDuration 控制回歸行為;scope 決定與 droppable 的配對關係;scroll 系列處理自動捲動;snap 系列處理吸附;stack 與 zIndex 決定層級。

實際使用時最值得先調的三個是 distance(手感)、containment(避免元素被拖出畫面)與 helper(決定是搬動原件還是留下佔位),這三者往往就決定了整體互動是否自然。

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