L'objet Range du DOM W3C, similaire conceptuellement à l´objet TextRange de IE, représente une séquence de zéro caractère de texte affiché ou plus dans un document. Une plage de texte comprenant zéro caractère représente un point d'insertion situé entre deux caractères (il peut également se situer avant le premier ou après le dernier caractère du document). L´objet Range effectue automatiquement le suivi des références de décalage de caractères et de noeuds pour les points de début et de fin de la plage. De ce fait, sa méthode peut copier le contenu existant, supprimer le contenu de la plage ou insérer un nouveau contenu (sous la forme de noeuds) dans la plage existante, tout en maintenant en permanence l´intégrité de l´arborescence de documents. La structure axée sur les noeuds est importante pour l´objet Range, mais la plupart de ces problèmes sont traités pour vous.

Un objet Range est créé par le biais de la méthode document.createTextRange( ) ou en transformant une sélection de l´utilisateur en plage par le biais de window.getSelection().getRangeAt(0). Après avoir créé une plage de texte, vous pouvez utiliser les méthodes correspondantes pour déterminer les points de début et de fin d'un segment de texte spécifique. Puis, choisissez parmi un ensemble de méthodes supplémentaires pour agir sur la plage. Reportez-vous au chapitre 5 pour des détails et des exemples de l´utilisation de l´objet Range et ses différences de syntaxe par rapport à l´objet TextRange IE.

Renvoie la valeur booléenne true si les points de début et de fin de la plage sont au même emplacement, sans aucun caractère entre eux. Une plage réduite peut se trouver n´importe où dans le document.

Renvoie une référence à un noeud d´arborescence de documents du contenu parent immédiat qui comprend les points de début et de fin de la plage actuelle. Si les points de début et de fin se trouvent eux-mêmes dans le même noeud (par exemple, le même noeud de texte), la propriété commonAncestorContainer renvoie une référence au noeud parent de ce noeud. L´équivalent de l´objet TextRange IE est parentElement( ).

Renvoie une référence à un noeud d´arborescence de documents qui comprend le point de fin de la plage actuelle.

Renvoie un nombre entier de caractères ou de noeuds pour l´emplacement du point de fin au sein du noeud rapporté par la propriété endContainer. Si endContainer est un noeud de texte, la propriété endOffset compte le nombre de caractères à droite du premier caractère de noeud de texte. Si endContainer est un noeud élément, la propriété endOffset compte le nombre de noeuds entre le début et le point de fin du contenu du noeud conteneur.

Par exemple, regardez le segment de document suivant. Il montre une plage de texte en caractères gras, avec les points de début et de fin indiqués par des barres verticales:

Renvoie une référence à un noeud d´arborescence de documents qui comprend le point de début de la plage actuelle.

Renvoie un nombre entier de caractères ou de noeuds pour l´emplacement du point de début au sein du noeud rapporté par la propriété startContainer. Si startContainer est un noeud de texte, la propriété startOffset compte le nombre de caractères à droite du premier caractère de noeud de texte. Si startContainer est un noeud élément, la propriété startOffset compte le nombre de noeuds entre le début du contenu du noeud conteneur et le point de début. Reportez-vous à endOffset pour plus de détails.

Renvoie un noeud DocumentFragment contenant une copie du contenu de la plage actuelle. Tous les noeuds en suspens sont résolus dans le processus de clonage.

Renvoie un objet Range qui est une copie carbone de la plage actuelle, y compris les références aux conteneurs associés. Cette méthode vous permet de préserver une copie des spécifications de l´objet Range tout en créant un nouvel objet Range. Similaire à la méthode duplicate( ) de l´objet TextRange.

collapse(toStartFlag)

Réduit la plage actuelle à un point d´insertion (les points de début et de fin sont dans le même noeud au même décalage). La valeur booléenne contrôle si la plage est réduite au niveau du point de début (true) ou du point de fin (false) de la plage actuelle. Un script parcourant un document (par exemple en utilisant la méthode String.indexOf( ) pour chercher l´instance suivante d´une chaîne) effectue généralement la réduction au niveau du point de fin avant de déplacer le point de fin à l´extrémité du corps afin d´effectuer la recherche String.indexOf( ) suivante.

compareBoundaryPoints(compareType, sourceRangeRef)

Renvoie un code, sous la forme d´un nombre entier, indiquant l´emplacement relatif d´un point de début ou de fin de la plage actuelle par rapport à un point de début ou de fin d´une autre plage de texte. Dans le cas le plus simple, les deux points d´extrémité (un de chaque plage) partagent le même conteneur parent. Dans ce cas, le premier paramètre détermine si ce sont les points de début ou de fin des deux plages qui sont comparés. Utilisez les constantes fournies avec chaque objet Range, comme l´illustre le tableau suivant.

