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

CKTIS / JavaScript

Selection : compter les plages avec rangeCount et en ajouter avec addRange()

`rangeCount` indique combien de plages contient la sélection du document et `addRange()` ajoute une plage du DOM. Pour remplacer la sélection par une seule plage quel que soit le navigateur, videz-la d’abord.

Version : Current web platform; runtime support varies

Syntaxe

// Web platform: Selection API (not part of ECMAScript).
const selection = window.getSelection(); // Selection | null
if (selection !== null) {
  const count = selection.rangeCount;    // read-only number
  selection.addRange(range);            // takes a Range; returns undefined
}

Selection représente la sélection du document ou la position du curseur de texte. Récupérez cet objet avec window.getSelection() et vérifiez si le résultat vaut null. Cette API appartient à la plateforme web, pas à ECMAScript 2024. Pour le texte d’un textarea ou d’un type d’input compatible, utilisez plutôt la méthode setSelectionRange() de l’élément.

rangeCount est une propriété numérique en lecture seule. Elle compte des objets Range, pas des caractères. 0 signifie qu’il n’y a aucune plage. Même sans texte surligné, rangeCount === 1 est possible : une plage réduite à un seul point compte aussi. Vérifiez que rangeCount > 0 avant d’appeler getRangeAt(0), car un indice hors limites déclenche une exception.

addRange(range) prend un objet Range et renvoie undefined : cette valeur n’indique donc pas si la plage a été ajoutée. Créez une plage avec document.createRange() et définissez ses limites, par exemple avec range.selectNodeContents(node) sur un nœud rattaché au même document. Un Range est dynamique : des modifications du DOM peuvent déplacer ses limites.

La spécification prévoit au plus une plage par sélection, mais Firefox en prend plusieurs en charge. Un navigateur limité à une plage peut ignorer un nouvel appel à addRange() au lieu de remplacer la plage existante. Pour définir une seule nouvelle plage de façon fiable, appelez d’abord removeAllRanges(). Cela efface la sélection précédente, pas le contenu du document.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Selection API example</title>
</head>
<body>
  <script>
    (() => {
      const selection = window.getSelection();
      if (selection === null) throw new Error("No document selection available");

      const paragraph = document.createElement("p");
      paragraph.textContent = "CKTIS";
      document.body.append(paragraph);

      try {
        const range = document.createRange();
        range.selectNodeContents(paragraph);

        selection.removeAllRanges();
        console.log(selection.rangeCount);
        selection.addRange(range);
        console.log(selection.rangeCount);
        console.log(selection.toString());
      } finally {
        selection.removeAllRanges();
        paragraph.remove();
      }
    })();
  </script>
</body>
</html>

Résultat

0
1
CKTIS

Enregistrez l’exemple dans un fichier `.html`, ouvrez-le dans un onglet distinct du navigateur et consultez la console de développement. Le code affiche `0` après avoir vidé la sélection, puis `1` et `CKTIS` après avoir ajouté la plage. À la fin, il vide la sélection et supprime le paragraphe temporaire, sans restaurer la sélection précédente.

Leçons associées

  • JavaScript · Leçon 33 · Intermédiaire · Version : 3

Sources