AbstractRange

Proprits d'instance

collapsed Lecture seule

Une valeur boolenne qui est true si la plage est rduite. Une plage rduite est une plage dont la position de dbut et la position de fin sont les mmes, ce qui donne une plage de longueur zro.

endContainer Lecture seule

L'objet Node dans lequel se trouve la fin de la plage, telle que dfinie par la proprit endOffset.

endOffset Lecture seule

Une valeur entire indiquant le dcalage, en caractres, depuis le dbut du contenu du nud jusqu'au dernier caractre de la plage reprsente par l'objet de plage. Cette valeur doit tre infrieure la longueur du nud endContainer.

startContainer Lecture seule

L'objet DOM Node dans lequel se trouve le dbut de la plage, telle que dfinie par la proprit startOffset.

startOffset Lecture seule

Une valeur entire indiquant le dcalage, en caractres, depuis le dbut du contenu du nud jusqu'au premier caractre du contenu rfrenc par l'objet de plage. Cette valeur doit tre infrieure la longueur du nud indiqu dans startContainer.

Mthodes d'instance

L'interface AbstractRange ne fournit aucune mthode.

Notes d'utilisation

Types de plage

Toutes les plages de contenu au sein d'un document sont dcrites l'aide d'instances d'interfaces bases sur AbstractRange. Il existe deux telles interfaces :

Range

L'interface Range existe depuis longtemps et n'a t redfinie que rcemment pour tre base sur AbstractRange, lorsque le besoin est apparu de dfinir d'autres formes de donnes de plage. Range fournit des mthodes permettant de modifier les points de terminaison de la plage, ainsi que des mthodes pour comparer des plages, dtecter des intersections entre des plages, et ainsi de suite.

StaticRange

L'interface StaticRange est une plage de base qui ne peut pas tre modifie une fois cre. Plus prcisment, mesure que l'arborescence des nuds mute et change, la plage ne change pas. C'est utile lorsque vous devez dfinir une plage qui n'est utilise qu'une seule fois, car cela vite l'impact sur les performances et les ressources de l'interface plus complexe Range.

Contenu des lments

Lorsque vous essayez d'accder au contenu d'un lment, gardez l'esprit que l'lment lui-mme est un nud, mais qu'il en va de mme pour tout texte qu'il contient. Pour dfinir un point de terminaison de plage l'intrieur du texte d'un lment, assurez-vous de trouver le nud de texte l'intrieur de l'lment :

const elemDebut = document.querySelector("p");
const elemFin = elemDebut.querySelector("span");
const plage = document.createRange();

plage.setStart(elemDebut, 0);
plage.setEnd(elemFin, elemFin.childNodes[0].length / 2);
const contenus = plage.cloneContents();

document.body.appendChild(contenus);

Cet exemple cre une nouvelle plage plage, et dfinit son point de dpart au troisime nud enfant du premier lment. Le point de terminaison est dfini pour tre au milieu du premier enfant de la porte (span en anglais), puis la plage est utilise pour copier le contenu de la plage.

Les plages et la hirarchie du DOM

Pour dfinir une plage de caractres dans un document de manire ce qu'elle puisse s'tendre sur zro ou plusieurs limites de nuds, et qu'elle soit aussi rsiliente que possible aux changements du DOM, vous ne pouvez pas dfinir le dcalage des premiers et derniers caractres dans le HTML. Il y a plusieurs bonnes raisons cela.

Tout d'abord, aprs le chargement de votre page, le navigateur ne pense pas en termes de HTML. Une fois charge, la page est un arbre d'objets DOM Node, vous devez donc dfinir les emplacements de dbut et de fin d'une plage en termes de nuds et de positions l'intrieur des nuds.

Deuximement, afin de prendre en charge la mutabilit de l'arbre DOM autant que possible, vous avez besoin d'un moyen de reprsenter les positions relatives aux nuds dans l'arbre, plutt que des positions globales dans l'ensemble du document. En dfinissant des points dans le document comme des dcalages l'intrieur d'un nud donn, ces positions restent cohrentes avec le contenu mme lorsque des nuds sont ajouts, supprims ou dplacs dans l'arbre DOM (dans une certaine mesure). Il existe des limitations assez videntes (par exemple, si un nud est dplac pour se trouver aprs le point final d'une plage, ou si le contenu d'un nud est fortement modifi), mais c'est bien mieux que rien.

Troisimement, utiliser des positions relatives aux nuds pour dfinir les positions de dbut et de fin est gnralement plus facile optimiser en termes de performance. Plutt que de devoir parcourir le DOM pour dterminer quoi correspond votre dcalage global, l'agent utilisateur (navigateur) peut aller directement au nud indiqu par la position de dpart et commencer partir de l, en avanant jusqu' atteindre le dcalage donn dans le nud de fin.

Pour illustrer cela, considrez le HTML ci-dessous :

<div class="conteneur">
  <div class="entete">
    <img src="..." alt="" class="logosite" />
    <h1>Le Site Ultime</h1>
  </div>
  <article>
    <section class="entree" id="entree1">
      <h2>Section 1&nbsp;: Une chose intressante</h2>
      <p>
        Une <em>trs</em> chose intressante s'est produite en chemin vers le
        forum
      </p>
      <aside class="apropos">
        <h2> propos</h2>
        <p>Une chose intressante  partager avec vous</p>
      </aside>
    </section>
  </article>
  <pre id="journal"></pre>
