CKTIS / JavaScript
Range — une plage vivante dans l’arbre DOM
Range décrit un fragment du DOM délimité par deux frontières. Il permet d’extraire, de supprimer et d’insérer du contenu, tandis que ses frontières réagissent automatiquement aux changements de l’arbre.
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
const range = document.createRange();
range.setStart(node, startOffset);
range.setEnd(node, endOffset);
range.extractContents();
range.insertNode(node);Range est une plage vivante définie par deux paires nœud-décalage. Créez-la avec document.createRange() ou new Range(). C’est une API Web de la norme DOM, et non une fonctionnalité d’une édition particulière d’ECMAScript ; la présence de Node 24 dans un dépôt ne prouve pas qu’elle est disponible. L’exemple nécessite un DOM de navigateur.
Range.startOffset et Range.endOffset comptent les unités de code UTF-16 dans CharacterData, mais les nœuds enfants, et non les caractères, dans les éléments. Range.commonAncestorContainer renvoie le nœud commun le plus profond qui contient les deux frontières ; il peut s’agir du nœud texte lui-même. Range.collapsed signifie que les frontières sont identiques, et pas simplement que le texte est vide.
Range.extractContents() supprime le contenu et renvoie un DocumentFragment : les nœuds entièrement contenus sont déplacés, tandis que les structures partiellement contenues sont copiées selon les besoins. Range.deleteContents() supprime le contenu sans renvoyer de fragment. Les deux opérations réduisent la plage à un point. Range.insertNode(node) insère au début au lieu de remplacer le contenu ; cette opération peut scinder un nœud texte et étendre une plage réduite.
Range.setStartAfter(node) place le début après le nœud dans son parent ; le nœud doit avoir un parent. Range.collapse(true) réduit la plage à son début, tandis que Range.collapse(false) ou Range.collapse() la réduit à sa fin. Range.cloneRange() crée une plage vivante distincte avec les mêmes frontières, et non une copie du DOM ni un instantané immuable : des mutations ultérieures peuvent affecter les deux plages.
Exemples
(() => {
const host = document.createElement('div');
host.textContent = 'ABCDE';
const range = document.createRange();
range.setStart(host.firstChild, 1);
range.setEnd(host.firstChild, 4);
console.log(range.commonAncestorContainer === host.firstChild);
console.log(range.startOffset, range.endOffset, range.collapsed);
const copy = range.cloneRange();
copy.collapse(true);
console.log(copy.collapsed, range.collapsed);
const fragment = range.extractContents();
console.log(fragment.textContent, host.textContent, range.collapsed);
const mark = document.createElement('mark');
mark.appendChild(fragment);
range.insertNode(mark);
range.setStartAfter(mark);
range.collapse(true);
console.log(host.textContent, range.startOffset, range.endOffset);
range.selectNode(mark);
range.deleteContents();
console.log(host.textContent, range.collapsed);
})();Résultat
true 1 4 false true false BCD AE true ABCDE 2 2 AE true
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.