Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Selection.getRangeAt — récupérer une plage de sélection

Selection.getRangeAt(0) renvoie l’objet Range associé à la sélection du document, et non une copie.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

selection.getRangeAt(index)

selection.getRangeAt(index) expose la plage de la sélection. Il s’agit d’une API Web du navigateur, et non d’une fonctionnalité ECMAScript ; Node 24 ne permet pas d’établir qu’elle est prise en charge.

Avant d’appeler la méthode avec l’index 0, vérifiez que selection !== null et selection.rangeCount > 0. La spécification impose de lever IndexSizeError si l’index est différent de 0, si la sélection est vide ou si l’une de ses extrémités se trouve hors de l’arbre du document. Les navigateurs n’appliquent pas toujours cette règle : Firefox peut exposer plusieurs plages de sélection, si bien qu’un index non nul peut fonctionner. Si une extrémité se trouve dans un arbre du Shadow DOM, ne supposez pas que le navigateur lèvera cette exception. Une sélection réduite à un curseur peut tout de même avoir une plage.

Le résultat est une référence : modifier la plage affecte la sélection tant qu’elles restent associées. Des appels répétés avec le même index renvoient le même objet, sauf si la plage a été remplacée ou supprimée. La spécification est un Working Draft, et non un tableau de compatibilité des navigateurs.

Exemples

(() => {
  const selection = window.getSelection();
  if (!selection || !document.body) {
    throw new Error("An active browser document is required.");
  }

  const element = document.createElement("p");
  element.textContent = "Hello world";
  document.body.append(element);

  try {
    selection.removeAllRanges();
    const range = document.createRange();
    range.setStart(element.firstChild, 0);
    range.setEnd(element.firstChild, 5);
    selection.addRange(range);

    if (selection.rangeCount === 0) {
      throw new Error("No selection range is available.");
    }
    const selectedRange = selection.getRangeAt(0);
    console.log(selectedRange.toString());
    console.log(selectedRange === selection.getRangeAt(0));
  } finally {
    selection.removeAllRanges();
    element.remove();
  }
})();

Résultat

Hello
true

Le code et le résultat ont été vérifiés dans un environnement Chromium isolé. L’exemple récupère l’unique plage à l’index `0` et vérifie qu’un second appel renvoie le même objet. Il ne teste ni les index non nuls ni les extrémités situées dans un arbre du Shadow DOM.

Sources