jQuery UI API - 可拖拽小部件(Draggable Widget)

所屬類別

交互(Interactions)

用法

描述:允許使用鼠標移動元素。

版本新增:1.0

依賴:

注釋:讓被選元素可被鼠標拖拽。如果您不只是拖拽,而是拖拽 & 放置,請查看 jQuery UI 可放置(Droppable)插件,為可拖拽元素提供了一個放置目標。

快速導航

選項 方法 事件

選項 類型 描述 默認值
addClasses Boolean 如果設(shè)置為 false,將阻止 ui-draggable class 被添加。當在數(shù)百個元素上調(diào)用 .draggable() 時,這么設(shè)置有利于性能優(yōu)化。

代碼實例:

初始化帶有指定 addClasses 選項的 draggable:

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

在初始化后,獲取或設(shè)置 addClasses 選項:

// getter
var addClasses = $( ".selector" ).draggable( "option", "addClasses" );
 
// setter
$( ".selector" ).draggable( "option", "addClasses", false );
	
true
appendTo jQuery 或 Element 或 Selector 或 String 當拖拽時,draggable 助手(helper)要追加到哪一個元素。

支持多個類型:

  • jQuery:一個 jQuery 對象,包含助手(helper)要追加到的元素。
  • Element:要追加助手(helper)的元素。
  • Selector:一個選擇器,指定哪一個元素要追加助手(helper)。
  • String:字符串 "parent" 將促使助手(helper)成為 draggable 的同級。

代碼實例:

初始化帶有指定 appendTo 選項的 draggable:

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

在初始化后,獲取或設(shè)置 appendTo 選項:

// getter
var appendTo = $( ".selector" ).draggable( "option", "appendTo" );
 
// setter
$( ".selector" ).draggable( "option", "appendTo", "body" );
	
"parent"
axis String 約束在水平軸 (x) 或垂直軸 (y) 上拖拽。可能的值:"x", "y"。

代碼實例:

初始化帶有指定 axis 選項的 draggable:

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

在初始化后,獲取或設(shè)置 axis 選項:

// getter
var axis = $( ".selector" ).draggable( "option", "axis" );
 
// setter
$( ".selector" ).draggable( "option", "axis", "x" );
	
false
cancel Selector 防止從指定的元素上開始拖拽。

代碼實例:

初始化帶有指定 cancel 選項的 draggable:

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

在初始化后,獲取或設(shè)置 cancel 選項:

// getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );
 
// setter
$( ".selector" ).draggable( "option", "cancel", ".title" );
	
"input, textarea, button, select, option"
connectToSortable Selector 允許 draggable 放置在指定的 sortable 上。如果使用了該選項,一個 draggable 可被放置在一個 sortable 列表上,然后成為列表的一部分。注意:helper 選項必須設(shè)置為 "clone",以便更好地工作。必須包含 可排序小部件(Sortable Widget)。

代碼實例:

初始化帶有指定 connectToSortable 選項的 draggable:

$( ".selector" ).draggable({ connectToSortable: "#my-sortable" });
	

在初始化后,獲取或設(shè)置 connectToSortable 選項:

// getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );
 
// setter
$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );
	
false
containment Selector 或 Element 或 String 或 Array 約束在指定元素或區(qū)域的邊界內(nèi)拖拽。

支持多個類型:

  • Selector:可拖拽元素將被包含在 selector 第一個元素的邊界內(nèi)。如果未找到元素,則不設(shè)置 containment。
  • Element:可拖拽元素將被韓寒在元素的邊界。
  • String:可能的值:"parent"、"document"、"window"。
  • Array:一個數(shù)組, 以形式 [ x1, y1, x2, y2 ] 定義元素的邊界。

代碼實例:

初始化帶有指定 containment 選項的 draggable:

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

在初始化后,獲取或設(shè)置 containment 選項:

// getter
var containment = $( ".selector" ).draggable( "option", "containment" );
 
// setter
$( ".selector" ).draggable( "option", "containment", "parent" );
	
