Opération glisser-déposer dans HTML

Adobe AIR 1.0 et les versions ultérieures

Comportement par défaut des mouvements glisser-déposer
Evénements glisser-déposer dans HTML
Types MIME associés à l’événement glisser-déposer HTML
Effets de glissement dans HTML

Pour faire glisser des données vers une application HTML ou hors de cette dernière (ou vers le code HTML affiché dans un objet HTMLLoader et hors de ce dernier), vous disposez des événements glisser-déposer HTML. L’API glisser-déposer HTML vous permet de faire glisser des données vers des éléments DOM ou à partir de ces derniers dans le contenu HTML.

Remarque : vous pouvez également utiliser les API NativeDragEvent et NativeDragManager d’AIR en écoutant les événements sur l’objet HTMLLoader qui comporte le contenu HTML. L’API HTML est toutefois mieux intégrée au DOM HTML et permet de contrôler le comportement par défaut.

Comportement par défaut des mouvements glisser-déposer

L’environnement HTML définit le comportement par défaut des actions glisser-déposer qui impliquent du texte, des images et des URL. Le comportement par défaut permet de faire glisser ces types de données hors d’un élément. Vous ne pouvez toutefois faire glisser que du texte vers un élément, sous réserve qu’il réside dans une zone modifiable de page. Lorsque vous faites glisser du texte entre des zones modifiables d’une page ou au sein de l’une de ces zones, le comportement par défaut consiste à exécuter une action de déplacement. Lorsque vous faites glisser du texte vers une zone modifiable à partir d’une zone non modifiable ou de l’extérieur de l’application, le comportement par défaut consiste à exécuter une action de copie.

Vous pouvez remplacer le comportement par défaut en gérant vous-même les événements glisser-déposer. Pour annuler le comportement par défaut, vous devez appeler les méthodes preventDefault() des objets distribués suite aux événements glisser-déposer. Vous pouvez ensuite insérer des données dans la cible du dépôt et supprimer les données de la source du glissement pour exécuter l’action sélectionnée.

Par défaut, l’utilisateur peut sélectionner et faire glisser n’importe quel texte. Il peut faire glisser des images et des liens. La propriété CSS WebKit, -webkit-user-select , permet de contrôler le mode de sélection de tout élément HTML. Par exemple, si vous définissez -webkit-user-select sur none , il est impossible de sélectionner les contenus d’élément et, par conséquent, de les faire glisser. La propriété CSS -webkit-user-drag permet également de déterminer s’il est possible de faire glisser un élément global. Le contenu de l’élément est toutefois traité séparément. L’utilisateur peut néanmoins faire glisser une section sélectionnée de texte. Pour plus d’informations, voir CSS dans AIR .

Evénements glisser-déposer dans HTML

Les événements distribués par l’élément initiateur à l’origine d’un glissement sont indiqués dans le tableau suivant :

Evénement	Description
dragstart	Distribué lorsque l’utilisateur démarre l’action de glissement. Le gestionnaire de cet événement peut, le cas échéant, interdire le glissement en appelant la méthode preventDefault() de l’objet événement. Pour déterminer si les données glissées peuvent être copiées, liées ou déplacées, définissez la propriété effectAllowed. Le texte, les images et les liens sélectionnés sont placés dans le Presse-papiers par défaut, mais vous pouvez définir d’autres données pour le mouvement de glissement par le biais de la propriété dataTransfer de l’objet événement.
drag	Distribué continuellement pendant le mouvement de glissement.
dragend	Distribué lorsque l’utilisateur relâche le bouton de la souris pour achever l’action de glissement.

Les événements distribués par une cible de glissement sont les suivants :

Evénement	Description
dragover	Distribué continuellement tant que le mouvement de glissement ne dépasse pas les limites de l’élément. Le gestionnaire de cet événement doit définir la propriété dataTransfer.dropEffect pour indiquer si le dépôt entraîne une action de copie, de déplacement ou de lien lorsque l’utilisateur relâche la souris.
dragenter	Distribué lorsque le mouvement de glissement pénètre dans les limites de l’élément. Si vous modifiez toute propriété d’un objet dataTransfer dans un gestionnaire d’événement dragenter, ces modifications sont rapidement annulées par l’événement dragover suivant. En revanche, il se produit un bref délai entre un événement dragenter et le premier événement dragover susceptible d’entraîner le clignotement du curseur si d’autres propriétés sont définies. Dans de nombreux cas de figure, vous pouvez utiliser le même gestionnaire pour les deux événements.
dragleave	Distribué lorsque le mouvement de glissement quitte les limites de l’élément.
drop	Distribué lorsque l’utilisateur dépose les données sur l’élément. Seul le gestionnaire de l’événement peut accéder aux données en cours de glissement.

L’objet événement distribué en réponse à ces événements est similaire à un événement souris. Les propriétés d’événement souris telles que ( clientX , clientY ) et ( screenX , screenY ) permettent de déterminer la position de la souris.

La principale propriété d’un objet événement drag correspond à dataTransfer , qui contient les données en cours de glissement. L’objet dataTransfer en tant que tel dispose des propriétés et méthodes suivantes :

