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

CKTIS / JavaScript

Modifier le DOM avec Range

Coupez, insérez et supprimez du contenu dans le DOM. Apprenez à placer les bornes d’une plage, à la réduire à un point et à distinguer ce que copie `cloneRange()`.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

range.extractContents() → DocumentFragment
range.insertNode(newNode) → undefined
range.deleteContents() → undefined
range.setStartAfter(referenceNode) → undefined
range.collapse() → undefined
range.collapse(toStart) → undefined
range.cloneRange() → Range

Un Range est une plage dynamique du DOM avec une borne de début et une borne de fin. Chaque borne associe un nœud conteneur à un décalage. Dans un nœud texte, le décalage compte les unités de code UTF-16 ; dans un élément, il compte les nœuds enfants qui précèdent la borne, pas seulement les éléments enfants. Range relève du DOM, et non d’ECMAScript 2024 : l’environnement doit fournir un DOM.

extractContents() retire le contenu de la plage et renvoie un DocumentFragment. Les nœuds entièrement compris sont déplacés, les portions de texte sélectionnées sont copiées et les éléments partiellement compris sont clonés si nécessaire pour préserver la structure. deleteContents() retire le contenu sans renvoyer de fragment (undefined). Les deux méthodes réduisent la plage à un point. Si elle est déjà réduite, l’extraction renvoie un fragment vide et la suppression ne fait rien.

insertNode(newNode) insère à la borne de début sans remplacer le contenu de la plage. Si cette borne se trouve dans un nœud texte, celui-ci est scindé à cet endroit. Avec un DocumentFragment, ses enfants sont déplacés et le fragment se vide. L’insertion peut étendre une plage réduite à un point. Une hiérarchie interdite peut déclencher HierarchyRequestError. L’insertion n’assainit pas le contenu : placez le texte brut non fiable dans un nœud texte plutôt que de l’analyser comme du HTML.

setStartAfter(referenceNode) place le début juste après le nœud de référence, dans son parent. Sans parent, ce nœud provoque InvalidNodeTypeError. Si le nouveau début suit la fin ou se trouve dans un autre arbre, la fin est aussi déplacée à ce point. collapse(true) réduit la plage à son début ; collapse(false) et collapse() la réduisent à sa fin. Ces deux méthodes et insertNode() renvoient undefined.

cloneRange() renvoie un Range distinct dont les bornes sont initialement identiques, sans copier de nœuds. Déplacer la borne d’une plage ne déplace pas directement celle de l’autre, mais les deux plages restent dynamiques : les mutations du DOM peuvent ajuster leurs bornes. Le clone n’est pas un instantané du contenu.

Exemples

<!doctype html>
<meta charset="utf-8">
<title>Editing the DOM with Range</title>
<script>
(() => {
  const source = document.createElement('p');
  const target = document.createElement('p');
  const item = document.createElement('em');
  item.textContent = 'B';
  source.append('A', item, 'C');
  target.textContent = 'XY';

  const cut = document.createRange();
  cut.selectNode(item);
  const copy = cut.cloneRange();
  copy.collapse(true);
  console.log(`before: ${cut.toString()} / ${copy.collapsed}`);

  const fragment = cut.extractContents();
  const edit = document.createRange();
  edit.setStart(target.firstChild, 1);
  edit.collapse(true);
  edit.insertNode(fragment);
  console.log(`moved: ${source.textContent} / ${target.textContent} / ${fragment.childNodes.length}`);

  edit.setStartAfter(item);
  edit.collapse(true);
  edit.setEnd(target, target.childNodes.length);
  edit.deleteContents();
  console.log(`final: ${target.textContent} / ${edit.collapsed}`);
})();
</script>

Résultat

before: B / true
moved: AC / XBY / 0
final: XB / true

Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur et consultez la console de développement. Réduire la copie à un point laisse `B` dans la plage d’origine. Le nœud extrait est inséré entre `X` et `Y`, le fragment se vide, puis `Y` est supprimé.

Leçons associées

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

Sources