[jQuery]UI/API/1.8/Draggable

以下是我參考了 jQuery  UI 1.8 API Draggable的部分，
如有錯誤請指正~




UI/API/1.8/Draggable

綜述

jQuery UI 的插件Draggable使得滑鼠能夠拖動選定的元素。
可拖動的元素會有一個類別：ui-draggable。在拖動的元素也會有一個類別：ui-draggable-dragging。
如果你不只是想要有drop的功能，而是drag-and-drop，可以參考jQuery UI的Droppable插件，它提供了接收draggable的drop方法。   
所有的回調（start,stop,drag）接受兩個參數：原始的瀏覽器事件(event)，ui對象，參考以下的內容（假設你把第二個參數稱為'UI'）：   

• 
  ui.helper - jQuery對象的helper，代表正在拖曳
  
• ui.position -helper目前的位置，以{ top, left }表示，指的是相對於原始目標的位置
• ui.offset -helper的絕對位置，以{ top, left } 表示，指的是相對於頁面的位置

選項

disable

型態：Boolean 預設值:false

禁用（true）或允許（false）物件可拖動。可以在初始化的時候設定（第一次創建）draggable。

Code examples

初始化draggable物件的 disabled選項

$( ".selector" ).draggable({ disabled: true });

在初始化之後取得或設定disabled選項

/ / 取得 var disabled = $( ".selector" ).draggable("option", "disabled" ); //設定 $( ".selector" ).draggable( "option","disabled", true );

addClasses

型態：Boolean 預設值:true

如果設置為false，就不會增加ui-draggable這個類別。這是以效能最佳化作為目標。draggable() 會對許多元素作初始化。

Code examples

初始化draggable物件的addClasses選項

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

在初始化之後取得或設定addClasses選項

//取得 var addClasses = $( ".selector" ).draggable("option", "addClasses" ); //設定 $( ".selector" ).draggable( "option", "addClasses",false );

appendTo

型態：Element, Selector 預設值:'parent'

傳入 appendTo 的元素或是由 appendTo選擇的元素在移動的時候會作為裝helper的容器預設情況下，helper拖曳會被附加在同一個容器。

Code examples

初始化draggable物件的appendTo選項

$( ".selector" ).draggable({ appendTo: 'body' });

在初始化之後取得或設定appendTo選項

//獲取 var appendTo = $( ".selector" ).draggable("option", "appendTo" ); //設定 $( ".selector" ).draggable( "option", "appendTo",'body' );

axis

型態：String 預設值:false

限制拖曳按照橫向（X）或垂直（Y）軸。可接受的值：'×'，'y'。

Code examples

初始化draggable物件的axis選項

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

在初始化之後取得或設定axis選項

//獲取 var axis = $( ".selector" ).draggable("option", "axis" ); //設定 $( ".selector" ).draggable( "option","axis", 'x' );

cancel

型態：Selector 預設值:':input,option'

防止在指定的元素上拖曳

Code examples

初始化draggable物件的cancel選項

$( ".selector" ).draggable({ cancel: 'button' });

在初始化之後取得或設定cancel選項

//獲取 var cancel = $( ".selector" ).draggable("option", "cancel" ); //設定 $( ".selector" ).draggable( "option","cancel", 'button' );

connectToSortable

型態：Selector 預設值:false

允許在拖曳到指定的sortables放開。 如果使用此選項（ helper 必須設定為'clone'，以正常的運作），一個可拖動可以被丟棄到一個可排序的列表(sortables)，然後成為它的一部分。

Code examples

初始化draggable物件的connectToSortable選項

$( ".selector" ).draggable({ connectToSortable: 'ul#myList' });

在初始化之後取得或設定connectToSortable選項

//獲取 var connectToSortable = $( ".selector" ).draggable("option","connectToSortable" ); //設定 $( ".selector" ).draggable("option","connectToSortable",'ul#myList' );

containment

型態：Selector,Element,String,Array 預設值:false

限制可拖曳的範圍。合法的參數：'parent', 'document', 'window', [x1, y1, x2, y2]

Code examples