Propriété ou méthode	Description
effectAllowed	Effet autorisé par la source du glissement. Le gestionnaire de l’événement dragstart définit généralement cette valeur. Pour plus d’informations, voir la section Effets de glissement dans HTML .
dropEffect	Effet sélectionné par la cible ou l’utilisateur. Si vous définissez la propriété `dropEffect` dans un gestionnaire d’événement `dragover` ou `dragenter` , AIR met à jour le curseur de la souris pour indiquer l’effet qui se produit lorsque l’utilisateur relâche le bouton de la souris. Si la propriété `dropEffect` définie ne correspond pas à l’un des effets autorisés, aucun dépôt n’est autorisé et le curseur unavailable s’affiche. Si vous n’avez pas défini de propriété `dropEffect` en réponse à l’événement `dragover` ou `dragenter` le plus récent, l’utilisateur peut choisir l’un des effets autorisés par le biais des touches de modification standard gérées par le système d’exploitation. Le dernier effet est signalé par la propriété `dropEffect` de l’objet distribué pour `dragend` . Si l’utilisateur abandonne le dépôt en relâchant le bouton de la souris hors d’une cible appropriée, la propriété `dropEffect` est définie sur `none` .
types	Tableau contenant les chaînes de type MIME associées à chaque format de données que contient l’objet `dataTransfer` .
getData(mimeType)	Extrait les données au format stipulé par le paramètre `mimeType` . La méthode `getData()` ne peut être appelée qu’en réponse à l’événement `drop` .
setData(mimeType)	Ajoute des données à l’objet `dataTransfer` au format stipulé par le paramètre mimeType. Vous pouvez ajouter des données dans divers formats en appelant la méthode `setData()` pour chaque type MIME. Toute donnée placée dans l’objet `dataTransfer` par le comportement de glissement par défaut est effacée. La méthode `setData()` ne peut être appelée qu’en réponse à l’événement `dragstart` .
clearData(mimeType)	Efface toute donnée au format stipulé par le paramètre `mimeType` .
setDragImage(image, offsetX, offsetY)	Définit une image de glissement personnalisée. Vous ne pouvez appeler la méthode `setDragImage()` qu’en réponse à l’événement dragstart et uniquement lorsqu’un élément HTML entier fait l’objet d’un glissement en définissant le style CSS `-webkit-user-drag` sur `element` . Le paramètre `image` peut correspondre à un objet JavaScript Element ou Image.

Types MIME associés à l’événement glisser-déposer HTML

Les types MIME à utiliser avec l’objet dataTransfer d’un événement glisser-déposer HTML sont indiqués dans le tableau suivant :

Format de données	Type MIME
Texte	"text/plain"
HTML	"text/html"
URL	"text/uri-list"
Image bitmap	"image/x-vnd.adobe.air.bitmap"
Liste de fichiers	"application/x-vnd.adobe.air.file-list"

Vous disposez également d’autres chaînes MIME, notamment les chaînes définies par une application. D’autres applications risquent toutefois de ne pas pouvoir reconnaître ou utiliser les données transférées. Il vous incombe d’ajouter des données à l’objet dataTransfer dans le format attendu.

Important : seul le code qui s’exécute dans le sandbox d’application peut accéder aux fichiers déposés. Toute tentative de lecture ou de définition de propriété d’un objet File au sein d’un sandbox hors application génère une erreur de sécurité. Pour plus d’informations, voir la section Gestion des dépôts de fichier dans un sandbox HTML hors application .

Effets de glissement dans HTML

L’initiateur du mouvement de glissement peut limiter les effets de glissement autorisés en définissant la propriété dataTransfer.effectAllowed du gestionnaire de l’événement dragstart . Les valeurs de chaîne suivantes sont prises en charge :

Valeur de chaîne	Description
"none"	Aucune opération de glissement n’est autorisée.
"copy"	Les données sont copiées sur la cible, sans modifier l’original.
"link"	Les données sont partagées avec la cible du dépôt par le biais d’un lien associé à l’original.
"move”	Les données sont copiées sur la cible et supprimées de l’emplacement d’origine.
"copyLink"	Les données peuvent être copiées ou liées.
"copyMove"	Les données peuvent être copiées ou déplacées.
"linkMove"	Les données peuvent être liées ou déplacées.
"all"	Les données peuvent être copiées, déplacées ou liées. All correspond à l’effet par défaut lorsque vous interdisez le comportement par défaut.

La cible du mouvement de glissement peut définir la propriété dataTransfer.dropEffect pour indiquer l’action exécutée si l’utilisateur achève le dépôt. Si l’effet de dépôt fait partie des actions autorisées, le système affiche le curseur de copie, déplacement ou lien approprié. Dans le cas contraire, le système affiche le curseur unavailable . Si aucun effet de dépôt n’est défini par la cible, l’utilisateur peut choisir les actions autorisées par le biais des touches de modification.

Le code suivant définit la valeur dropEffect dans les gestionnaires des événements dragover et 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"; 
}

Remarque : bien qu’il soit recommandé de définir systématiquement la propriété dropEffect dans le gestionnaire de l’événement dragenter , notez que l’événement dragover suivant réinitialise la valeur par défaut de la propriété. Définissez dropEffect en réponse aux deux événements.