jQuery UI API - Widget arrastrable (Draggable Widget)

Categoría

Interacciones (Interactions)

Uso

Descripción:Permite mover elementos con el mouse.

Agregado en la versión:1.0

Dependencias:

Notas:Hace que los elementos seleccionados se puedan arrastrar con el mouse. Si no solo necesita arrastrar, sino arrastrar y soltar (drag & drop), consulteel complemento Droppable de jQuery UI, que proporciona un destino de colocación para los elementos arrastrables.

Navegación rápida

Opciones Métodos Eventos

Opciones Tipo Descripción Valor por defecto
addClasses Boolean Si se establece afalse, se evitaráui-draggableque se agregue la clase. Cuando se llama a.draggable()en cientos de elementos, esta configuración favorece la optimización del rendimiento.

Ejemplo de código:

Inicializar el draggable con laaddClassesopción especificada:

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

Después de la inicialización, obtener o establecer laaddClassesopción:

// getter
var addClasses = $( ".selector" ).draggable( "option", "addClasses" );
 
// setter
$( ".selector" ).draggable( "option", "addClasses", false );
    
true
appendTo jQuery o Element o Selector o String El elemento al que se debe agregar el helper del draggable mientras se arrastra.

Soporta múltiples tipos:

  • jQuery: un objeto jQuery que contiene el elemento al que se agregará el helper.
  • Element: el elemento al que se agregará el helper.
  • Selector: un selector que especifica a qué elemento se agregará el helper.
  • String: String"parent"hará que el helper sea un hermano del draggable.

Ejemplo de código:

Inicializar el draggable con laappendToopción especificada:

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

Después de la inicialización, obtener o establecer laappendToopción:

// getter
var appendTo = $( ".selector" ).draggable( "option", "appendTo" );
 
// setter
$( ".selector" ).draggable( "option", "appendTo", "body" );
    
"parent"
axis String Restringe el arrastre al eje horizontal (x) o vertical (y). Valores posibles:"x", "y"。

Ejemplo de código:

Inicializar el draggable con laaxisopción especificada:

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

Después de la inicialización, obtener o establecer laaxisopción:

// getter
var axis = $( ".selector" ).draggable( "option", "axis" );
 
// setter
$( ".selector" ).draggable( "option", "axis", "x" );
    
false
cancel Selector Evita que el arrastre se inicie desde el elemento especificado.

Ejemplo de código:

Inicializar el draggable con lacancelopción especificada:

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

Después de la inicialización, obtener o establecer lacancelopción:

// getter
var cancel = $( ".selector" ).draggable( "option", "cancel" );
 
// setter
$( ".selector" ).draggable( "option", "cancel", ".title" );
    
"input, textarea, button, select, option"
connectToSortable Selector Permite colocar el draggable en un sortable especificado. Si se utiliza esta opción, un draggable puede colocarse en una lista sortable y pasar a formar parte de la lista. Nota:helperla opción debe establecerse a"clone", para que funcione correctamente. Debe incluirseel widget ordenable (Sortable Widget).。

Ejemplo de código:

Inicializar el draggable con laconnectToSortableopción especificada:

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

Después de la inicialización, obtener o establecer laconnectToSortableopción:

// getter
var connectToSortable = $( ".selector" ).draggable( "option", "connectToSortable" );
 
// setter
$( ".selector" ).draggable( "option", "connectToSortable", "#my-sortable" );
    
false
containment Selector o Element o String o Array Restringe el arrastre dentro de los límites del elemento o área especificados.

Soporta múltiples tipos:

  • Selector: el elemento arrastrable se contendrá dentro de los límites del primer elemento del selector. Si no se encuentra ningún elemento, no se establece containment.
  • Element: el elemento arrastrable se contendrá dentro de los límites del elemento.
  • String: valores posibles:"parent"、"document"、"window"。
  • Array: un array, en la forma[ x1, y1, x2, y2 ]define los límites del elemento.

Ejemplo de código:

Inicializar el draggable con lacontainmentopción especificada:

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

Después de la inicialización, obtener o establecer lacontainmentopción:

