Range | NN 6 IE s.o DOM 2
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.
Référence de modèle d'objet
    document.createRange( )
Propriétés spécifiques à l´objet
collapsed | commonAncestorContainer | endContainer
endOffset | startContainer | startOffset
Méthodes spécifiques à l´objet
cloneContents( ) | cloneRange( ) | collapse( )
compareBoundaryPoints( ) | compareNode( ) | comparePoint( )
createContextualFragment( ) | deleteContents( ) | detach( )
extractContents( ) | insertNode( ) | intersectsNode( )
isPointInRange( ) | selectNode( ) | selectNodeContents( )
setEnd( ) | setEndAfter( ) | setEndBefore( )
setStart( ) | setStartAfter( ) | setStartBefore( )
surroundContents( ) | toString() |
Propriétés de gestionnaire d´événements spécifiques à l´objet
Aucune.

collapsed | NN 6 IE s.o DOM 2
| Lecture seule
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.
Exemple
    if (rng.collapsed) {
        // act on collapsed text range
    }
Valeur
Valeur booléenne: true | false.
Par défaut
Aucune.

commonAncestorContainer | NN 6 IE s.o DOM 2
| Lecture seule
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( ).
Exemple
var containingElem = rng.commonAncestorContainer;
Valeur
Référence à un objet noeud d´élément (généralement un type de noeud élément).
Par défaut
Aucune.

endContainer | NN 6 IE s.o DOM 2
| Lecture seule
Renvoie une référence à un noeud d´arborescence de documents qui comprend le point de fin de la plage actuelle.
Exemple
var containingElemRight = rng.endContainer;
Valeur
Référence à un objet noeud.
Par défaut
Aucune.

endOffset | NN 6 IE s.o DOM 2
| Lecture seule
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: <p>One paragraph with |a <span>nested</span>| element inside.</p> Remarque: Le point de début est à l´intérieur d´un noeud de texte, alors que le point de fin se trouve juste à l´extérieur de la balise de fin de l´élément span. Les propriétés de l´objet Range rapportent des valeurs comme l´indique le tableau suivant.
Propriété | Valeur | Description
--- | --- | ---
commonAncestorContainer | [object HTMLParagraphElement] | L´élément p comprend les points de début et de fin.
startContainer | [object Text] | Le point de début se trouve dans un noeud de texte.
startOffset | 19 | Le point de début est au 20ème caractère (index de 19 en base zéro) à partir du début de son conteneur, le noeud de texte.
endContainer | [object HTMLParagraphElement] | Le point de fin est désigné à la fin de l´élément span, ce qui fait de l´élément p parent immédiat le conteneur du point de fin.
endOffset | 2 | Le point de fin est au 3ème (index de 2 en base zéro) noeud dans le contexte de son élément endContainer p (le premier noeud est un noeud de texte, le deuxième noeud est l´élément span; le point de fin est au début du troisième noeud de l´élément p).
Exemple
var rngEndOff = rng.endOffset;
Valeur
Nombre entier.
Par défaut
Aucune.

startContainer | NN 6 IE s.o DOM 2
| Lecture seule
Renvoie une référence à un noeud d´arborescence de documents qui comprend le point de début de la plage actuelle.
Exemple
var containingElemLeft = rng.startContainer;
Valeur
Référence à un objet noeud.
Par défaut
Aucune.

startOffset | NN 6 IE s.o DOM 2
| Lecture seule
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.
Exemple
var rngStartOff = rng.startOffset;
Valeur
Nombre entier.
Par défaut
Aucune.

cloneContents() | NN 7 IE s.o DOM 2
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.
Valeur renvoyée
Référence à un noeud d´un type de fragment de document.
Paramètres
Aucune.

cloneRange() | NN 6 IE s.o DOM 2
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.
Valeur renvoyée
Référence à un objet Range.
Paramètres
Aucune.

collapse() | NN 6 IE s.o DOM 2
    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.
Valeur renvoyée
Aucune.
Paramètres
toStartFlag Valeur booléenne qui 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.

compareBoundaryPoints() | NN 6 IE s.o DOM 2
    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.
