Objet `dataTransfer`

L’objet dataTransfer est associé à chaque événement de glissement et constitue l’unique canal de communication entre la source et la cible. Il transporte les charges utiles, les listes de fichiers, les effets autorisés et l’effet de dépôt choisi.

La source écrit des charges utiles typées avec e.dataTransfer.setData(format, value). La cible les lit avec e.dataTransfer.getData(format). Les deux arguments sont des chaînes les valeurs sont converties en chaînes avant leur stockage.

Stocker la même charge utile sous plusieurs types rend un glissement interopérable : « text/plain » fonctionne dans n’importe quel éditeur de texte, « text/uri-list » est reconnu par les navigateurs comme une URL et « text/html » conserve la mise en forme dans les traitements de texte. La cible choisit ce qu’elle comprend.

Pour protéger la vie privée, le navigateur expose uniquement la liste des types — et non les valeurs — aux gestionnaires dragenter et dragover via e.dataTransfer.types. Les données réelles ne sont lisibles qu’à l’intérieur de l’événement drop d’une cible qui accepte le dépôt.

Lorsque l’utilisateur fait glisser un élément depuis le bureau, e.dataTransfer.files est une FileList d’objets File. Elle est vide pour les glissements provenant de la page. Considérez-la comme le moyen de référence pour détecter le dépôt externe d’un fichier et accéder à sa taille, son nom et son type.

e.dataTransfer.items expose à la fois les chaînes et les fichiers sous forme d’objets DataTransferItem. Chaque élément possède kind (« string » ou « file »), type (MIME) et getAsString(cb) / getAsFile(). items est l’alternative moderne, consciente des types, à files + getData.

effectAllowed est défini par la source dans dragstart et répertorie les opérations qu’elle prend en charge. dropEffect est défini par la cible dans dragover et choisit l’une de ces opérations. Le navigateur annule le dépôt si les deux valeurs ne correspondent pas.

e.dataTransfer.setDragImage(node, x, y) remplace l’image fantôme par défaut. Transmettez un élément DOM hors écran, stylisé selon vos besoins, ainsi que le décalage du curseur par rapport à cet élément. La modification ne s’applique qu’au glissement en cours.

e.dataTransfer.clearData() efface tous les formats ; clearData("text/plain") en supprime un seul. Cette méthode est rarement nécessaire, car dataTransfer est créé à nouveau pour chaque glissement, mais elle est utile lorsque vous commencez à renseigner des données, puis décidez d’annuler.

Les fichiers déplacés d’une page sur l’origine A vers une page sur l’origine B sont tout de même transmis : l’API fonctionne entre les origines. Cependant, la page réceptrice ne voit que ce que la source a explicitement placé dans dataTransfer : aucun accès arbitraire au DOM ne lui est accordé.

En écrivant le type « DownloadURL » (setData("DownloadURL", "image/png:filename.png:https://...")), une page peut permettre à l’utilisateur de faire glisser un fichier hors du navigateur vers le bureau. La prise en charge est limitée (navigateurs fondés sur Chromium) : détectez cette possibilité et prévoyez une solution de repli appropriée.

Pourquoi dataTransfer.getData() n'est-il pas autorisé à renvoyer la valeur réellement stockée pendant l'événement dragover ?

dataTransfer fait le lien entre la source du glissement et la cible du dépôt. Utilisez setData/getData pour des charges utiles sous forme de chaînes typées, items pour une vue unifiée des fichiers et des chaînes, files pour les dépôts depuis un ordinateur, setDragImage pour les aperçus personnalisés, et effectAllowed/dropEffect pour négocier l'opération.