// getter
var containment = $( ".selector" ).draggable( "option", "containment" );
 
// setter
$( ".selector" ).draggable( "option", "containment", "parent" );
    
false
cursor String El cursor CSS durante la operación de arrastre.

Ejemplo de código:

Inicializar el draggable con lacursoropción especificada:

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

Después de la inicialización, obtener o establecer lacursoropción:

// getter
var cursor = $( ".selector" ).draggable( "option", "cursor" );
 
// setter
$( ".selector" ).draggable( "option", "cursor", "crosshair" );
    
"auto"
cursorAt Object Establece el desplazamiento del helper de arrastre con respecto al cursor del mouse. Las coordenadas se pueden proporcionar como un hash compuesto por una o dos claves:{ top, left, right, bottom }。

Ejemplo de código:

Inicializar el draggable con lacursorAtopción especificada:

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

Después de la inicialización, obtener o establecer lacursorAtopción:

// getter
var cursorAt = $( ".selector" ).draggable( "option", "cursorAt" );
 
// setter
$( ".selector" ).draggable( "option", "cursorAt", { left: 5 } );
    
false
delay Number Tiempo en milisegundos desde que se presiona el mouse hasta que comienza el arrastre. Esta opción puede evitar arrastres innecesarios al hacer clic en un elemento.

Ejemplo de código:

Inicializar el draggable con ladelayopción especificada:

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

Después de la inicialización, obtener o establecer ladelayopción:

// getter
var delay = $( ".selector" ).draggable( "option", "delay" );
 
// setter
$( ".selector" ).draggable( "option", "delay", 300 );
    
0
disabled Boolean Si se establece atrue, se desactiva este draggable.

Ejemplo de código:

Inicializar el draggable con ladisabledopción especificada:

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

Después de la inicialización, obtener o establecer ladisabledopción:

// getter
var disabled = $( ".selector" ).draggable( "option", "disabled" );
 
// setter
$( ".selector" ).draggable( "option", "disabled", true );
    
false
distance Number Distancia en píxeles que debe moverse después de presionar el mouse y antes de que comience el arrastre. Esta opción puede evitar arrastres innecesarios al hacer clic en un elemento.

Ejemplo de código:

Inicializar el draggable con ladistanceopción especificada:

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

Después de la inicialización, obtener o establecer ladistanceopción:

// getter
var distance = $( ".selector" ).draggable( "option", "distance" );
 
// setter
$( ".selector" ).draggable( "option", "distance", 10 );
    
1
grid Array Alinea el helper de arrastre a una cuadrícula de x e y píxeles. La forma del array debe ser[ x, y ]。

Ejemplo de código:

Inicializar el draggable con lagridopción especificada:

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

Después de la inicialización, obtener o establecer lagridopción:

// getter
var grid = $( ".selector" ).draggable( "option", "grid" );
 
// setter
$( ".selector" ).draggable( "option", "grid", [ 50, 20 ] );
    
false
handle Selector o Element Si se especifica esta opción, se restringe el inicio del arrastre a menos que el mouse se presione sobre el elemento especificado. Solo se permite arrastrar desde los elementos descendientes del elemento draggable.

Ejemplo de código:

Inicializar el draggable con lahandleopción especificada:

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

Después de la inicialización, obtener o establecer lahandleopción:

// getter
var handle = $( ".selector" ).draggable( "option", "handle" );
 
// setter
$( ".selector" ).draggable( "option", "handle", "h2" );
    
false
helper String o Function() Permite que se use un elemento helper para la visualización del arrastre.

Soporta múltiples tipos:

  • String: si se establece a"clone", el elemento será clonado y se arrastrará el clon.
  • Function: una función que devolverá el DOMElement que se usará durante el arrastre.

Ejemplo de código:

Inicializar el draggable con lahelperopción especificada:

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

Después de la inicialización, obtener o establecer lahelperopción:

// getter
var helper = $( ".selector" ).draggable( "option", "helper" );
 
// setter
$( ".selector" ).draggable( "option", "helper", "clone" );
    