初始化draggable物件的containment選項

$( ".selector" ).draggable({ containment: 'parent' });

在初始化之後取得或設定containment選項

//獲取 var containment = $( ".selector" ).draggable("option", "containment" ); //設定 $( ".selector" ).draggable( "option","containment", 'parent' );

cursor

型態：String 預設值:'auto'

指定draggable時的滑鼠指標型式。

Code examples

初始化draggable物件的cursor選項

$( ".selector" ).draggable({ cursor: 'crosshair' });

在初始化之後取得或設定cursor選項

//獲取 var containment = $( ".selector" ).draggable("option", "containment" ); //設定 $( ".selector" ).draggable( "option","containment", 'parent' );

cursor

型態：String 預設值:'auto'

指定draggable時的滑鼠指標型式。

Code examples

初始化draggable物件的cursor選項

$( ".selector" ).draggable({ cursor: 'crosshair' });

在初始化之後取得或設定cursor選項

//獲取 var cursor = $( ".selector" ).draggable("option", "cursor" ); //設定 $( ".selector" ).draggable( "option","cursor", 'crosshair' );

cursorAt

型態：Object 預設值:false

開始拖曳的時候，滑鼠指標會定位在某一個位置上。 座標最多能包含2個參數：   { top, left, right, bottom }。

Code examples

初始化draggable物件的cursorAt選項

$( ".selector" ).draggable({ cursorAt: { left: 5 } });

在初始化之後取得或設定cursorAt選項

//獲取 var cursorAt = $( ".selector" ).draggable("option", "cursorAt" ); //設定 $( ".selector" ).draggable( "option", "cursorAt",{ left: 5 } );

dealy

型態： Integer 預設值:0

滑鼠點下之後，延遲指定的時間之後才會啟動拖曳的動作(時間以毫秒為單位)。 這個選項可用來防止不小心的點擊。

Code examples

初始化draggable物件的dealy選項

$( ".selector" ).draggable({ delay: 500 });

在初始化之後取得或設定dealy選項

//獲取 var delay = $( ".selector" ).draggable("option", "delay" ); //設定 $( ".selector" ).draggable( "option","delay", 500 );

distance

型態： Integer 預設值:1

滑鼠要移動一段指定的距離(以像素為單位)之後，才會開始拖曳的動作。 這個選項是用來防止不小心的拖曳或誤點。

Code examples

初始化draggable物件的distance選項

$( ".selector" ).draggable({ distance: 30 });

在初始化之後取得或設定distance選項

//獲取 var distance = $( ".selector" ).draggable("option", "distance" ); //設定 $( ".selector" ).draggable( "option","distance", 30 );

grid

型態： Array 預設值:false

拖曳元素的時候，按照指定的格子大小像素移動。array的值：[x,y]

Code examples

初始化draggable物件的grid選項

$( ".selector" ).draggable({ grid: [50, 20] });

在初始化之後取得或設定grid選項

//獲取 var grid = $( ".selector" ).draggable("option", "grid" ); //設定 $( ".selector" ).draggable( "option","grid", [50, 20] );

handle

型態： Element,Selector 預設值:false

限制只能在拖曳元素內的指定元素開始拖曳

Code examples

初始化draggable物件的handle選項

$( ".selector" ).draggable({ handle: 'h2' });

在初始化之後取得或設定handle選項

//獲取 var handle = $( ".selector" ).draggable("option", "handle" ); //設定 $( ".selector" ).draggable( "option","handle", 'h2' );

helper

型態： String, Function 預設值:'original'

拖曳元素時的顯示樣式。 允許的參數：'original', 'clone', Function 如果指定Function，這個Function必須要回傳一個DOM元素

Code examples

初始化draggable物件的helper選項

$( ".selector" ).draggable({ helper: 'clone' });

在初始化之後取得或設定helper選項

//獲取 var helper = $( ".selector" ).draggable("option", "helper" ); //設定 $( ".selector" ).draggable( "option","helper", 'clone' );

iframeFix

型態： Boolean, Selector 預設值:false