false
cursor String 拖拽操作期間的 CSS 光標。

代碼實例:

初始化帶有指定 cursor 選項的 draggable:

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

在初始化后,獲取或設(shè)置 cursor 選項:

// getter
var cursor = $( ".selector" ).draggable( "option", "cursor" );
 
// setter
$( ".selector" ).draggable( "option", "cursor", "crosshair" );
	
"auto"
cursorAt Object 設(shè)置拖拽助手(helper)相對于鼠標光標的偏移。坐標可通過一個或兩個鍵的組合成一個哈希給出:{ top, left, right, bottom }

代碼實例:

初始化帶有指定 cursorAt 選項的 draggable:

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

在初始化后,獲取或設(shè)置 cursorAt 選項:

// getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );
 
// setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );
	
false
delay Number 鼠標按下后直到拖拽開始為止的時間,以毫秒計。該選項可以防止點擊在某個元素上時不必要的拖拽。

代碼實例:

初始化帶有指定 delay 選項的 draggable:

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

在初始化后,獲取或設(shè)置 delay 選項:

// getter
var delay = $( ".selector" ).draggable( "option", "delay" );
 
// setter
$( ".selector" ).draggable( "option", "delay", 300 );
	
0
disabled Boolean 如果設(shè)置為 true,則禁用該 draggable。

代碼實例:

初始化帶有指定 disabled 選項的 draggable:

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

在初始化后,獲取或設(shè)置 disabled 選項:

// getter
var disabled = $( ".selector" ).draggable( "option", "disabled" );
 
// setter
$( ".selector" ).draggable( "option", "disabled", true );
	
false
distance Number 鼠標按下后拖拽開始前必須移動的距離,以像素計。該選項可以防止點擊在某個元素上時不必要的拖拽。

代碼實例:

初始化帶有指定 distance 選項的 draggable:

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

在初始化后,獲取或設(shè)置 distance 選項:

// getter
var distance = $( ".selector" ).draggable( "option", "distance" );
 
// setter
$( ".selector" ).draggable( "option", "distance", 10 );
	
1
grid Array 對齊拖拽助手(helper)到網(wǎng)格,每個 x 和 y 像素。數(shù)組形式必須是 [ x, y ]

代碼實例:

初始化帶有指定 grid 選項的 draggable:

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

在初始化后,獲取或設(shè)置 grid 選項:

// getter
var grid = $( ".selector" ).draggable( "option", "grid" );
 
// setter
$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );
	
false
handle Selector 或 Element 如果指定了該選項,則限制開始拖拽,除非鼠標在指定的元素上按下。只有可拖拽(draggable)元素的后代元素才允許被拖拽。

代碼實例:

初始化帶有指定 handle 選項的 draggable:

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

在初始化后,獲取或設(shè)置 handle 選項:

// getter
var handle = $( ".selector" ).draggable( "option", "handle" );
 
// setter
$( ".selector" ).draggable( "option", "handle", "h2" );
	
false
helper String 或 Function() 允許一個 helper 元素用于拖拽顯示。

支持多個類型:

  • String:如果設(shè)置為 "clone",元素將被克隆,且克隆將被拖拽。
  • Function:一個函數(shù),將返回拖拽時要使用的 DOMElement。

代碼實例:

初始化帶有指定 helper 選項的 draggable:

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

在初始化后,獲取或設(shè)置 helper 選項:

// getter
var helper = $( ".selector" ).draggable( "option", "helper" );
 
// setter
$( ".selector" ).draggable( "option", "helper", "clone" );
	
"original"
iframeFix Boolean 或 Selector 防止拖拽期間 iframes 捕捉鼠標移動(mousemove )事件。在與 cursorAt 選項結(jié)合使用時,或鼠標光標未覆蓋在助手(helper)上時,非常有用。

支持多個類型:

  • Boolean:當設(shè)置為 true 時,透明遮罩將被放置在頁面上所有 iframes 上。
  • Selector:匹配 selector 的任意 iframes 將被透明遮罩覆蓋。

