Spécification de la Traversée d'Éléments

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 1, 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.

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 Elements, 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 1 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 1 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 1, 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 1, 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 1. 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 :

<g id='shapeGroup'>

   <rect id='rect1' x='5' y='5' width='310' height='220' rx='15' ry='15' fill='skyblue'/>
   <rect id='rect2' x='15' y='15' width='210' height='180' rx='15' ry='15' fill='cornflowerblue'/>

   <ellipse id='ellipse1' cx='90' cy='70' rx='50' ry='30' fill='yellow' stroke='orange'/>

   <path id='path1' stroke-width='15' stroke='orange' fill='none' stroke-linecap='round'
      d='M25,150 C180,180 290,0 400,140 S420,100 460,90'/>
   <text id='text1' x='0' y='0' font-size='35' fill='yellow' stroke='orange'
      stroke-width='2' stroke-linejoin='round' font-weight='bold'>
      <textPath id='textPath1' xlink:href="#path1">when life gives you lemons...</textPath></text>

</g>

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 3), et n'est pas équivalent à la première valeur assignée à childEl, qui est un nœud Element (nodeType of 1) 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.

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

B. Correspondances avec le langage ECMAScript

C. Correspondances avec le langage 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.