防止在拖曳的時候，iframe內部事件捕捉到滑鼠移過的事件(mosemove)。 實用的時候會結合cursorAt，或是滑鼠指標沒有超過helper。 如果設置為true，會在iframe的範圍產生一層屏蔽。 如果指定了Selector，屏蔽就會覆蓋在對應的iframe上

Code examples

初始化draggable物件的iframeFix選項

$( ".selector" ).draggable({ iframeFix: true });

在初始化之後取得或設定iframeFix選項

//獲取 var iframeFix = $( ".selector" ).draggable("option", "iframeFix" ); //設定 $( ".selector" ).draggable( "option","iframeFix", true );

opacity

型態： Float 預設值:false

定義被拖曳的時候的透明度。

Code examples

初始化draggable物件的opacity選項

$( ".selector" ).draggable({ opacity: 0.35 });

在初始化之後取得或設定opacity選項

//獲取 var opacity = $( ".selector" ).draggable("option", "opacity" ); //設定 $( ".selector" ).draggable( "option","opacity", 0.35 );

refreshPositions

型態： Boolean 預設值:false

如果設置為 true，每次滑鼠移動的位置都會被記錄。 注意：此功能會大大降低性能。

Code examples

初始化draggable物件的refreshPositions選項

$( ".selector" ).draggable({ refreshPositions: true });

在初始化之後取得或設定refreshPositions選項

//獲取 var refreshPositions = $( ".selector" ).draggable("option", "refreshPositions" ); //設定 $( ".selector" ).draggable( "option","refreshPositions", true );

revert

型態： Boolean, String 預設值:false

如果設置為 true，當拖曳結束時，元素會回到起始的位置。 有效的參數： 'valid', 'invalid'。 如果設置為invalid，只會在無效droppable的時候回到起始位置。

Code examples

初始化draggable物件的revert選項

$( ".selector" ).draggable({ revert: true });

在初始化之後取得或設定revert選項

//獲取 var revert = $( ".selector" ).draggable("option", "revert" ); //設定 $( ".selector" ).draggable( "option","revert", true );

revertDuration

型態： Integer 預設值:500

當拖曳結束後，回到起始位置的時間(以毫秒為單位)。 若revert設定為false則無效。

Code examples

初始化draggable物件的revertDuration選項

$( ".selector" ).draggable({ revertDuration: 1000 });

在初始化之後取得或設定revertDuration選項

//獲取 var revertDuration = $( ".selector" ).draggable("option", "revertDuration" ); //設定 $( ".selector" ).draggable( "option","revertDuration", 1000 );

scope

型態： String 預設值:default

用於設定draggable和droppable物件的配套關係。 一個draggable物件和droppable的scope值相同就能接受droppable的動作。

Code examples

初始化draggable物件的scope選項

$( ".selector" ).draggable({ scope: 'tasks' });

在初始化之後取得或設定scope選項

//獲取 var scope = $( ".selector" ).draggable("option", "scope" ); //設定 $( ".selector" ).draggable( "option","scope", 'tasks' );

scroll

型態： Boolean 預設值:true

如果設定為 true，在拖曳到容器邊緣的時候，容器會自動捲動。

Code examples

初始化draggable物件的scroll選項

$( ".selector" ).draggable({ scroll: false });

在初始化之後取得或設定scroll選項

//獲取 var scroll = $( ".selector" ).draggable("option", "scroll" ); //設定 $( ".selector" ).draggable( "option","scroll", false );

scrollSensitivity

型態： Integer 預設值:20

拖曳到邊緣的時候一次滾動的像素。

Code examples

初始化draggable物件的scrollSensitivity選項

$( ".selector" ).draggable({ scrollSensitivity: 40 });

在初始化之後取得或設定scrollSensitivity選項

//獲取 var scrollSensitivity = $( ".selector" ).draggable("option", "scrollSensitivity" ); //設定 $( ".selector" ).draggable( "option","scrollSensitivity", 40 );

scrollSpeed

型態： Integer 預設值:20

拖曳到邊緣時，自動滾動的速度

Code examples

初始化draggable物件的scrollSpeed選項