代碼實例:

初始化帶有指定 iframeFix 選項的 draggable:

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

在初始化后,獲取或設(shè)置 iframeFix 選項:

// getter
var iframeFix = $( ".selector" ).draggable( "option", "iframeFix" );
 
// setter
$( ".selector" ).draggable( "option", "iframeFix", true );
	
false
opacity Number 當被拖拽時助手(helper)的不透明度。

代碼實例:

初始化帶有指定 opacity 選項的 draggable:

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

在初始化后,獲取或設(shè)置 opacity 選項:

// getter
var opacity = $( ".selector" ).draggable( "option", "opacity" );
 
// setter
$( ".selector" ).draggable( "option", "opacity", 0.35 );
	
false
refreshPositions Boolean 如果設(shè)置為 true,在每次鼠標移動(mousemove)時都會計算所有可放置的位置。注意:這解決了高度動態(tài)的問題,但是明顯降低了性能。

代碼實例:

初始化帶有指定 refreshPositions 選項的 draggable:

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

在初始化后,獲取或設(shè)置 refreshPositions 選項:

// getter
var refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" );
 
// setter
$( ".selector" ).draggable( "option", "refreshPositions", true );
	
false
revert Boolean 或 String 或 Function() 當拖拽停止時,元素是否還原到它的開始位置。

支持多個類型:

  • Boolean:如果設(shè)置為 true,元素總會還原。
  • String:如果設(shè)置為 "invalid",還原僅在 draggable 未放置在 droppable 上時發(fā)生,如果設(shè)置為 "valid" 則相反。
  • Function:一個函數(shù),確定元素是否還原到它的開始位置。該函數(shù)必須返回 true 才能還原元素。

代碼實例:

初始化帶有指定 revert 選項的 draggable:

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

在初始化后,獲取或設(shè)置 revert 選項:

// getter
var revert = $( ".selector" ).draggable( "option", "revert" );
 
// setter
$( ".selector" ).draggable( "option", "revert", true );
	
false
revertDuration Number 還原(revert)動畫的持續(xù)時間,以毫秒計。如果 revert 選項是 false 則忽略。

代碼實例:

初始化帶有指定 revertDuration 選項的 draggable:

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

在初始化后,獲取或設(shè)置 revertDuration 選項:

// getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );
 
// setter
$( ".selector" ).draggable( "option", "revertDuration", 200 );
	
500
scope String 用于組合配套 draggable 和 droppable 項,除了 droppable 的 accept 選項之外。一個與 droppable 帶有相同的 scope 值的 draggable 會被該 droppable 接受。

代碼實例:

初始化帶有指定 scope 選項的 draggable:

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

在初始化后,獲取或設(shè)置 scope 選項:

// getter
var scope = $( ".selector" ).draggable( "option", "scope" );
 
// setter
$( ".selector" ).draggable( "option", "scope", "tasks" );
	
"default"
scroll Boolean 如果設(shè)置為 true,當拖拽時容器會自動滾動。

代碼實例:

初始化帶有指定 scroll 選項的 draggable:

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

在初始化后,獲取或設(shè)置 scroll 選項:

// getter
var scroll = $( ".selector" ).draggable( "option", "scroll" );
 
// setter
$( ".selector" ).draggable( "option", "scroll", false );
	
true
scrollSensitivity Number 從要滾動的視區(qū)邊緣起的距離,以像素計。距離是相對于指針的,不是相對于 draggable。如果 scroll 選項是 false 則忽略。

代碼實例:

初始化帶有指定 scrollSensitivity 選項的 draggable:

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

在初始化后,獲取或設(shè)置 scrollSensitivity 選項:

// getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );
 
// setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );
	
20
scrollSpeed Number 當鼠標指針獲取到在 scrollSensitivity 距離內(nèi)時,窗體滾動的速度。如果 scroll 選項是 false 則忽略。

代碼實例:

初始化帶有指定 scrollSpeed 選項的 draggable:

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

在初始化后,獲取或設(shè)置 scrollSpeed 選項:

// getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );
 
// setter
$( ".selector" ).draggable( "option", "scrollSpeed", 100 );
	
20
snap Boolean 或 Selector 元素是否對齊到其他元素。

支持多個類型:

  • Boolean:當設(shè)置為 true 時,元素會對齊到其它可拖拽(draggable )元素。
  • Selector:一個選擇器,指定要對齊到哪個元素。

代碼實例:

初始化帶有指定 snap 選項的 draggable:

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

在初始化后,獲取或設(shè)置 snap 選項:

// getter
var snap = $( ".selector" ).draggable( "option", "snap" );
 
// setter
$( ".selector" ).draggable( "option", "snap", true );
	
false
snapMode String 決定 draggable 將對齊到對齊元素的哪個邊緣。如果 snap 選項是 false 則忽略??赡艿闹担?code>"inner"、"outer"、"both"。

代碼實例:

初始化帶有指定 snapMode 選項的 draggable:

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

在初始化后,獲取或設(shè)置 snapMode 選項:

// getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );
 
// setter
$( ".selector" ).draggable( "option", "snapMode", "inner" );
	
"both"
snapTolerance Number 從要發(fā)生對齊的對齊元素邊緣起的距離,以像素計。如果 snap 選項是 false 則忽略。

代碼實例:

初始化帶有指定 snapTolerance 選項的 draggable:

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

在初始化后,獲取或設(shè)置 snapTolerance 選項:

// getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );
 
// setter
$( ".selector" ).draggable( "option", "snapTolerance", 30 );
	
20
stack Selector 控制匹配選擇器(selector)的元素集合的 z-index,總是在當前拖拽項的前面,在類似窗口管理器這樣的事物中非常有用。

代碼實例:

初始化帶有指定 stack 選項的 draggable:

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

在初始化后,獲取或設(shè)置 stack 選項:

// getter
var stack = $( ".selector" ).draggable( "option", "stack" );
 
// setter
$( ".selector" ).draggable( "option", "stack", ".products" );
	
false
zIndex Number 當被拖拽時,助手(helper)的 Z-index。

代碼實例:

初始化帶有指定 zIndex 選項的 draggable:

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

在初始化后,獲取或設(shè)置 zIndex 選項:

// getter
var zIndex = $( ".selector" ).draggable( "option", "zIndex" );
 
// setter
$( ".selector" ).draggable( "option", "zIndex", 100 );
	
false

方法 返回 描述
destroy() jQuery (plugin only) 完全移除 draggable 功能。這會把元素返回到它的預初始化狀態(tài)。
  • 該方法不接受任何參數(shù)。

代碼實例:

調(diào)用 destroy 方法:

$( ".selector" ).draggable( "destroy" );
	
disable() jQuery (plugin only) 禁用 draggable。
  • 該方法不接受任何參數(shù)。

代碼實例:

調(diào)用 disable 方法:

$( ".selector" ).draggable( "disable" );
	
enable() jQuery (plugin only) 啟用 draggable。
  • 該方法不接受任何參數(shù)。

代碼實例:

調(diào)用 enable 方法:

$( ".selector" ).draggable( "enable" );
	
option( optionName ) Object 獲取當前與指定的 optionName 關(guān)聯(lián)的值。
  • optionName
    類型:String
    描述:要獲取的選項的名稱。

代碼實例:

調(diào)用該方法:

var isDisabled = $( ".selector" ).draggable( "option", "disabled" );
	
option() PlainObject 獲取一個包含鍵/值對的對象,鍵/值對表示當前 draggable 選項哈希。
  • 該方法不接受任何參數(shù)。

代碼實例:

調(diào)用該方法:

var options = $( ".selector" ).draggable( "option" );
	
option( optionName, value ) jQuery (plugin only) 設(shè)置與指定的 optionName 關(guān)聯(lián)的 draggable 選項的值。
  • optionName
    類型:String
    描述:要設(shè)置的選項的名稱。
  • value
    類型:Object
    描述:要為選項設(shè)置的值。

