|
Per trascinare i dati all'interno e all'esterno di un'applicazione basata su HTML (o all'interno e all'esterno dell'HTML visualizzato in un HTMLLoader), è possibile utilizzare eventi di trascinamento HTML. L'API di trascinamento HTML consente di trascinare verso e da elementi DOM all'interno del contenuto HTML.
Nota:
è possibile inoltre utilizzare le API NativeDragEvent e NativeDragManager di AIR intercettando gli eventi sull'oggetto HTMLLoader che include il contenuto HTML. Tuttavia, l'API HTML è meglio integrata con il DOM HTML e consente di controllare il comportamento predefinito.
Comportamento di trascinamento predefinito
L'ambiente HTML offre un comportamento predefinito per i movimenti di trascinamento che coinvolgono testo, immagini e URL. Con il comportamento predefinito, è possibile sempre trascinare questi tipi di dati fuori da un elemento. Tuttavia, è possibile trascinare solo testo in un elemento e solo a elementi in un'area modificabile di una pagina. Quando si trascina testo tra o all'interno di aree modificabili di una pagina, il comportamento predefinito esegue un'azione di spostamento. Quando si trascina testo in un'area modificabile da un'area non modificabile o dall'esterno dell'applicazione, il comportamento predefinito esegue un'azione di copia.
È possibile sostituire il comportamento predefinito gestendo da solo eventi di trascinamento. Per annullare il comportamento predefinito, è necessario chiamare i metodi
preventDefault()
degli oggetti inviati per gli eventi di trascinamento. È possibile quindi inserire dati nella destinazione di rilascio e rimuovere dati dall'origine del trascinamento secondo necessità al fine di eseguire l'azione selezionata.
Per impostazione predefinita, l'utente può selezionare e trascinare qualsiasi testo e trascinare immagini e collegamenti. È possibile utilizzare la proprietà WebKit CSS,
-webkit-user-select
per controllare come si possa selezionare qualsiasi elemento HTML. Ad esempio, se si imposta
-webkit-user-select
su
none
, il contenuto dell'elemento non è selezionabile e quindi non può essere trascinato. È possibile inoltre utilizzare la proprietà CSS,
-webkit-user-drag
per controllare se è possibile trascinare un elemento come intero. Tuttavia, il contenuto dell'elemento viene trattato in modo separato. L'utente potrebbe ancora trascinare una porzione selezionata del testo. Per ulteriori informazioni, vedete
CSS in AIR
.
Eventi di trascinamento in HTML
Gli eventi, inviati dall'elemento promotore da cui ha origine un trascinamento, sono:
|
Evento
|
Descrizione
|
|
dragstart
|
Inviato quando l'utente inizia il movimento di trascinamento. Il gestore di questo evento può evitare il trascinamento, se necessario, chiamando il metodo preventDefault() dell'oggetto evento. Per controllare se è possibile copiare, collegare o spostare i dati trascinati, impostare la proprietà effectAllowed. Testo, immagini e collegamenti selezionati vengono posti negli Appunti dal comportamento predefinito, ma è possibile impostare dati differenti per il movimento di trascinamento mediante la proprietà dataTransfer dell'oggetto evento.
|
|
drag
|
Inviato continuamente durante il movimento di trascinamento.
|
|
dragend
|
Inviato quando l'utente rilascia il pulsante del mouse per terminare il movimento di trascinamento.
|
Gli eventi inviati da una destinazione di trascinamento sono:
|
Evento
|
Descrizione
|
|
dragover
|
Inviato continuamente mentre il movimento di trascinamento resta all'interno dei limiti dell'elemento. Il gestore di questo evento deve impostare la proprietà dataTransfer.dropEffect a indicare se il rilascio determinerà un'azione di copia, spostamento o collegamento qualora l'utente rilasci il mouse.
|
|
dragenter
|
Inviato quando il movimento di trascinamento raggiunge i limiti dell'elemento.
Se si modifica qualsiasi proprietà di un oggetto dataTransfer in un gestore eventi dragenter, queste modifiche vengono rapidamente sostituite dal successivo evento dragover. D'altro canto, vi è un breve ritardo tra un evento dragenter e il primo evento dragover che possono determinare il lampeggiare del cursore qualora vengano impostate le diverse proprietà. In molti casi, è possibile utilizzare lo stesso gestore per entrambi gli eventi.
|
|
dragleave
|
Inviato quando il movimento di trascinamento esce dai limiti dell'elemento.
|
|
drop
|
Inviato quando l'utente rilascia i dati sull'elemento. È possibile accedere ai dati solo all'interno del gestore per questo evento.
|
L'oggetto evento inviato in risposta a questi eventi è simile a un evento di mouse. È possibile utilizzare le proprietà evento del mouse come (
clientX
,
clientY
) e (
screenX
,
screenY
), per determinare la posizione del mouse.
La proprietà più importante di un oggetto evento di trascinamento è
dataTransfer
, contenente i dati trascinati. L'oggetto
dataTransfer
stesso ha le seguenti proprietà e metodi:
|
Proprietà o metodo
|
Descrizione
|
|
effectAllowed
|
L'effetto consentito dall'origine del trascinamento. Di solito, il gestore dell'evento dragstart imposta questo valore. consultate
Effetti di trascinamento in HTML
.
|
|
dropEffect
|
L'effetto consentito dalla destinazione o dall'utente. Se si imposta
dropEffect
in un gestore eventi
dragover
o
dragenter
, AIR quindi aggiorna il cursore del mouse a indicare l'effetto che si verifica qualora l'utente rilasci il mouse. Se l'impostazione
dropEffect
non soddisfa uno degli effetti consentiti, non è possibile alcun rilascio e viene visualizzato il cursore
non disponibile
. Se non è stato impostato un
dropEffect
in risposta all'ultimo evento
dragover
o
dragenter
, l'utente può quindi scegliere tra gli effetti consentiti tramite i tasti modificatore standard del sistema operativo.
L'effetto finale è riportato dalla proprietà
dropEffect
dell'oggetto inviato per
dragend
. Se l'utente sospende il rilascio lasciando il mouse all'esterno di un'idonea destinazione,
dropEffect
è impostato su
none
.
|
|
types
|
Un array contenente le stringhe di tipo MIME per ciascun formato di dati presente nell'oggetto
dataTransfer
.
|
|
getData(mimeType)
|
Recupera i dati nel formato specificato dal parametro
mimeType
.
Il metodo
getData()
può essere richiamato solo in risposta all'evento
drop
.
|
|
setData(mimeType)
|
Aggiunge i dati al
dataTransfer
nel formato specificato dal parametro mimeType. È possibile aggiungere dati in più formati chiamando
setData()
per ogni tipo MIME. Vengono cancellati tutti i dati posti nell'oggetto
dataTransfer
tramite il comportamento predefinito di trascinamento.
Il metodo
setData()
può essere richiamato solo in risposta all'evento
dragstart
.
|
|
clearData(mimeType)
|
Cancella tutti i dati nel formato specificato dal parametro
mimeType
.
|
|
setDragImage(image, offsetX, offsetY)
|
Imposta un'immagine di trascinamento personalizzata. Il metodo
setDragImage()
può essere chiamata solo in risposta all'evento dragstart e solo quando viene trascinato un intero elemento HTML impostando il suo stile CSS
-webkit-user-drag
su
element
. Il parametro
image
può essere un elemento JavaScript o un oggetto Image.
|
Tipi MIME per trascinamento HTML
I tipi MIME da utilizzare con l'oggetto
dataTransfer
di un evento di trascinamento HTML:
|
Formato dati
|
Tipo MIME
|
|
Testo
|
"text/plain"
|
|
HTML
|
"text/html"
|
|
URL
|
"text/uri-list"
|
|
Bitmap
|
"image/x-vnd.adobe.air.bitmap"
|
|
Elenco file
|
"application/x-vnd.adobe.air.file-list"
|
È possibile utilizzare anche altre stringhe MIME, comprese le stringhe definite dall'applicazione. Tuttavia, altre applicazioni potrebbero non essere in grado di riconoscere o utilizzare i dati trasferiti. È vostra responsabilità aggiungere dati all'oggetto
dataTransfer
nel formato previsto.
Importante:
solo il codice eseguito nella sandbox dell'applicazione può accedere ai file rilasciati. Il tentativo di leggere o impostare qualsiasi proprietà di un oggetto File in una sandbox di non applicazione genera un errore di sicurezza. Per ulteriori informazioni, consultate
Gestione dei rilasci di file nelle sandbox HTML di non applicazione
.
Effetti di trascinamento in HTML
Il promotore del movimento di trascinamento può limitare gli effetti di trascinamento consentiti impostando la proprietà
dataTransfer.effectAllowed
nel gestore dell'evento
dragstart
. È possibile utilizzare i seguenti valori stringa:
|
Valore stringa
|
Descrizione
|
|
"none"
|
Non è consentita alcuna operazione di trascinamento.
|
|
"copy"
|
I dati verranno copiati alla destinazione, lasciando in posizione l'originale.
|
|
"link"
|
I dati verranno condivisi con la destinazione di rilascio mediante un collegamento all'originale.
|
|
"move”
|
I dati verranno copiati alla destinazione e rimossi dalla posizione originale.
|
|
"copyLink"
|
È possibile copiare o collegare i dati.
|
|
"copyMove"
|
È possibile copiare o spostare i dati.
|
|
"linkMove"
|
È possibile collegare o spostare i dati.
|
|
"all"
|
È possibile copiare, spostare o collegare i dati.
All
è l'effetto predefinito quando si evita il comportamento predefinito.
|
La destinazione del movimento di trascinamento può impostare la proprietà
dataTransfer.dropEffect
per indicare l'azione da intraprendere se l'utente completa il rilascio. Se l'effetto di rilascio è una delle azioni consentite, il sistema visualizza il cursore appropriato per copia, spostamento o collegamento. In caso contrario, il sistema visualizza il cursore
non disponibile
. Se non è impostato alcun effetto di rilascio dalla destinazione, l'utente può scegliere tra le azioni consentite con i tasti modificatore.
Impostate il valore
dropEffect
nei gestori per entrambi gli eventi
dragover
e
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:
sebbene sia necessario impostare sempre la proprietà
dropEffect
nel gestore per
dragenter
, accertatevi che l'evento
dragover
successivo reimposti la proprietà al suo valore predefinito. Impostate
dropEffect
in risposta a entrambi gli eventi.
|
|
|
