CKTIS / JavaScript
Range : conteneur commun, décalages et état réduit
Lisez les bornes d’une plage DOM, trouvez leur nœud commun le plus proche et vérifiez si les deux bornes désignent le même point.
Version : Current web platform; runtime support varies
Syntaxe
range.commonAncestorContainer
range.startOffset
range.endOffset
range.collapsedRange est une interface du DOM, pas une fonctionnalité d’ECMAScript 2024. La disponibilité de ces propriétés dépend de l’implémentation du DOM par l’environnement hôte, et non de l’édition d’ECMAScript. Ne supposez pas qu’elles existent dans un environnement sans DOM. Chaque borne est définie par un nœud et un décalage. Lisez startOffset avec startContainer, et endOffset avec endContainer.
Un décalage est une position à partir de zéro, pas l’indice du dernier caractère inclus. Dans un nœud CharacterData tel que Text, il compte les unités de code UTF-16 avant la borne, et non les caractères tels qu’on les perçoit. Dans un conteneur tel qu’un Element, il compte les nœuds enfants directs avant la borne, y compris les textes et les commentaires, comme dans childNodes. 0 précède la première unité ou le premier enfant ; la longueur totale se situe après le dernier.
commonAncestorContainer renvoie le nœud le plus profond qui, pour chaque conteneur de borne, est soit ce conteneur lui-même, soit l’un de ses ancêtres. Si les deux conteneurs sont le même nœud, c’est ce nœud qui est renvoyé, même s’il s’agit d’un Text. collapsed vaut true uniquement lorsque les deux bornes ont le même nœud et le même décalage. Des décalages égaux dans des nœuds différents ne suffisent pas.
Les quatre propriétés d’instance sont en lecture seule ; startOffset, endOffset et collapsed sont héritées d’AbstractRange. Déplacez les bornes avec setStart() et setEnd(). collapse(true) réduit la plage à son début ; collapse(false) ou collapse() la réduit à sa fin. Un Range est dynamique : les modifications du DOM peuvent ajuster ses bornes.
Exemples
<!doctype html>
<meta charset="utf-8">
<title>DOM Range boundary points</title>
<script>
{
const container = document.createElement('div');
const text = document.createTextNode('A😀B');
container.appendChild(text);
const range = document.createRange();
range.setStart(text, 3);
range.setEnd(container, 1);
const logRange = (expectedAncestor) => {
console.log(JSON.stringify([
range.commonAncestorContainer === expectedAncestor,
range.startOffset,
range.endOffset,
range.collapsed,
range.toString(),
]));
};
logRange(container);
range.collapse(true);
logRange(text);
}
</script>Résultat
[true,3,1,false,"B"] [true,3,3,true,""]
Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur et consultez le résultat dans la console de développement. Le décalage `3` dans le nœud texte se trouve juste après l’emoji, qui occupe deux unités de code UTF-16. Le décalage `1` dans l’élément se trouve après son unique enfant. La plage contient donc `B`. Après `collapse(true)`, les deux bornes sont au décalage `3` dans le nœud texte, qui devient le conteneur commun.
Leçons associées
- JavaScript · Leçon 33 · Intermédiaire · Version : 3