代碼實例:

調(diào)用該方法:

$( ".selector" ).draggable( "option", "disabled", true );
	
option( options ) jQuery (plugin only) 為 draggable 設(shè)置一個或多個選項。
  • options
    類型:Object
    描述:要設(shè)置的 option-value 對。

代碼實例:

調(diào)用該方法:

$( ".selector" ).draggable( "option", { disabled: true } );
	
widget() jQuery 返回一個包含 draggable 元素的 jQuery 對象。
  • 該方法不接受任何參數(shù)。

代碼實例:

調(diào)用 widget 方法:

var widget = $( ".selector" ).draggable( "widget" );
	

事件 類型 描述
create( event, ui ) dragcreate 當 draggable 被創(chuàng)建時觸發(fā)。
  • event
    類型:Event
  • ui
    類型:Object

注意:ui 對象是空的,這里包含它是為了與其他事件保持一致性。

代碼實例:

初始化帶有指定 create 回調(diào)的 draggable:

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

綁定一個事件監(jiān)聽器到 dragcreate 事件:

$( ".selector" ).on( "dragcreate", function( event, ui ) {} );
	
drag( event, ui ) drag 在拖拽期間當鼠標移動時觸發(fā)。
  • event
    類型:Event
  • ui
    類型:Object
    • helper
      類型:jQuery
      描述:jQuery 對象,表示被拖拽的助手(helper)。
    • position
      類型:Object
      描述:助手(helper)的當前 CSS 位置,比如 { top, left } 對象。
    • offset
      類型:Object
      描述:助手(helper)的當前偏移位置,比如 { top, left } 對象。

代碼實例:

初始化帶有指定 drag 回調(diào)的 draggable:

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

綁定一個事件監(jiān)聽器到 drag 事件:

$( ".selector" ).on( "drag", function( event, ui ) {} );
	
start( event, ui ) dragstart 當拖拽開始時觸發(fā)。
  • event
    類型:Event
  • ui
    類型:Object
    • helper
      類型:jQuery
      描述:jQuery 對象,表示被拖拽的助手(helper)。
    • position
      類型:Object
      描述:助手(helper)的當前 CSS 位置,比如 { top, left } 對象。
    • offset
      類型:Object
      描述:助手(helper)的當前偏移位置,比如 { top, left } 對象。

代碼實例:

初始化帶有指定 start 回調(diào)的 draggable:

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

綁定一個事件監(jiān)聽器到 dragstart 事件:

$( ".selector" ).on( "dragstart", function( event, ui ) {} );
	
stop( event, ui ) dragstop 當拖拽停止時觸發(fā)。
  • event
    類型:Event
  • ui
    類型:Object
    • helper
      類型:jQuery
      描述:jQuery 對象,表示被拖拽的助手(helper)。
    • position
      類型:Object
      描述:助手(helper)的當前 CSS 位置,比如 { top, left } 對象。
    • offset
      類型:Object
      描述:助手(helper)的當前偏移位置,比如 { top, left } 對象。

代碼實例:

初始化帶有指定 stop 回調(diào)的 draggable:

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

綁定一個事件監(jiān)聽器到 dragstop 事件:

$( ".selector" ).on( "dragstop", function( event, ui ) {} );
	

實例

一個簡單的 jQuery UI 可拖拽小部件(Draggable Widget)。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>可拖拽小部件(Draggable Widget)演示</title>
  <link rel="stylesheet"  rel="external nofollow" target="_blank" >
  <style>
  #draggable {
    width: 100px;
    height: 100px;
    background: #ccc;
  }
  </style>
  <script src="http://code.jquery.com/jquery-1.10.2.js" rel="external nofollow" ></script>
  <script src="http://code.jquery.com/ui/1.10.4/jquery-ui.js" rel="external nofollow" ></script>
</head>
<body>
 
<div id="draggable">請拖拽我!</div>
 
<script>
$( "#draggable" ).draggable();
</script>
 
</body>
</html>

查看演示