"original"
iframeFix Boolean o Selector Evita que los iframes capturen los eventos de movimiento del mouse (mousemove) durante el arrastre. Cuando se usa junto concursorAtla opción, o cuando el cursor del mouse no está sobre el helper, es muy útil.

Soporta múltiples tipos:

  • Boolean: cuando se establece atrue, se colocará una superposición transparente sobre todos los iframes de la página.
  • Selector: todos los iframes que coincidan con el selector serán cubiertos con una superposición transparente.

Ejemplo de código:

Inicializar el draggable con laiframeFixopción especificada:

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

Después de la inicialización, obtener o establecer laiframeFixopción:

// getter
var iframeFix = $( ".selector" ).draggable( "option", "iframeFix" );
 
// setter
$( ".selector" ).draggable( "option", "iframeFix", true );
    
false
opacity Number La opacidad del helper mientras se arrastra.

Ejemplo de código:

Inicializar el draggable con laopacityopción especificada:

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

Después de la inicialización, obtener o establecer laopacityopción:

// getter
var opacity = $( ".selector" ).draggable( "option", "opacity" );
 
// setter
$( ".selector" ).draggable( "option", "opacity", 0.35 );
    
false
refreshPositions Boolean Si se establece atrue, se calcularán todas las posiciones de colocación posibles en cada movimiento del mouse (mousemove). Nota: esto soluciona el problema de entornos altamente dinámicos, pero reduce notablemente el rendimiento.

Ejemplo de código:

Inicializar con lasrefreshPositionsopciones especificadas del draggable:

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

Después de la inicialización, obtener o establecer larefreshPositionsopción:

// getter
var refreshPositions = $( ".selector" ).draggable( "option", "refreshPositions" );
 
// setter
$( ".selector" ).draggable( "option", "refreshPositions", true );
    
false
revert Boolean o String o Function() Indica si el elemento debe revertir a su posición inicial cuando se detiene el arrastre.

Soporta múltiples tipos:

  • Boolean: si se establece entrue, el elemento siempre se revierte.
  • String: si se establece en"invalid", la reversión ocurre solo si el draggable no está sobre un droppable; si se establece en"valid"ocurre lo contrario.
  • Function: una función que determina si el elemento se revierte a su posición inicial. La función debe devolvertruepara que el elemento se revierta.

Ejemplo de código:

Inicializar con lasrevertopciones especificadas del draggable:

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

Después de la inicialización, obtener o establecer larevertopción:

// getter
var revert = $( ".selector" ).draggable( "option", "revert" );
 
// setter
$( ".selector" ).draggable( "option", "revert", true );
    
false
revertDuration Number Duración de la animación de reversión (revert), en milisegundos. Sirevertla opción esfalsese ignora.

Ejemplo de código:

Inicializar con lasrevertDurationopciones especificadas del draggable:

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

Después de la inicialización, obtener o establecer larevertDurationopción:

// getter
var revertDuration = $( ".selector" ).draggable( "option", "revertDuration" );
 
// setter
$( ".selector" ).draggable( "option", "revertDuration", 200 );
    
500
scope String Usado para agrupar draggables y droppables correspondientes, además de laacceptopción del droppable.scopeUn draggable con el mismo

valor que el droppable será aceptado por ese droppable.

Ejemplo de código:scopeInicializar con las

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

opciones especificadas del draggable:scopeDespués de la inicialización, obtener o establecer la

// getter
var scope = $( ".selector" ).draggable( "option", "scope" );
 
// setter
$( ".selector" ).draggable( "option", "scope", "tasks" );
    
"default"
scroll Boolean opción:trueSi se establece en

, el contenedor se desplaza automáticamente al arrastrar.

Ejemplo de código:scrollInicializar con las

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

opciones especificadas del draggable:scrollDespués de la inicialización, obtener o establecer la

// getter
var scroll = $( ".selector" ).draggable( "option", "scroll" );
 
// setter
$( ".selector" ).draggable( "option", "scroll", false );
    
true
scrollSensitivity Number opción:scrollLa distancia desde el borde del viewport que se va a desplazar, en píxeles. La distancia es relativa al puntero, no al draggable. Sifalsela opción es

