L'objet DataTransfer
contient les données glissées au cours d'une opération de glisser-déposer. Il peut contenir un ou plusieurs éléments, du même type ou de types différents. Pour plus d'informations sur le glisser-déposer, voir Glisser et déposer.
Cet objet est disponible depuis la propriété dataTransfer
de tous les événements de glisser. Il ne peut pas être créé séparément.
Aperçu des proprietés
Propriété | Type |
dropEffect |
String |
effectAllowed |
String |
files |
FileList |
mozCursor |
String |
mozItemCount |
unsigned long |
mozSourceNode |
Node |
mozUserCancelled |
Boolean |
types |
StringList |
Aperçu des méthodes
void addElement(in Element image) |
void clearData([in String type]) |
String getData(in String type) |
void setData(in String type, in String data) |
void setDragImage(in nsIDOMElement image, in long x, in long y) |
void mozClearDataAt([in String type, in unsigned long index]) |
nsIVariant mozGetDataAt(in String type, in unsigned long index) |
void mozSetDataAt(in String type, in nsIVariant data, in unsigned long index) |
StringList mozTypesAt([in unsigned long index]) |
Propriétés
dropEffect
L'effet utilisé, qui doit toujours être l'une des valeurs possibles de effectAllowed
.
Pour les événements d
ragenter
et dragover
, la propriété dropEffect
est initialisée en fonction des actions initiées par l'utilisateur. Ceci est spécifique à la plateforme, mais en général, l'utilisateur peut appuyer sur les touches de modification pour ajuster l'action souhaitée. Dans un gestionnaire d'événement d
ragenter
et dragover
, la propriété dropEffect
peut être modifiée si l'action de l'utilisateur demandée n'est pas celle souhaitée.
Pour les évènements dragstart
, drag
, and dragleave
events, dropEffect
est initialisé à "none". Toute valeur peut être assignée à dropEffect
, mais elle sera ignorée.
Pour les évènements drop
et dragend
, dropEffect
est initialisé en fonction de l'action initiée, et correspond à la dernière valeur de dropEffect
après le dernier événement dragenter
ou dragover
.
Valeurs possibles:
- copy: Une copie de l'élément source est faite au nouvel emplacement.
- move: Un élément est déplacé vers un nouvel emplacement.
- link: Un lien est établi depuis la source vers le nouvel emplacement.
- none: L'élément ne peut pas être déposé.
Attribuer une autre valeur n'a aucun effet et conserve l'ancienne valeur.
effectAllowed
Indique les effets qui sont autorisés pour ce déplacer. Il peut être spécifié dans l'évènement dragstart
pour définir les effets souhaités pour la source, et dans les événements dragenter
et dragover
pour définir les effets souhaités pour la cible. La valeur n'est pas utilisée pour d'autres événements.
Valeurs possibles:
- copy: Une copie de l'élément source peut être faite à son nouvel emplacement.
- move: Un élément peut être déplacé vers un nouvel emplacement.
- link: Un lien peut être établi vers la source depuis le nouvel emplacement.
- copyLink: Une opération copy ou link est autorisée.
- copyMove: Une opération copy ou move est autorisée.
- linkMove: Une opération link ou move est autorisée.
- all: Toutes les opérations sont autorisées.
- none: l'élément ne peut être déposé.
- uninitialized: la valeur par défaut lorsque l'effet n'a pas été spécifié, ce qui équivaut à all.
Attribuer une autre valeur n'a aucun effet et conserve l'ancienne valeur.
files
Contient une liste de tous les fichiers locaux disponibles sur le transfert de données. Si le glisser n'implique pas de fichiers, cette propriété est une liste vide. Un accès à un index invalide sur le FileList
spécifié par cette propriété renvoie null
.
Exemple
Cet exemple retourne la liste des fichiers traînée dans la fenêtre du navigateur.
Unable to find file filednd.html
See this in effect at: https://jsfiddle.net/9C2EF/
types
Contient une liste des types de format des données stockées pour le premier élément, dans le même ordre oú les données ont été ajoutées. Une liste vide sera retournée si aucune donnée n'a été ajoutée.
mozCursor
(Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)L'état du curseur au cours d'un glisser. Cette propriété est surtout utilisée pour contrôler le curseur au cours d'un glisser d'onglet.
Valeurs possibles
-
auto
- Utilise le comportement par défaut du système.
-
default
- Utilise le comportement par défaut de Gecko, qui consiste à utiliser une flèche pour curseur au cours d'un glisser.
mozItemCount
Le nombre d'éléments glissés.
mozSourceNode
le Node
au dessus duquel le curseur de la souris se trouvait lorsque le bouton a été pressé pour initialiser le glisser. Cette valeur est nulle pour un glisser externe, ou si l'appelant ne peut pas accéder au nœud.
mozUserCancelled
Cette propriété s'applique uniquement à l'événement dragend
, et est positionnée à true
si l'utilisateur a annulé le glisser en appuyant sur la touche échappe. Elle est positionnée à false
dans les autres cas, y compris si le glisser a échoué pour toute autre raison, par exemple en raison d'un déposer sur un emplacement non valide. Cette propriété n'est pas encore implémenté sous Linux.
Methods
addElement()
Spécifie la source du glisser. Ceci est rarement utilisé, mais a pour effet de modifier la cible des événements drag
et dragend
. La cible par défaut est le nœud qui est glissé.
void addElement( in Element element );
Parametres
-
element
- L'élément à ajouter.
clearData()
Supprime les données associées au type spécifié. L'argument type est facultatif. Si le type est vide ou non spécifié, les données associées à tous les types sont supprimées. Si les données pour le type spécifié n'existent pas, ou le transfert de données ne contient pas de données, cette méthode n'aura aucun effet.
void clearData( [optional] in String type );
Parametres
-
type
- The type of data to remove.
getData()
Récupère les données du type spécifié, ou une chaîne vide si les données de ce type n'existe pas ou le transfert de données ne contient aucune donnée.
Une erreur de sécurité se produira si vous tentez de récupérer des données lors d'un glisser qui a été spécifié à partir d'un domaine différent ou auquel l'appelant n'a pas accès. Ces données ne seront disponibles qu'à l'issue du déposer au cours d'un événement drop.
void getData( in String type );
Parametres
-
type
- Le type de donnée à récupérer.
setData()
Définit une donnée pour le type spécifié. Si des données pour le type n'existe pas, elle est ajoutée à la fin, de telle sorte que le dernier élément dans la liste des types sera le nouveau format. Si une donnée pour le type existe déjà, la donnée existante est remplacée à la même position. C'est-à-dire que l'ordre de la liste des types ne change pas lors du remplacement de la donnée d'un même type.
void setData( in String type, in String data );
Parametres
-
type
- Le type de la donnée à ajouter.
-
data
- La donnée à ajouter.
setDragImage()
Définit l'image à utiliser pour un glisser, si une image personnalisée est souhaitée. Cette méthode est rarement utilisée, dans la mesure oú une image par défaut est créée à partir du nœud glissé.
Si le nœud est un élément HTML img, un élément canvas HTML ou un élément d'image XUL, la donnée image est utilisée. Sinon, l'image doit être un nœud visible et l'image utilisée pendant le glisser est créée à partir de ce noeud. Si l'image est null, toute image personnalisé est effacée et la valeur par défaut est utilisée à la place.
Les coordonnées spécifient le décalage à l'intérieur de l'image spécifiant la position du curseur de la souris. Pour centrer l'image, par exemple, utiliser des valeurs qui sont la moitié de la largeur et de la hauteur de l'image.
void setDragImage( in Element image, in long x, in long y );
Parametres
-
image
- Un élément à utiliser comme image pendant le glisser
-
x
- Décalage horizontal à l'intérieur de l'image.
-
y
- Décalage vertical à l'intérieur de l'image.
mozClearDataAt()
Supprime les données associées au format pour un élément à l'index spécifié. L'index est compris entre zéro et le nombre d'éléments moins un.
Si le dernier format de l'élément est supprimé, l'élément entier est retiré, réduisant mozItemCount
par un.
Si la liste format
est vide, alors les données associées à tous les formats sont supprimées. Si le format n'est pas trouvé, alors cette méthode n'a aucun effet.
void mozClearDataAt( [optional] in String type, in unsigned long index );
Parametres
-
type
- Le type de la donnée à supprimer.
-
index
- L'index de la donnée à supprimer.
mozGetDataAt()
Récupère les données associées au format donné pour un élément à l'index spécifié, ou null si elle n'existe pas. L'indice devrait être compris entre zéro et le nombre d'éléments moins un.
nsIVariant mozGetDataAt( [optional] in String type, in unsigned long index );
Parametres
-
type
- Le type de donnée à récupérer.
-
index
- L'indice de la donnée à récupérer.
mozSetDataAt()
Un transfert de données peut stocker plusieurs éléments, chacun à un index commençant à zéro. mozSetDataAt(
)
ne peut être appelé qu'avec un index inférieur à mozItemCount,
auquel cas un élément existant est modifié, ou égal à mozItemCount,
auquel cas un nouvel élément est ajouté, et mozItemCount
est incrémenté de un.
Les données doivent être ajoutées par ordre de préférence, avec le format le plus spécifique ajouté en premier et le format moins spécifique ajouté en dernier. Si la donnée du format spécifié existe déjà, elle est remplacée dans la même position que la donnée précédente.
La donnée doit être une chaîne, ou un type primitif booléen, ou un type numérique (qui sera converti en une chaîne), ou une nsISupports
.
void mozSetDataAt( [optional] in String type, in nsIVariant data, in unsigned long index );
Parametres
-
type
- Le type de donnée à ajouter.
-
data
- La donnée à ajouter.
-
index
- L'index de la donnée à ajouter.
mozTypesAt()
Contient une liste des types de format des données qui sont stockées pour un élément à l'index spécifié. Si l'index n'est pas dans compris entre 0 et le nombre d'éléments moins un, une liste de chaîne vide est retournée.
nsIVariant mozTypesAt( in unsigned long index );
Parameters
-
index
- L'index de la donnée pour laquelle récupérer les types.