Type de comparaison | Description
--- | ---
rng.START_TO_START | Comparaison du point de début de la plage actuelle avec le point de début de la plage source
rng.START_TO_END | Comparaison du point de début de la plage actuelle avec le point de fin de la plage source
rng.END_TO_END | Comparaison du point de fin de la plage actuelle avec le point de fin de la plage source
rng.END_TO_START | Comparaison du point de fin de la plage actuelle avec le point de début de la plage source
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.
Valeur renvoyée
Nombres entiers -1, 0 ou 1.
Paramètres
compareType Nombres entiers de 0 à 3 correspondant à des types de comparaisons. Les nombres entiers ne sont pas alignés avec la norme du DOM W3C dans Netscape 6 ou 7, mais les constantes en anglais (telles que rng.START_TO_START, dans le tableau ci-dessus) effectuent des comparaisons correctes. sourceRangeRef Référence à un second objet Range, précédemment défini, peut-être préservé par le biais de la méthode cloneRange( ).

compareNode() | NN 6 IE s.o. DOM s.o.
    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:
Constante | Valeur | Description
--- | --- | ---
rng.NODE_BEFORE | 0 | Le noeud entier se trouve avant la plage.
rng.NODE_AFTER | 1 | Le noeud entier se trouve après la plage.
rng.NODE_BEFORE_AND_AFTER | 2 | Le noeud commence avant la plage actuelle et finit après.
rng.NODE_INSIDE | 3 | Le noeud est entièrement compris à l´intérieur de la plage.
Exemple: if (rng.compareNode(document.getElementById("myElem")) == rng.NODE_INSIDE) { // process for myElem node being contained by the range }
Valeur renvoyée
Nombres entiers 0, 1, 2 ou 3.
Paramètres
nodeReference Référence à n´importe quel noeud dans l´arborescence de documents.

comparePoint() | NN 6 IE s.o. DOM s.o.
    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:
Valeur | Description
--- | ---
-1 | Le point se trouve avant le début de la plage.
0 | Le point se trouve dans la plage.
1 | Le point se trouve après la fin de la plage.
Exemple: if (rng.comparePoint(document.getElementById("myElem"), 2) == 0) { // process for offset of 2 within myElem node being contained by the range }
Valeur renvoyée
Nombres entiers -1, 0, 1.
Paramètres
nodeReference Référence à n´importe quel noeud dans l´arborescence de documents. offset Décalage, sous forme de nombre entier, comptant soit les noeuds imbriqués dans un élément, soit les caractères dans un noeud de texte.

createContextualFragment() | NN 6 IE s.o. DOM s.o.
    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.
Valeur renvoyée
Référence à un type de fragment de document d´un noeud hors de l´arborescence de documents. Ce noeud peut ensuite être appliqué à l´arborescence de documents.
Paramètres
contentString Contenu du document, sous forme de chaîne, balises et attributs inclus.

deleteContents() | NN 6 IE s.o DOM 2
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( )).
Valeur renvoyée
Aucune.
Paramètres
Aucune.

detach() | NN 6 IE s.o DOM 2
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.
Valeur renvoyée
Aucune.
Paramètres
Aucune.

extractContents() | NN 6 IE s.o DOM 2
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( ).
Valeur renvoyée
Référence à un noeud d´un type de fragment de document.
Paramètres
Aucune.

insertNode() | NN 6 IE s.o DOM 2
    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.
Valeur renvoyée
Aucune.
Paramètres
nodeReference Référence à n´importe quel noeud de fragment de document, d´élément ou de texte à insérer dans la plage.

intersectsNode() | NN 6 IE s.o. DOM s.o.
    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.
Valeur renvoyée
Valeur booléenne: true | false.
Paramètres
nodeReference Référence à n´importe quel texte ou élément dans l´arborescence de documents.

isPointInRange() | NN 6 IE s.o. DOM s.o.
    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.
Valeur renvoyée
Valeur booléenne: true | false.
Paramètres
nodeReference Référence à n´importe quel texte ou élément dans l´arborescence de documents. offset Décalage, sous forme de nombre entier, comptant soit les noeuds imbriqués dans un élément soit les caractères dans un noeud de texte.

selectNode(), selectNodeContents() | NN 6 IE s.o DOM 2
    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: <p>One paragraph with a <span id="myspan">nested</span> element inside.</p> 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: <p>One paragraph with a |<span id="myspan">nested</span>| element inside.</p> Les propriétés de l´objet Range rapportent des valeurs comme suit.
Propriété | Valeur | Description
--- | --- | ---
startContainer | [object HTMLParagraphElement] | Le point de début se trouve juste avant l´élément span.
startOffset | 1 | Le point de début est au 2ème noeud (index de 1 en base zéro) au sein de l´élément p.
endContainer | [object HTMLParagraphElement] | Le point de fin se trouve juste après l´élément span.
endOffset | 2 | Le point de début est au 3ème noeud (index de 2 en base zéro) dans le contexte de son élément endContainer.
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: <p>One paragraph with a <span id="myspan">|nested|</span> element inside.</p> Les propriétés de l´objet Range rapportent des valeurs comme suit.
Propriété | Valeur | Description
--- | --- | ---
startContainer | [object HTMLSpanElement] | Le point de début se trouve juste à l´intérieur de l´élément span.
startOffset | 0 | Le point de début est au 1er noeud (index de 0 en base zéro) au sein de l´élément p.
endContainer | [object HTMLSpanElement] | Le point de fin se trouve juste après le contenu de l´élément span.
endOffset | 1 | Le point de fin est à un emplacement où le 2ème noeud (index de 1 en base zéro), s´il y en a un, serait dans le contexte de son élément endContainer.
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: <p>One paragraph with a <span id="myspan">|nested|</span> element inside.</p> 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.
Propriété | Valeur | Description
--- | --- | ---
startContainer | [object HTMLSpanElement] | Le point de début se trouve juste à l´intérieur de l´élément span.
startOffset | 0 | Le point de début est au 1er noeud (index de 0 en base zéro) au sein de l´élément p.
endContainer | [object HTMLSpanElement] | Le point de fin se trouve juste après le contenu de l´élément span.
endOffset | 1 | Le point de fin est à un emplacement où le 2ème noeud (index de 1 en base zéro), s´il y en a un, serait dans le contexte de son élément endContainer.
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: <p>One paragraph with a <span id="myspan">||nested</span> element inside.</p> 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.
Propriété | Valeur | Description
--- | --- | ---
startContainer | [object Text] | Le point de début se trouve au début du noeud de texte.
startOffset | 0 | Le point de début est au 1er emplacement (index de 0 en base zéro) du noeud de texte.
endContainer | [object Text] | Le point de fin est réduit.
endOffset | 0 | Le point de fin est réduit.
Les noeuds éléments sont généralement les valeurs de paramètres les plus pratiques à transmettre à n´importe laquelle des méthodes.
Valeur renvoyée
Aucune.
Paramètres
nodeReference Référence à n´importe quel texte ou élément dans l´arborescence de documents.

setEnd(), setStart() | NN 6 IE s.o DOM 2
    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.
Valeur renvoyée
Aucune.
Paramètres
nodeReference Référence à n´importe quel noeud de texte ou élément dans l´arborescence de documents. offset Décalage, sous forme de nombre entier, comptant soit les noeuds imbriqués dans un élément soit les caractères dans un noeud de texte.

setEndAfter(), setEndBefore(), setStartAfter(), setStartBefore() | NN 6 IE s.o DOM 2
    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.
Valeur renvoyée
Aucune.
Paramètres
nodeReference Référence à n´importe quel noeud de texte ou élément dans l´arborescence de documents.

surroundContents() | NN 7 IE s.o DOM 2
    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.
Valeur renvoyée
Aucune.
Paramètres
parentNodeReference Référence à un noeud qui devient le nouveau parent conteneur pour la plage.

toString() | NN 6 IE s.o DOM 2
Renvoie une chaîne du contenu du corps de la plage. Aucun attribut ni balise n´accompagne la valeur renvoyée.
Valeur renvoyée
Chaîne.
Paramètres
Aucune.