se ignora.

Ejemplo de código:scrollSensitivityInicializar con las

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

opciones especificadas del draggable:scrollSensitivityDespués de la inicialización, obtener o establecer la

// getter
var scrollSensitivity = $( ".selector" ).draggable( "option", "scrollSensitivity" );
 
// setter
$( ".selector" ).draggable( "option", "scrollSensitivity", 100 );
    
20
scrollSpeed Number opción:scrollSensitivityCuando el puntero del ratón se encuentra dentro de lascrolldistancia, la velocidad de desplazamiento de la ventana. Sifalsela opción es

se ignora.

Ejemplo de código:scrollSpeedInicializar con las

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

opciones especificadas del draggable:scrollSpeedDespués de la inicialización, obtener o establecer la

// getter
var scrollSpeed = $( ".selector" ).draggable( "option", "scrollSpeed" );
 
// setter
$( ".selector" ).draggable( "option", "scrollSpeed", 100 );
    
20
snap opción: Boolean o Selector

Indica si el elemento se ajusta a otros elementos.

  • BooleanSoporta múltiples tipos:true: cuando se establece en
  • Selector, el elemento se ajusta a otros elementos draggable.

: un selector que especifica a qué elemento ajustarse.

Ejemplo de código:snapInicializar con las

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

opciones especificadas del draggable:snapDespués de la inicialización, obtener o establecer la

// getter
var snap = $( ".selector" ).draggable( "option", "snap" );
 
// setter
$( ".selector" ).draggable( "option", "snap", true );
    
false
snapMode String opción:snapDetermina a qué borde del elemento de ajuste se ajustará el draggable. Sifalsela opción es"inner"、"outer"、"both"。

se ignora. Valores posibles:

Ejemplo de código:snapModeInicializar con las

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

opciones especificadas del draggable:snapModeDespués de la inicialización, obtener o establecer la

// getter
var snapMode = $( ".selector" ).draggable( "option", "snapMode" );
 
// setter
$( ".selector" ).draggable( "option", "snapMode", "inner" );
    
"both"
snapTolerance Number opción:snapLa distancia, en píxeles, desde el borde del elemento de ajuste en la que se producirá el ajuste. Sifalsela opción es

se ignora.

Ejemplo de código:snapToleranceInicializar con las

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

opciones especificadas del draggable:snapToleranceDespués de la inicialización, obtener o establecer la

// getter
var snapTolerance = $( ".selector" ).draggable( "option", "snapTolerance" );
 
// setter
$( ".selector" ).draggable( "option", "snapTolerance", 30 );
    
20
stack Selector opción:

Controla el z-index del conjunto de elementos que coinciden con el selector, que siempre está por delante del elemento actualmente arrastrado; muy útil en cosas como administradores de ventanas.

Ejemplo de código:stackInicializar con las

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

opciones especificadas del draggable:stackDespués de la inicialización, obtener o establecer la

// getter
var stack = $( ".selector" ).draggable( "option", "stack" );
 
// setter
$( ".selector" ).draggable( "option", "stack", ".products" );
    
false
zIndex Number opción:

El z-index del helper cuando se arrastra.

Ejemplo de código:zIndexInicializar con las

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

opciones especificadas del draggable:zIndexDespués de la inicialización, obtener o establecer la

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

opción: Métodos Devuelve
destroy() jQuery (plugin only) Descripción
  • Elimina por completo la funcionalidad draggable. Esto devuelve el elemento a su estado previo a la inicialización.

Este método no acepta ningún argumento.

Ejemplo de código:

$( ".selector" ).draggable( "destroy" );
    
disable() jQuery (plugin only) Llame al método destroy:
  • Deshabilita el draggable.

Este método no acepta ningún argumento.

Ejemplo de código:

$( ".selector" ).draggable( "disable" );
    
enable() jQuery (plugin only) Llame al método disable:
  • Habilita el draggable.

Este método no acepta ningún argumento.

Ejemplo de código:

$( ".selector" ).draggable( "enable" );
    