Dans le document, si la première extrémité de la comparaison se trouve avant la deuxième, la valeur renvoyée est –1 . Si la première extrémité de la comparaison se trouve après la deuxième, la valeur renvoyée est 1. Si les deux extrémités se trouvent au même emplacement, la valeur renvoyée est 0. Similaire à la méthode compareEndPoints( ) de l´objet TextRange dans IE.

Mais le problème peut s´avérer plus complexe si les points d´extrémité qui sont comparés ont des noeuds conteneurs parents différents. Les valeurs de décalage des noeuds conteneurs influencent les résultats de la comparaison. Du fait de l´étendue des résultats possibles de la gamme, compte-tenu des nombreuses relations entre les points d´extrémité comparés, vos scripts devront effectuer une analyse complexe des extrémités pour s´assurer que les comparaisons renvoient la séquence désirée. D´un autre côté, rechercher simplement l´unanimité des points d´extrémité est beaucoup plus facile. Il se peut que préfériez limiter vos comparaisons à la recherche des valeurs zéro qui sont renvoyées (ou toute autre valeur) pour une détermination plus binaire des comparaisons d´extrémités.

compareNode(nodeReference)

Méthode propre à Netscape qui renvoie un code, sous forme de nombre entier, indiquant l´emplacement relatif d´un autre noeud par rapport à la plage actuelle. Chaque objet Range Netscape comprend en anglais quatre constantes, qui peuvent être utilisées pour comparer des valeurs renvoyées par la méthode compareNode( ). Remarque: Les valeurs renvoyées sont transmises sous la forme d´un paramètre, du point de vue du noeud, non de la plage actuelle.

Les valeurs renvoyées et les constantes sont les suivantes:

Exemple:

compareNode(nodeReference, offset)

Méthode propre à Netscape qui renvoie un code, sous forme de nombre entier, indiquant l´emplacement relatif d´un autre noeud et le décalage dans ce noeud, par rapport à la plage actuelle. Remarque: Les valeurs renvoyées sont transmises sous la forme de paramètres, du point de vue du noeud (plus particulièrement, le point signifié par le décalage dans le noeud), non de la plage actuelle.

Les valeurs renvoyées sont les suivantes:

Exemple:

createContextualFragment(contentString)

Au départ, la méthode createContextualFragment( ) a été conçue comme un remplacement de la propriété innerHTML (car le DOM W3C ne prend que peu en charge les chaînes de contenu composées de balises). Cette méthode accepte n´importe quelle chaîne, y compris celles avec le contenu entre balises, comme paramètre, et renvoie un type de noeud DocumentFragment, prêt à être ajouté ou inséré dans l´arborescence de documents. L´adoption de la propriété innerHTML par le navigateur Mozilla rend cette méthode redondante, sauf qu´elle est plus en harmonie avec une structure axée sur les noeuds du DOM W3C.

Supprime le contenu de la plage de texte actuelle de l´arborescence de documents. Si la plage est un noeud élément (par exemple avec des extrémités établies par le biais de la méthode selectNode( )), l´invocation de deleteContents( ) sur la plage supprime le noeud de l´arborescence de documents et réduit la plage. L´objet Range reste en mémoire, mais sans contenu aucun. Si vous voulez capturer le contenu avant sa suppression, utilisez d´autres méthodes de l´objet Range (telles que cloneRange( ) et, lorsqu´elle fonctionne correctement, cloneContents( )).

Détruit l´objet Range actuel puisque l´invocation de la plupart des méthodes pour l´objet ou l´accès à ses propriétés renvoie une RangeException de type INVALID_STATE_ERR.

Renvoie un noeud DocumentFragment contenant le contenu de la plage actuelle, après la suppression du contenu de l´arborescence de documents. Ne fonctionne pas dans Netscape à partir de la version 6.2 sauf quand les extrémités de la plage sont définies par le biais de la méthode selectNodeContents( ).

insertNode(nodeReference)

Insère un noeud au début de la plage de texte actuelle. Particulièrement utile lorsque la plage est déjà réduite à un point d´insertion de texte. Le noeud à insérer peut être créé de zéro (par le biais de document.createElement( )) ou récupéré à un autre endroit de l´arborescence de documents, auquel cas il est supprimé de son ancien emplacement et inséré dans la plage actuelle. Si vous insérez un noeud de texte à côté d´un emplacement qui est déjà un noeud de texte existant, vous pouvez avoir deux noeuds de texte adjacents. Invoquez la méthode normalize( ) sur le parent afin de fusionner les deux noeuds.

