|
Para arrastrar datos hacia dentro y hacia fuera de una aplicación basada en HTML (o hacia dentro y hacia fuera del HTML visualizado en un HTMLLoader), se pueden utilizar eventos de arrastrar y colocar en HTML. La API de arrastrar y colocar en HTML permite arrastrar hacia y desde elementos DOM en el contenido HTML.
Nota:
también se pueden utilizar las API NativeDragEvent y NativeDragManager de AIR mediante la detección de eventos en el objeto HTMLLoader que contiene el contenido HTML. Sin embargo, la API de HTML está mejor integrada con el DOM de HTML y le permite controlar el comportamiento predeterminado.
Comportamiento predeterminado de arrastrar y colocar
El entorno HTML proporciona comportamiento predeterminado para gestos de arrastrar y colocar que implican texto, imágenes y URL. Estos tipos de datos siempre pueden arrastrarse para sacarlos de un elemento si se utiliza el comportamiento predeterminado. Sin embargo, solo se puede arrastrar texto para introducirlo en un elemento y solo a elementos en una región editable de la página. Al arrastrar texto entre o dentro de regiones editables de la página, el comportamiento predeterminado realiza una acción de mover. Al arrastrar texto a una región editable desde una región no editable o desde fuera de la aplicación, el comportamiento predeterminado lleva a cabo una acción de copia.
El comportamiento predeterminado puede suprimirse si controla uno mismo los eventos de arrastrar y colocar. Para anular el comportamiento predeterminado hay que llamar a los métodos
preventDefault()
de los objetos distribuidos para los eventos de arrastrar y colocar. Luego se pueden introducir datos en el destino y eliminar datos del origen según haga falta para llevar a cabo la acción seleccionada.
La situación predeterminada es que el usuario puede seleccionar y arrastrar cualquier texto, así como arrastrar imágenes y vínculos. Se puede utilizar la propiedad de CSS WebKit
-webkit-user-select
para controlar cómo puede seleccionarse cualquier elemento HTML. Por ejemplo, si se define
-webkit-user-select
en
none
, el contenido del elemento no será seleccionable y, por lo tanto, no se podrá arrastrar. También se puede utilizar la propiedad de CSS
-webkit-user-drag
para controlar si se puede arrastrar un elemento en su totalidad. No obstante, el contenido del elemento se trata por separado. De todos modos, el usuario puede arrastrar una parte seleccionada del texto. Para obtener más información, consulte
CSS en AIR
.
Eventos de arrastrar y colocar en HTML
Los eventos distribuidos por el elemento iniciador desde el que origina una operación de arrastrar son:
|
Evento
|
Descripción
|
|
dragstart
|
Se distribuye cuando el usuario inicia el gesto de arrastrar. El controlador de este evento puede impedir la operación de arrastrar, si es preciso, llamando al método preventDefault() del objeto de evento. Para controlar si se pueden copiar, vincular o mover los datos arrastrados, configure la propiedad effectAllowed. El texto, las imágenes y los vínculos seleccionados se colocan en el portapapeles como parte del comportamiento predeterminado, pero se pueden configurar otros datos para el gesto de arrastrar mediante la propiedad dataTransfer del objeto de evento.
|
|
drag
|
Se distribuye de forma continua durante el gesto de arrastrar.
|
|
dragend
|
Se distribuye cuando el usuario suelta el botón del ratón para terminar el gesto de arrastrar.
|
Los eventos distribuidos por un destino de arrastre son:
|
Evento
|
Descripción
|
|
dragover
|
Se distribuye de forma continua mientras el gesto de arrastrar permanece dentro de los límites del elemento. El controlador de este evento debe definir la propiedad dataTransfer.dropEffect para indicar si se producirá una acción de copiar, mover o vincular si el usuario suelta el ratón.
|
|
dragenter
|
Se distribuye cuando el gesto de arrastrar entra en el elemento.
Si cambia alguna propiedad del objeto dataTransfer en un controlador de eventos dragenter, esas modificaciones se verán suprimidas en cuanto se produzca el siguiente evento dragover. Por otro lado, existe un breve retardo entre un evento dragenter y el primer evento dragover que puede hacer que el cursor parpadee si se han definido propiedades distintas. En muchos casos se puede utilizar el mismo controlador para ambos eventos.
|
|
dragleave
|
Se distribuye cuando el gesto de arrastrar sale de los límites del elemento.
|
|
drop
|
Se distribuye cuando el usuario coloca los datos en el elemento. Solo se tiene acceso a los datos arrastrados dentro del controlador de este evento.
|
El objeto de evento que se distribuye como respuesta a estos eventos es similar a un evento de ratón. Se pueden utilizar propiedades de evento de ratón tales como (
clientX
,
clientY
) y (
screenX
,
screenY
) para determinar la posición del ratón.
La propiedad más importante de un objeto de evento drag es
dataTransfer
, que contiene los datos arrastrados. El objeto
dataTransfer
en sí tiene los siguientes métodos y propiedades:
|
Método o propiedad
|
Descripción
|
|
effectAllowed
|
El efecto admitido por el origen de la operación de arrastrar. Lo habitual es que este valor lo defina el controlador del evento dragstart. Consulte
Efectos de arrastrar en HTML
.
|
|
dropEffect
|
El efecto elegido por el destino o el usuario. Si se define la propiedad
dropEffect
en un controlador de eventos
dragover
o
dragenter
, AIR actualiza el cursor para mostrar el efecto que se produciría si el usuario soltara el ratón. Si la definición de
dropEffect
no coincide con uno de los efectos admitidos, no se permite colocar y se presenta el cursor de
indisposición
. Si usted no ha definido la propiedad
dropEffect
como respuesta al último evento
dragover
o
dragenter
, el usuario podrá elegir entre los efectos admitidos con las teclas modificadoras normales del sistema operativo.
El efecto final lo notifica la propiedad
dropEffect
del objeto distribuido para
dragend
. Si el usuario abondona la operación de colocar, soltando el ratón fuera de un destino idóneo,
dropEffect
se define en
none
.
|
|
types
|
Un conjunto que contiene las cadenas de tipos MIME para cada formato de datos presente en el objeto
dataTransfer
.
|
|
getData(mimeType)
|
Obtiene los datos en el formato especificado por el parámetro
mimeType
.
El método
getData()
solo puede llamarse como respuesta al evento
drop
.
|
|
setData(mimeType)
|
Añade datos a
dataTransfer
en el formato especificado por el parámetro mimeType. Para añadir datos en varios formatos, llame a
setData()
para cada tipo MIME. Los datos que el comportamiento predeterminado de arrastrar haya colocado en el objeto
dataTransfer
se eliminan.
El método
setData()
solo puede llamarse como respuesta al evento
dragstart
.
|
|
clearData(mimeType)
|
Elimina datos en el formato especificado por el parámetro
mimeType
.
|
|
setDragImage(image, offsetX, offsetY)
|
Configura una imagen de arrastrar personalizada. El método
setDragImage()
solo se puede llamar como respuesta al evento dragstart y únicamente cuando un elemento HTML completo se arrastra estableciendo su estilo CSS
-webkit-user-drag
en
element
. El parámetro
image
puede ser un elemento JavaScript o un objeto Image.
|
Tipos MIME para la operación de arrastrar y colocar en HTML
Los tipos MIME a utilizar con un objeto
dataTransfer
de un evento de arrastrar y colocar en HTML incluyen:
|
Formato de datos
|
Tipo MIME
|
|
Texto
|
"text/plain"
|
|
HTML
|
"text/html"
|
|
URL
|
"text/uri-list"
|
|
Mapa de bits
|
"image/x-vnd.adobe.air.bitmap"
|
|
Lista de archivos
|
"application/x-vnd.adobe.air.file-list"
|
También se pueden utilizar otras cadenas MIME, incluidas las que define la aplicación. Sin embargo, cabe la posibilidad de que otras aplicaciones no reconozcan o no puedan utilizar los datos transferidos. Es su responsabilidad añadir datos al objeto
dataTransfer
en el formato previsto.
Efectos de arrastrar en HTML
El iniciador del gesto de arrastrar puede limitar los efectos de arrastrar que se admiten mediante la definición de la propiedad
dataTransfer.effectAllowed
en el controlador del evento
dragstart
. Se pueden utilizar los siguientes valores de cadenas:
|
Valor de la cadena
|
Descripción
|
|
"none"
|
No se admite ninguna operación de arrastrar.
|
|
"copy"
|
Los datos se copiarán en el destino, dejando los originales en su lugar.
|
|
"link"
|
Los datos se compartirán con el destino utilizando un vínculo a los originales.
|
|
"move”
|
Los datos se copiarán en el destino y se eliminarán del lugar original.
|
|
"copyLink"
|
Los datos se pueden copiar o vincular.
|
|
"copyMove"
|
Los datos se pueden copiar o mover.
|
|
"linkMove"
|
Los datos se pueden vincular o mover.
|
|
"all"
|
Los datos se pueden copiar, mover o vincular.
All
es el efecto predeterminado cuando se impide el comportamiento predeterminado.
|
El destino del gesto de arrastrar puede definir la propiedad
dataTransfer.dropEffect
para indicar la acción que se realiza si el usuario finaliza la operación de colocar. Si el efecto de colocar es una de las acciones admitidas, el sistema muestra el cursor de copiar, mover o vincular, según proceda. De lo contrario, el sistema muestra el cursor de
indisposición
. Si el destino no define ningún efecto de colocar, el usuario puede elegir entre las acciones admitidas con las teclas modificadoras.
Defina el valor
dropEffect
de los controladores para ambos eventos,
dragover
y
dragenter
:
function doDragStart(event) {
event.dataTransfer.setData("text/plain","Text to drag");
event.dataTransfer.effectAllowed = "copyMove";
}
function doDragOver(event) {
event.dataTransfer.dropEffect = "copy";
}
function doDragEnter(event) {
event.dataTransfer.dropEffect = "copy";
}
Nota:
si bien conviene siempre definir la propiedad
dropEffect
en el controlador de
dragenter
, tenga en cuenta que el siguiente evento
dragover
restaurará el valor predeterminado de la propiedad. Defina
dropEffect
como respuesta a ambos eventos.
|
|
|