$( ".selector" ).draggable({ scrollSpeed: 40 });

在初始化之後取得或設定scrollSpeed選項

//獲取 var scrollSpeed = $( ".selector" ).draggable("option", "scrollSpeed" ); //設定 $( ".selector" ).draggable( "option","scrollSpeed", 40 );

snap

型態： Boolean, Selector 預設值:false

如果設定為Selector，或設定為true（相當於'.ui-draggable'），當拖曳到元素邊緣時會被吸附到該元素。

Code examples

初始化draggable物件的snap選項

$( ".selector" ).draggable({ snap: true });

在初始化之後取得或設定snap選項

//獲取 var snap = $( ".selector" ).draggable("option", "snap" ); //設定 $( ".selector" ).draggable( "option","snap", true );

snapMode

型態： String 預設值:'both'

定義元素吸附的模式。 若snap設定為false時無效。 有效的參數：'inner', 'outer', 'both'

Code examples

初始化draggable物件的snapMode選項

$( ".selector" ).draggable({ snapMode: 'outer' });

在初始化之後取得或設定snapMode選項

//獲取 var snapMode = $( ".selector" ).draggable("option", "snapMode" ); //設定 $( ".selector" ).draggable( "option","snapMode", 'outer' );

snapTolerance

型態： Integer 預設值:20

拖曳至靠近距離元素指定距離(像素)時產生吸附的作用。若snap設定為false時無效。

Code examples

初始化draggable物件的snapTolerance選項

$( ".selector" ).draggable({ snapTolerance: 40 });

在初始化之後取得或設定snapTolerance選項

//獲取 var snapTolerance = $( ".selector" ).draggable("option", "snapTolerance" ); //設定 $( ".selector" ).draggable( "option","snapTolerance", 40 );

stack

型態：   Selector 預設值:false

控制物件的z-index值，會把拖曳的物件放在最前面。例如在window managers就很常用到。

Code examples

初始化draggable物件的stack選項

$( ".selector" ).draggable({ stack:".products" });

在初始化之後取得或設定stack選項

//獲取 var stack = $( ".selector" ).draggable("option", "stack" ); //設定 $( ".selector" ).draggable( "option","stack", ".products" );

zIndex

型態：   Integer 預設值:false

在拖曳時的z-index值。

Code examples

初始化draggable物件的zIndex選項

$( ".selector" ).draggable({ zIndex: 2700 });

在初始化之後取得或設定zIndex選項

//獲取 var zIndex = $( ".selector" ).draggable("option", "zIndex" ); //設定 $( ".selector" ).draggable( "option","zIndex", 2700 );

事件

start

型態： dragstart

當滑鼠拖曳開始時觸發這個事件。

Code examples

初始化draggable物件的start事件

$( ".selector" ).draggable({ start: function(event, ui) { ... }） ））;

由dragstart綁定start事件

$( ".selector" ).bind( "dragstart",function(event, ui) { ... ））;

drag

型態： drag

當滑鼠拖曳開始時觸發這個事件。

Code examples

初始化draggable物件的drag事件

$( ".selector" ).draggable({ drag: function(event, ui) { ... }） ））;

綁定drag事件

$( ".selector" ).bind( "drag",function(event, ui) { ... ））;

stop

型態： dragstop

當滑鼠拖曳時觸發這個事件。

Code examples

初始化draggable物件的stop事件

$( ".selector" ).draggable({ stop: function(event, ui) { ... }） ））;

綁定stop事件

$( ".selector" ).bind( "dragstop",function(event, ui) { ... ））;

方法

destroy

用法： draggable( "destroy" )

移除draggable的功能。把元素返回原始的初始狀態。

disable

用法： draggable( "disable" )

禁止draggable功能。

enable

用法： draggable( "enable" )

啟用draggable功能。

option

用法：draggable( "option" , optionName , [value] )

獲取或設置option。如果沒有指定值，將作為一個 getter。

option

用法：draggable( "option" , options )

一次設定多個oprion，必須傳入一個option物件。

widget

用法：draggable( "widget" )

返回.ui-draggable元素。