intersectsNode(nodeReference)

Renvoie la valeur booléenne true si n´importe quelle partie de la plage actuelle se chevauche avec le noeud de texte ou élément qui est transmis en tant que paramètre. Si votre script détecte un chevauchement, il peut utiliser la méthode compareNode( ) pour obtenir plus de détails au sujet du chevauchement.

isPointInRange(nodeReference, offset)

Renvoie la valeur booléenne true si l´emplacement dénoté par les valeurs de paramètres (un noeud dans l´arborescence de documents et un emplacement de décalage au sein de ce noeud) est dans la plage actuelle.

selectNode(nodeReference) selectNodeContents(nodeReference)

Définit les points de début et de fin de la plage de façon à inclure un noeud ou juste le contenu du noeud. Malgré les noms des méthodes, aucun texte de corps dans le document affiché n´est en surbrillance.

La méthode choisie influence la façon dont les propriétés startContainer et endContainer de la plage sont remplies. Dans la séquence suivante, vous pouvez voir ce qui arrive à la plage et à ses propriétés lorsqu´un noeud élément et un noeud de texte sont des paramètres de ces méthodes. Le segment HTML initial est:

Si vous sélectionnez l´élément span (par le biais de la méthode rng.selectNode(document.getElementById("myspan"))), la plage est définie sur:

Les propriétés de l´objet Range rapportent des valeurs comme suit.

Si vous sélectionnez l´élément span par le biais de la méthode rng.selectNodeContents(document.getElementById("myspan"))), la plage est définie sur:

Les propriétés de l´objet Range rapportent des valeurs comme suit.

Si vous sélectionnez le noeud de texte dans l´élément span par le biais de la méthode rng.selectNode(document.getElementById("myspan").firstChild)), la plage est définie sur:

Bien que le noeud transmis en tant que paramètre soit différent (et d´un différent type de noeud), la nouvelle sélection de plage ressemble à la précédente. En fait, du fait de la structure de l´arborescence de noeuds, les propriétés de l´objet Range envoient des valeurs identiques comme suit.

Si vous sélectionnez le contenu du noeud de texte dans l´élément span par le biais de la méthode rng.selectNodeContents(document.getElementById("myspan"))), la plage est définie sur:

En d´autres termes, la plage est réduite à un point d´insertion au début du noeud de texte (peut-être un bogue dans Netscape 6) et le noeud de texte devient le conteneur, comme illustré dans l´énumération des propriétés suivante.

Les noeuds éléments sont généralement les valeurs de paramètres les plus pratiques à transmettre à n´importe laquelle des méthodes.

setEnd(nodeReference, offset) setStart(nodeReference, offset)

Etablissent les emplacements de l´arborescence de documents pour les points de début et de fin individuels d´un objet Range. Similaire à la méthode setEndPoint( ) de l´objet TextRange IE. Le mappage d´un emplacement est fondé sur une référence de noeud et une valeur de décalage par rapport au point de début et au type de ce noeud. Les valeurs de décalage comptent les noeuds enfants lorsque nodeReference est un noeud élément; elles comptent les caractères lorsque nodeReference est un noeud de texte. Pour définir une extrémité au bord d´un noeud, les méthodes associées (setEndAfter( ) et trois autres) sont plus pratiques.

setEndAfter(nodeReference) setEndBefore(nodeReference) setStartAfter(nodeReference) setStartBefore(nodeReference)

Etablissent les emplacements de l´arborescence de documents pour les points de début et de fin individuels d´un objet Range existant par rapport aux bords d´un noeud. Ces méthodes supposent que vous voulez placer les extrémités d´une plage juste avant ou après un noeud existant et que les autres types de décalage ne vous intéressent pas. Les extrémités d´une plage n´ont pas besoin d´être symétriques, ce qui vous permet de spécifier le point de début par rapport à un noeud et le point de fin par rapport à un noeud complètement différent plus loin dans le document.

surroundContents(parentNodeReference)

Entoure la plage actuelle d´un nouveau conteneur, généralement un nouveau noeud élément créé par le biais de la méthode document.createElement( ). Les points de fin de la plage actuelle doivent avoir le même conteneur parent avant l´application de cette méthode.

Renvoie une chaîne du contenu du corps de la plage. Aucun attribut ni balise n´accompagne la valeur renvoyée.