API HTML Glisser et déposer

Concepts et utilisation

En surface, le glisser-déposer a en réalité trois cas d'utilisation distincts : déplacer des éléments au sein d'une page, déplacer des données hors d'une page, et déplacer des données dans une page. Ils ont des exigences et des implémentations légèrement différentes. Cependant, l'API de glisser-déposer fournit un modèle unifié pour penser à toutes ces interactions.

Au cœur de l'opération de glisser-déposer, trois éléments sont impliqués :

• L'élément déplacé
• Les données sous-jacentes à transférer
• La cible de dépôt

Il n'est pas nécessaire que les trois soient sous votre contrôle, ni que vous deviez les définir vous-même :

• Lors du déplacement de données externes dans une page, aucun élément déplaçable n'a besoin d'être défini (par exemple, il pourrait s'agir d'un fichier dans l'explorateur de fichiers du système d'exploitation).
• Lors du déplacement d'éléments au sein d'une page, vous n'avez souvent pas besoin de définir des données transférées ; vous manipulez simplement l'élément déplacé.
• Lors du déplacement hors de la page, aucune cible de dépôt n'a besoin d'être définie.

Nous allons examiner comment chacun peut être défini et utilisé.

Éléments déplaçables

En HTML, les images, les liens et les sélections sont déplaçables par défaut. Pour rendre un élément arbitraire déplaçable, définissez l'attribut draggable sur la valeur "true".

<p id="p1" draggable="true">Cet élément est déplaçable.</p>

À ce stade, l'élément a déjà l'apparence de déplacement, bien qu'aucun comportement ne soit encore défini :

Pour les images et les liens, l'attribut draggable est défini par défaut sur true, donc vous ne le définirez sur false que pour désactiver le déplacement de ces éléments. Pour les éléments non déplaçables, le geste de « glisser » sélectionne généralement le texte à la place.

Une sélection est également déplaçable. Dans ce cas, le nœud source, ou le nœud sur lequel divers évènements tels que dragstart et dragend sont déclenchés, est le nœud de texte sur lequel le déplacement a commencé. La sélection peut contenir partiellement ou entièrement plusieurs nœuds, y compris des nœuds de texte et des nœuds d'élément, qui sont tous considérés comme étant déplacés simultanément.

Comme mentionné précédemment, l'élément déplacé peut également être quelque chose qui n'est pas sur une page Web — par exemple, un fichier dans l'explorateur de fichiers du système d'exploitation. Cependant, seuls les éléments sur la page Web peuvent déclencher les évènements dragstart et dragend.

Pour plus d'informations, consultez le guide des opérations de glisser-déposer.

Stockage des données déplacées

Vous ne pouvez pas transférer directement des objets JavaScript vers des pages Web arbitraires, et encore moins vers des applications externes. Pour transférer des données vers et depuis la page Web, les données doivent être sérialisées sous forme de chaîne de caractères (ou sous forme de File). Dans le glisser-déposer, cette chaîne de caractères est encapsulée dans un objet DataTransferItem, qui définit également un type particulier — généralement un type MIME tel que text/html — qui définit comment la chaîne de caractères doit être interprétée.

Chaque opération de glisser-déposer est associée à un stockage de données déplacées qui est un objet DataTransfer accessible par la propriété dataTransfer de DragEvent. Pour les éléments glissables par défaut tels que les images, les liens et les sélections, les données de glissement sont déjà définies par le navigateur ; pour les éléments glissables personnalisés définis à l'aide de l'attribut draggable, vous devez définir vous-même les données de glissement. La seule occasion d'apporter des modifications au magasin de données se situe dans le gestionnaire dragstart — pour le dataTransfer de tout autre évènement de glissement, le magasin de données est non modifiable.

La méthode setData() peut être utilisée pour ajouter un élément aux données de déplacement, comme le montre l'exemple suivant.

function dragstartHandler(ev) {
  // Ajouter différents types de données à déplacer
  ev.dataTransfer.setData("text/plain", ev.target.innerText);
  ev.dataTransfer.setData("text/html", ev.target.outerHTML);
  ev.dataTransfer.setData(
    "text/uri-list",
    ev.target.ownerDocument.location.href,
  );
}

const p1 = document.getElementById("p1");
p1.addEventListener("dragstart", dragstartHandler);

De plus, le seul moment où vous pouvez lire à partir du stockage de données, en dehors de l'évènement dragstart, est pendant l'évènement drop (ce qui permet à la cible de dépôt de récupérer les données). Pour tous les autres évènements, le stockage de données ne peut pas être consulté.

Pour plus d'informations, consultez Travailler avec le stockage des données déplacées.

Cible de dépôt

Une cible de dépôt est un élément sur lequel un·e utilisateur·ice peut déposer un élément déplacé. Par défaut, la plupart des éléments ne sont pas des cibles de dépôt, et si vous relâchez le déplacement, une animation de « retour en arrière » s'affiche, indiquant que le glisser-déposer a échoué. Tout élément peut devenir une cible de dépôt en annulant l'évènement dragover qui se déclenche sur lui avec preventDefault().

L'évènement drop ne se déclenche que sur les cibles de dépôt, et c'est le seul moment où vous pouvez lire le stockage de données.

L'exemple suivant montre une cible de dépôt minimale valide, et combine également le code des exemples précédents.

<p id="cible">Zone de dépôt</p>

const cible = document.getElementById("cible");

// Annuler dragover pour que drop puisse se déclencher
cible.addEventListener("dragover", (ev) => {
  ev.preventDefault();
});
cible.addEventListener("drop", (ev) => {
  ev.preventDefault();
  const donnees = ev.dataTransfer.getData("text/plain");
  ev.target.append(donnees);
});

Pour plus d'informations, consultez Spécification des cibles de dépôt.

Guides

Opérations de déplacement

Décrit les étapes qui se déroulent lors d'une opération de déplacement et ce que l'application doit faire dans chaque gestionnaire.

Travailler avec le stockage des données déplacées

Explique comment lire et écrire dans le stockage des données déplacées pendant une opération de glisser-déposer.

Glisser et déposer des fichiers

Guide pratique pour implémenter une interface basique acceptant des fichiers déposés.

Tableau Kanban avec glisser-déposer

Un guide pratique pour implémenter un tableau Kanban impliquant le glisser-déposer d'éléments au sein d'une page.

Interfaces

DragEvent

L'objet d'évènement passé aux gestionnaires d'évènements de glissement.

DataTransfer

Contient les données transférées entre contextes, constituées d'éléments texte et d'éléments fichier. Initialement conçue pour le glisser-déposer, cette interface est désormais aussi utilisée dans d'autres contextes tels que l'API Presse-papiers.

DataTransferItem

Représente un élément du stockage des données déplacées, qui peut être un élément texte ou un élément fichier.

DataTransferItemList

Représente la liste des objets DataTransferItem dans le stockage des données déplacées.

Exemples

• Copier et déplacer des éléments avec l'interface DataTransfer ^(angl.)
• Copier et déplacer des éléments avec l'interface DataTransferListItem ^(angl.)

Les pages de référence de chaque interface contiennent également des exemples individuels.

Spécifications

Voir aussi

• Les opérations de déplacement
• Travailler avec le stockage des données déplacées
• Standard Vivant de HTML : Glisser et déposer ^(angl.)
• Données d'interopérabilité pour l'API Drag and Drop sur CanIUse ^(angl.)