</div>

Aprs avoir charg le HTML et construit la reprsentation DOM du document, l'arbre DOM rsultant ressemble ceci :

[Diagramme du DOM pour une page web simple]

Dans ce diagramme, les nuds reprsentant les lments HTML sont affichs en vert. Chaque ligne en dessous montre le niveau de profondeur suivant dans l'arbre DOM. Les nuds bleus sont des nuds de texte, contenant le texte qui s'affiche l'cran. Le contenu de chaque lment est li en dessous dans l'arbre, pouvant potentiellement gnrer une srie de branches en dessous mesure que les lments incluent d'autres lments et nuds de texte.

Si vous souhaitez crer une plage qui inclut le contenu de l'lment HTML <p> dont le contenu est "Une <em>trs</em> chose intressante s'est produite en chemin vers le forum", vous pouvez le faire comme ceci :

const pRange = document.createRange();
pRange.selectNodeContents(document.querySelector("#entree1 p"));

Comme nous souhaitons slectionner l'intgralit du contenu de l'lment <p>, y compris ses descendants, cela fonctionne parfaitement.

Si nous souhaitons plutt copier le texte  Une chose intressante  depuis le titre de la <section> (un lment HTML <h2>) jusqu' la fin des lettres  trs  dans l'lment <em> l'intrieur du paragraphe ci-dessous, le code suivant fonctionne :

const plage = document.createRange();
const noeudDebut = document.querySelector("section h2").childNodes[0];
plage.setStart(noeudDebut, 11);

const noeudFin = document.querySelector("#entry1 p em").childNodes[0];
plage.setEnd(noeudFin, 2);

const fragment = plage.cloneContents();

C'est l qu'un problme intressant se pose nous rcuprons du contenu provenant de plusieurs nuds situs diffrents niveaux de la hirarchie DOM, puis seulement une partie de l'un d'entre eux. quoi doit ressembler le rsultat ?

Il se trouve que la spcification DOM traite heureusement ce problme exact. Par exemple, dans ce cas, nous appelons cloneContents() sur la plage pour crer un nouvel objet DocumentFragment fournissant un sous-arbre DOM qui reproduit le contenu de la plage dfinie. Pour ce faire, cloneContents() construit tous les nuds ncessaires pour prserver la structure de la plage indique, mais pas plus que ncessaire.

Dans cet exemple, le dbut de la plage dfinie se trouve dans le nud de texte sous le titre de la section, ce qui signifie que le nouveau DocumentFragment doit contenir un <h2> et, en dessous, un nud de texte.

La fin de la plage se trouve sous l'lment <p>, donc c'est ncessaire dans le nouveau fragment. Il en est de mme pour le nud de texte contenant le mot  A , puisque c'est inclus dans la plage. Enfin, un <em> et un nud de texte en dessous sont ajouts sous le <p> galement.

Le contenu des nuds de texte est ensuite dtermin par les dcalages dans ces nuds de texte donns lors de l'appel setStart() et setEnd(). tant donn le dcalage de 11 dans le texte du titre, ce nud contient  Une chose intressante . De mme, le dernier nud de texte contient  trs , tant donn la demande pour les deux premiers caractres du nud de fin.

Le fragment de document rsultant ressemble ceci :

[Un DocumentFragment reprsentant le contenu clon]

Notez surtout que le contenu de ce fragment se trouve entirement sous le parent commun des nuds les plus levs qu'il contient. Le parent <section> n'est pas ncessaire pour reproduire le contenu clon, il n'est donc pas inclus.

Exemples

Considrons ce fragment HTML simple.

<p><strong>Ceci</strong> est un paragraphe.</p>

Imaginons utiliser un Range pour extraire le mot  paragraphe  de ceci. Le code pour le faire ressemble ce qui suit :

const noeudPara = document.querySelector("p");
const noeudTextePara = noeudPara.childNodes[1];

const plage = document.createRange();
plage.setStart(noeudTextePara, 8);
plage.setEnd(noeudTextePara, noeudTextePara.length - 1);

const fragment = plage.cloneContents();
document.body.appendChild(fragment);

Tout d'abord, nous obtenons des rfrences au nud de paragraphe lui-mme ainsi qu'au deuxime nud enfant l'intrieur du paragraphe. Le premier enfant est l'lment HTML <strong>. Le deuxime enfant est le nud de texte   est un paragraphe. .

Avec la rfrence au nud de texte en main, nous crons un nouvel objet Range en appelant createRange() sur le Document lui-mme. Nous dfinissons la position de dpart de la plage au sixime caractre de la chane de caractres du nud de texte, et la position de fin la longueur de la chane de caractres du nud de texte moins un. Cela dfinit la plage pour englober le mot  paragraphe .

Nous terminons ensuite en appelant cloneContents() sur la Range pour crer un nouvel objet DocumentFragment qui contient la portion du document englobe par la plage. Aprs cela, nous utilisons appendChild() pour ajouter ce fragment la fin du corps du document, tel qu'obtenu partir de document.body.

Le rsultat ressemble ceci :

Spcifications

Compatibilit des navigateurs