Spécification de la Traversée d'Éléments
Ce document est la traduction en français de la Recommandation du W3C
portant sur la Traversée d'Éléments (22 Décembre 2008).
Cette recommandation est une version traduite qui peut comporter des
erreurs. La seule version normative et originale est la version
anglaise, qui se trouve à :
Adresse
Traducteur
Xavier Lacot
-
Relecteur
: Guillaume Saint-Raymond
Date de début de traduction
: 8 Janvier 2009
Date de fin de traduction
: 20 Janvier 2009
Dernière mise à jour
: 20 Janvier 2009
Spécification de la Traversée d'Éléments
Recommandation du W3C - 22 Décembre 2008
Cette version :
Dernière version :
Version précédente :
Éditeurs :
Doug Schepers
W3C
, auparavant
Vectoreal
) <
schepers@w3.org
Robin Berjon (auparavant Expway) <
robin@berjon.com
>, jusqu'en 2006
Veuillez consulter l'
errata
de ce document, qui peut inclure quelques corrections normatives.
Consultez également les
traductions
Droit de copie
W3C
MIT
ERCIM
Keio
), tous droits réservés. Les règles de
responsabilité
, de
nom de marque
et d'
utilisation de document
du W3C s'appliquent.
Résumé
Cette spécification définit l'interface
ElementTraversal
, qui permet une navigation au sein des éléments d'un arbre DOM à l'aide de scripts, à l'exclusion de tous les autres nœuds du DOM comme les nœuds de texte. Elle fournit par ailleurs un attribut permettant d'obtenir le nombre d'éléments fils d'un élément. L'objectif est d'offrir une meilleure alternative aux interfaces de parcours de DOM existantes, avec une empreinte d'implémentation faible.
Statut de ce Document
Ce chapitre décrit le statut de ce document au moment de sa publication. D'autres documents pourront remplacer ce document. Une liste des publications courantes du W3C et les dernières révisions de ce rapport technique peuvent être trouvées dans l'
index des rapports techniques du W3C
à l'adresse http://www.w3.org/TR/.
Ceci est la Recommandation du 22 Décembre 2008 au sujet de la spécification de Traversée d'Élements.
Ce document a été revu par les membres du W3C, par les développeurs de logiciels, et par tous les autres groupes du W3C et les tiers concernés, et a été approuvé par le Directeur comme Recommandation du W3C. C'est un document stable qui peut être utilisé comme document de référence ou cité comme norme de référence par un autre document. Le rôle du W3C, en produisant cette recommandation, est de mettre en lumière la spécification et d'en promouvoir le plus large déploiement. Ceci permet d'améliorer le fonctionnement et l'interopérabilité du Web.
Le
Groupe de Travail Web Applications (WebApps)
a produit une
suite de tests
et un
rapport d'implémentation
afin d'indiquer le niveau actuel de support d'implémentation pour cette spécification, avec des résultats positifs pour tous les tests. Il n'y a pas eu de changements depuis la Proposition de Recommandation.
Merci d'envoyer les questions et commentaires à propos de cette spécification à
public-webapps@w3.org
, la liste de diffusion publique au sujet des livrables du Groupe de Travail WebApps. Cette liste propose une
archive
publique, et l'acceptation de cette politique d'archivage est automatiquement requise au premier message. Afin de vous inscrire à cette liste, envoyez un email à
public-webapps-request@w3.org
avec le mot "subscribe" dans la ligne de sujet.
Ce document a été produit par le
Groupe de Travail Web Applications (WebApps)
au sein de l'
Activité Clients Web Riches
du W3C, conformément aux procédures mises en place pour les
Processus
du W3C.
L'interface
ElementTraversal
a originellement été publiée comme partie de la
spécification SVG Tiny 1.2
dans l'espace de nommage SVG. À la demande des groupes SVG, CDF, JCP, et d'autres groupes, elle a été transférée au WebAPI WG, et a migré par facilité vers DOM et l'espace de nommage DOM. Elle a été à nouveau transférée lorsque le WebApps WG a pris la responsabilité des livrables du WebAPI WG.
Ce document a été produit par un groupe agissant sous couvert de la
politique de brevets du W3C du 5 février 2004
. Le W3C maintient une
liste publique des divulgations de brevets
faites en lien avec les produits livrables du groupe; cette page contient également des instructions pour divulguer un brevet. Quiconque aurait connaissance d'un brevet dont il pense qu'il contient des
Revendication(s) Essentielle(s)
doit divulguer cette information conformément à la
section 6 de la Politique de Brevets du W3C
Contenu
1. Introduction
1.1. Ce qui n'est pas dans cette spécification
1.2. Conformité
2. L'interface
ElementTraversal
2.1.
firstElementChild
2.2.
lastElementChild
2.3.
previousElementSibling
2.4.
nextElementSibling
2.5.
childElementCount
3. Exemples d'utilisation
3.1. Exemple de
previousElementSibling
3.2. Exemple de Valeurs Pré-calculées et de Bouclage au Travers des Éléments
3.3. Exemple de Comparaison avec d'Autres Interfaces DOM
4. Relations avec d'autres spécifications
DOM
4.1. Noyau de
DOM
Niveau 1
4.2.
DOM
Niveau 2 Traversal et Range
4.3. Noyau de
DOM
Niveau 3
5. Considérations de Sécurité
A. Définitions IDL
B. Correspondances avec le langage ECMAScript
C. Correspondances avec le langage Java
D. Historique des Changements
E. Références
F. Remerciements
1. Introduction
Cette section est informative.
L'interface du
Noyau
de DOM Niveau 1 définit 11 types de nœuds, mais de manière courante les auteurs utilisent uniquement le
nodeType
, le nœud
Element
. Les autres types de nœuds incluent les nœuds d'élément
Document
et de
Text
, ce qui inclut les espaces blancs et les sauts de ligne. La traversée de nœuds de DOM 1 inclut tous ces types de nœuds, ce qui est souvent une source de confusion pour les auteurs, et nécessite un travail supplémentaire de la part des auteurs afin de confirmer que les interfaces de nœud
Element
attendues sont bien disponibles. Ceci introduit une contrainte de performance additionnelle.
ElementTraversal
est une interface qui permet aux auteurs de restreindre la navigation aux nœuds
Element
. Elle permet la navigation d'un élément à son premier élément fils, son dernier élément fils, et à ses éléments frères suivants ou précédents. Comme l'implémentation expose uniquement les nœuds élément, l'empreinte mémoire et calculatoire de la représentation DOM peut être optimisée pour les appareils limités.
L'interface
Node
DOM de niveau 1 définit également l'attribut
childNodes
, qui est une liste vivante de tous les nœuds enfants du nœud; la liste
childNodes
a un attribut
length
qui expose le nombre total de nœuds enfants de tous
nodeTypes
, ce qui est utile pour préparer les opérations et calculs avant ou à la place d'un parcours des nœuds enfants. L'interface
ElementTraversal
a un attribut similaire,
childElementCount
, qui indique seulement le nombre de nœuds
Element
, ce qui est souvent attendu pour de telles opérations.
1.1. Ce qui n'est pas dans cette spécification
Cette spécification n'inclut pas la liste complète des attributs, méthodes, et des autres interfaces disponibles pour l'objet
Element
. Les interfaces additionnelles peuvent être trouvées dans d'autres spécifications, notamment les spécifications du Noyau de DOM.
1.2. Conformité
Cette section est normative.
Dans ce document, les mots-clés "
DOI(VEN)T
",
NE DOI(VEN)T PAS
",
REQUIS
",
DEVRA
",
NE DEVRA PAS
",
DEVRAIT
",
NE DEVRAIT PAS
",
RECOMMANDÉ
",
PEUT
",
et "
OPTIONNEL
" doivent s'interpréter comme décrit dans le document [
RFC2119
]. À des fins de lisibilité, ces termes ne sont pas nécessairement employés de manière sensible à la casse dans ce document.
Parfois, pour des raisons de lisibilité, les besoins de conformité sont exprimés comme contraintes sur les éléments, attributs, méthodes, interfaces, propriétés ou fonctions. Dans tous les cas, ces exigences de conformité portent sur les implémentations. Une implémentation conforme à cette spécification respecte toutes les contraintes identifiées par l'usage de ces termes, dans le champ d'application des correspondances avec son langage.
2. L'interface
ElementTraversal
Cette section est normative.
L'interface
ElementTraversal
est un ensemble d'attributs en lecture seule, qui permet aux auteurs de naviguer aisément entre les éléments dans un document. Dans les implémentations conformes de la Traversée d'Élément, tous les objets qui implémentent
Element
doivent également implémenter l'interface
ElementTraversal
. Quatre des attributs,
firstElementChild
lastElementChild
previousElementSibling
, et
nextElementSibling
, fournissent chacun une référence vivante à un autre élément ayant la relation définie à l'élément courant, si cet élément en relation existe. Le cinquième attribut,
childElementCount
, présente le nombre d'éléments enfants d'un élément, pour pré-traitement avant navigation. Un agent Utilisateur conforme doit implémenter tous ces cinq attributs. Un Agent Utilisateur peut implémenter des interfaces similaires dans d'autres spécifications, mais une telle implémentation n'est pas requise pour la conformité à cette spécification, si l'Agent Utilisateur est conçu pour une empreinte de code minimale.
Cette interface doit être implémentée sur tous les
Element
s, quel que soit leur espace de nommage. Les nœuds EntityReference ne sont pas visibles au mécanisme de la Traversée d'Éléments ; si l'objet
TreeWalker
rencontre un nœud EntityReference, il descend dans ce nœud sans en informer l'appelant, et traite tous les enfants comme s'ils avaient été présents à la place où le nœud d'entité a été trouvé. La navigation doit être indifférente aux espaces de nommage. Par exemple, si un élément de l'espace de nommage HTML est suivi par un élément de l'espace de nommage SVG, l'attribut
nextElementSibling
de l'élément HTML retournera l'élément SVG.
2.1.
firstElementChild
L'accès à cet attribut d'un élément doit retourner une référence au premier nœud fils de
nodeType
de cet élément, sous la forme d'un objet
Element
. Si l'élément pour lequel cet attribut est demandé n'a aucun nœud enfant, ou si aucun de ces nœuds enfants n'est un nœud élément, alors cet attribut doit retourner
null
2.2.
lastElementChild
L'accès à cet attribut d'un élément doit retourner une référence au dernier nœud fils de
nodeType
de cet élément, sous la forme d'un objet
Element
. Si l'élément pour lequel cet attribut est demandé n'a aucun nœud enfant, ou si aucun de ces nœuds enfants n'est un nœud élément, alors cet attribut doit retourner
null
2.3.
previousElementSibling
L'accès à cet attribut d'un élément doit retourner une référence au nœud frère de cet élément qui précède immédiatement cet élément dans l'ordre du document, et qui est de
nodeType
, sous la forme d'un objet
Element
. Si l'élément pour lequel cet attribut est demandé n'a aucun nœud frère le précédant, ou si aucun de ses nœuds frères le précédant n'est un nœud élément, alors cet attribut doit retourner
null
2.4.
nextElementSibling
L'accès à cet attribut d'un élément doit retourner une référence au nœud frère de cet élément qui succède immédiatement à cet élément dans l'ordre du document, et qui est de
nodeType
, sous la forme d'un objet
Element
. Si l'élément pour lequel cet attribut est demandé n'a aucun nœud frère lui succédant, ou si aucun de ses nœuds frères lui succédant n'est un nœud élément, alors cet attribut doit retourner
null
2.5.
childElementCount
L'accès à cet attribut d'un élément doit retourner le nombre courant des nœuds enfants de cet élément qui sont de
nodeType
. Une implémentation peut stocker ce nombre, ou elle peut le calculer lors de son accès, mais ce nombre doit toujours représenter le nombre des nœuds éléments enfants au moment de l'accès à l'attribut. Seul les nœuds enfants immédiats doivent être comptés. Par exemple, les éléments qui sont des nœuds enfants d'un des nœuds enfants de l'élément pour lequel l'attribut est demandé, ne sont pas inclus dans ce décompte. Si l'élément pour lequel cet attribut est demandé n'a aucun nœud enfant, ou si aucun de ces nœuds enfants n'est un nœud élément, alors cet attribut doit retourner 0.
3. Exemples d'utilisation
Cette section est informative.
Cette section illustre différents exemples ECMAScript [
ECMA262
] utilisant la Traversée d'Élément.
3.1. Exemple of
previousElementSibling
Cet exemple démontre l'utilité de l'attribut
previousElementSibling
. Le code suivant prend en paramètre un élément, et retourne la position de cet élément dans l'ordre du document au sein de son parent :
function findPosition( el ) {
var pos = 0;
// parcours des éléments fils en ordre inverse
while ( null != el ) {
// navigue au frère précédent
el = el.previousElementSibling;
pos++;
return pos;
3.2. Exemple de Valeurs Pré-calculées et de Bouclage au Travers des Éléments
Cet exemple démontre l'utilité de l'attribut
childElementCount
. Le code suivant prend en paramètre un élément, et place chacun de ses enfants de manière équidistante en fonction de l'espace disponible :
function spaceChildren( el ) {
// obtient le nombre de nœuds éléments
var elCount = el.childElementCount;
var eachWidth = window.innerWidth / (elCount + 1);
// obtient le premier élément enfant
var childEl = el.firstElementChild;
// fixe la position initiale
var nextPos = eachWidth/2;
// parcourt un à un les éléments enfants
while ( childEl ) {
// positionne l'enfant
childEl.style.setProperty( 'position', 'absolute', '' );
childEl.style.setProperty( 'left', nextPos + 'px', '' );
childEl.style.setProperty( 'width', eachWidth + 'px', '' );
// incrémente la position avec la largeur
nextPos += eachWidth;
// puis navigue au prochain élément enfant
childEl = childEl.nextElementSibling;
3.3. Exemple de Comparaison avec d'Autres Interfaces DOM
Cet exemple met en contraste
ElementTraversal
avec d'autres interfaces DOM. Le script suivant montre différentes méthodes d'itération au travers d'un arbre DOM, étant donné le fragment SVG suivant :
function walkTest( el ) {
// obtient le nombre de tous les nœuds
var nodeCount = el.childNodes.length;
// obtient le premier nœud enfant
var firstNode = el.firstChild;
// obtient le premier element enfant
var childEl = el.firstElementChild;
// parcourt un à un les éléments enfants
while ( childEl ) {
// faire quelque chose d'utile ici...
// puis navigue au prochain élément enfant
childEl = childEl.nextElementSibling;
Où
el
est l'élément
'g'
avec l'
'id'
"shapeGroup"
nodeCount
aura la valeur
11
firstNode
sera un nœud
Text
nodeType
of
), et n'est pas équivalent à la première valeur assignée à
childEl
, qui est un nœud
Element
nodeType
of
) avec l'
'id'
"rect1"
. La boucle
while
va boucler 4 fois supplémentaires, itérant parmi les nœuds
Element
frères, respectivement
"rect2"
"ellipse1"
"path1"
, et
"text1"
. La dernière valeur de
childEl
sera
null
, étant donné que
"text1"
n'a pas d'élément frère lui succédant, bien qu'il a un nœud lui succédant.
Veuillez noter qu'un élément SVG
'text'
n'est pas la même chose qu'un nœud
Text
. Veuillez également noter que l'élément SVG
'textPath'
fils de l'élément
'text'
n'est pas inclus dans l'itération, étant donné que ce n'est pas un frère de
childEl
4. Relations avec d'autres spécifications
DOM
Cette section est informative.
4.1. Noyau de
DOM
Niveau 1
Cette spécification fournit une interface qui a des similarités fonctionnelles avec les attributs de navigation DOM du Noyau de DOM 1, mais qui opèrent uniquement sur les nœuds éléments, et pas sur les autres types de nœuds. Les attributs du Noyau de DOM 1 les plus comparables sont :
firstChild
lastChild
previousSibling
nextSibling
, et
nodeList.length
4.2.
DOM
Niveau 2 Traversal et Range
Le Modèle Objet de Document de Niveau 2
Traversal & Range
est une spécification exhaustive de la navigation dans un document, mais peut nécessiter plus de ressources matérielles et d'implémentation que la Traversée d'Éléments. Comme la Traversée d'Éléments est un sous-ensemble de la fonctionnalité de la
Traversée
de DOM 2, un agent utilisateur implémentant les deux peut le faire d'une manière qui tire partie des fonctionnalités de la Traversée.
4.3. Noyau de
DOM
Niveau 3
Ceci est une spécification s'ajoutant au
Noyau de DOM 3
5. Considérations de Sécurité
Cette section est informative.
Aucune considération de sécurité connue n'est impliquée dans l'implémentation ou l'emploi de l'interface
ElementTraversal
. Cette section pourra être révisée si de futures considérations de sécurité sont découvertes.
A. Définitions IDL
Définition IDL
interface ElementTraversal
readonly attribute Element
firstElementChild
readonly attribute Element
lastElementChild
readonly attribute Element
previousElementSibling
readonly attribute Element
nextElementSibling
readonly attribute unsigned long
childElementCount
};
Aucune constante définie
Attributs
firstElementChild
Retourne le premier nœud élément fils de cet élément.
null
si cet élément n'a aucun élément fils.
lastElementChild
Retourne le dernier nœud élément fils de cet élément.
null
si cet élément n'a aucun élément fils.
previousElementSibling
Retourne nœud élément frère précédant cet élément.
null
si cet élément n'a aucun élément frère le précédant dans l'arbre du document.
nextElementSibling
Retourne nœud élément frère suivant cet élément.
null
si cet élément n'a aucun élément frère le suivant dans l'arbre du document.
childElementCount
Retourne le nombre courant des nœuds éléments qui sont enfants de cet élément.
si cet élément n'a aucun élément fils de
nodeType
Aucune méthode définie
B. Correspondances avec le langage ECMAScript
Objet
Element
Dans un agent Utilisateur qui implémente l'interface
ElementTraversal
Element
a toutes les propriétés et méthodes de
Node
et
Element
comme défini dans d'autres spécifications DOM, et dispose en plus des propriétés suivantes :
firstElementChild
Cette propriété en lecture seule est de type
Element
lastElementChild
Cette propriété en lecture seule est de type
Element
previousElementSibling
Cette propriété en lecture seule est de type
Element
nextElementSibling
Cette propriété en lecture seule est de type
Element
childElementCount
Cette propriété en lecture seule est de type
Number
C. Correspondances avec le langage Java
org/w3c/dom/ElementTraversal.java:
package org.w3c.dom;
public interface ElementTraversal
Element getFirstElementChild();
Element getLastElementChild();
Element getPreviousElementSibling();
Element getNextElementSibling();
int getChildElementCount();
D. Historique des Changements
Diverses modifications éditoriales, corrections et modifications aux exemples ont été faites de brouillon en brouillon.
L'attribut
childElementCount
a été ajouté à la proposition originelle, pour les raisons expliquées dans cette spécification.
E. Références
Références Normatives
RFC2119
Key words for use in RFCs to indicate Requirement Levels
, S. Bradner, mars 1997. La spécification indiquant comment utiliser l'Anglais comme s'il s'agissait d'un langage technique fait pour indiquer des contraintes normatives.
DOM1Core
Document Object Model - Level 1 Core
, V. Apparao, S. Byrne, M. Champion, S. Isaacs, I. Jacobs, A. Le Hors, G. Nicol, J. Robie, R. Sutor, C. Wilson, L. Wood, Editors. World Wide Web Consortium, 1er octobre 1998. Un ensemble standard d'objets pour représenter des documents HTML et XML, un modèle standard de la manière de combiner ces objets, et une interface standard pour y accéder et les manipuler.
ECMA262
Standard ECMA-262, 3
rd
edition
. ECMA International, décembre 1999. La spécification du langage ECMAScript, duquel JavaScript est un dialècte.
Références informatives
SVGD
The SVG Micro DOM (uDOM)
, O. Andersson, R. Berjon, E. Dahlström, A. Emmons, J. Ferraiolo, V. Hardy, S. Hayman, D. Jackson, C. Lilley, A. Neumann, C. Northway, A. Quint, N. Ramani, D. Schepers, A. Shellshear, Editors. World Wide Web Consortium, 10 août 2006. L'interface
ElementTraversal
proposée en SVG.
DOM2TR
Document Object Model (DOM) Level 2 Traversal and Range Specification
, J. Kesselman, J. Robie, M. Champion, P. Sharpe, V. Apparao, L. Wood, Editors. World Wide Web Consortium, 13 novembre 2000. Un ensemble d'interfaces indépendantes de la plateforme ou du langage, qui permettent aux programmes et aux scripts de traverser dynamiquement un document et d'en identifier une partie du contenu.
DOM3Core
Document Object Model (DOM) Level 3 Core Specification
, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, Editors. World Wide Web Consortium, 07 avril 2004. Une interface indépendante de la plateforme ou du langage qui permet aux programmes et aux scripts d'accéder dynamiquement et de mettre à jour le contenu, la structure et le style de documents.
F. Remerciements
L'éditeur aimerait remercier les personnes suivantes pour leur contribution à cette spécification: David Andersson, Robin Berjon, Jean-Yves Bitterlich, Sergiu Dumitriu, Daniel Glazman, Bjoern Hoehrmann, Kurosawa Takeshi, Chris Lilley, Charles McCathieNevile, Cameron McCormack, Simon Pieters, Nandini Ramani, Jonas Sicking, Andrew Sledd, Josh Soref, Anne van Kesteren, Boris Zbarsky, et Mohamed Zergaoui. L'éditeur aimerait également remercier le
WG
SVG pour avoir produit le brouillon [
SVGD
] sur lequel cette publication est initialement basée.