option( optionName ) Object Llame al método enable:optionNameObtiene el valor actual asociado con la
  • optionName
    opción especificada.
    Tipo: String

Descripción: el nombre de la opción a obtener.

Ejemplo de código:

var isDisabled = $( ".selector" ).draggable( "option", "disabled" );
    
option() PlainObject Llame a este método:
  • Obtiene un objeto que contiene pares clave/valor que representan el hash de opciones actual del draggable.

Este método no acepta ningún argumento.

Ejemplo de código:

var options = $( ".selector" ).draggable( "option" );
    
option( optionName, value ) jQuery (plugin only) Llame a este método:optionNameEstablece el valor de la opción del draggable asociada con la
  • optionName
    opción especificada.
    Tipo: String
  • value
    Descripción: el nombre de la opción a establecer.
    Tipo: Object

Descripción: el valor a establecer para la opción.

Ejemplo de código:

$( ".selector" ).draggable( "option", "disabled", true );
    
option( options ) jQuery (plugin only) Llame a este método:
  • options
    Establece una o más opciones para el draggable.
    Tipo: Object

Descripción: los pares option-value a establecer.

Ejemplo de código:

$( ".selector" ).draggable( "option", { disabled: true } );
    
widget() jQuery Llame a este método:jQueryDevuelve un objeto que contiene el elemento draggable
  • objeto.

Este método no acepta ningún argumento.

Ejemplo de código:

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

Llame al método widget: Eventos Tipo
create( event, ui ) dragcreate Descripción
  • event
    Se dispara cuando se crea el draggable.
  • ui
    Tipo: Event

Tipo: ObjectuiNota:

El objeto está vacío, pero se incluye para mantener la consistencia con otros eventos.

Ejemplo de código:

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

Inicialice el draggable con el callback create especificado:

$( ".selector" ).on( "dragcreate", function( event, ui ) {} );
    
drag( event, ui ) drag Vincule un detector de eventos al evento dragcreate:
  • event
    Se dispara cuando el ratón se mueve durante el arrastre.
  • ui
    Tipo: Event
    • helper
      Tipo: Object
      Tipo: jQuery
    • position
      Descripción: un objeto jQuery que representa el helper que se está arrastrando.
      Tipo: Object{ top, left }Descripción: la posición CSS actual del helper, como un
    • offset
      objeto.
      Tipo: Object{ top, left }Descripción: la posición de desplazamiento actual del helper, como un

objeto.

Ejemplo de código:

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

Inicialice el draggable con el callback drag especificado:

$( ".selector" ).on( "drag", function( event, ui ) {} );
    
start( event, ui ) dragstart Vincule un detector de eventos al evento drag:
  • event
    Se dispara cuando comienza el arrastre.
  • ui
    Tipo: Event
    • helper
      Tipo: Object
      Tipo: jQuery
    • position
      Descripción: un objeto jQuery que representa el helper que se está arrastrando.
      Tipo: Object{ top, left }Descripción: la posición CSS actual del helper, como un
    • offset
      objeto.
      Tipo: Object{ top, left }Descripción: la posición de desplazamiento actual del helper, como un

objeto.

Inicializar draggable con el callback start especificado:

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

Vincular un listener de eventos al evento dragstart:

$( ".selector" ).on( "dragstart", function( event, ui ) {} );
    
stop( event, ui ) dragstop Se dispara cuando se detiene el arrastre.
  • event
    Tipo: Event
  • ui
    Tipo: Object
    • helper
      Tipo: jQuery
      Descripción: Objeto jQuery que representa el helper (asistente) que se está arrastrando.
    • position
      Tipo: Object
      Descripción: Posición CSS actual del helper (asistente), por ejemplo{ top, left }objeto.
    • offset
      Tipo: Object
      Descripción: Posición de desplazamiento actual del helper (asistente), por ejemplo{ top, left }objeto.

Ejemplo de código:

Inicializar draggable con el callback stop especificado:

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

Vincular un listener de eventos al evento dragstop:

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

Ejemplos

Un widget jQuery UI Draggable (widget arrastrable) simple.

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

Otras extensiones