Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Editar el DOM con Range

Corta, inserta y elimina contenido del DOM. Aprende a colocar los límites de un rango, a reducirlo a un punto y a distinguir qué copia `cloneRange()`.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

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 es un rango dinámico del DOM con un límite inicial y otro final. Cada límite es un par formado por un nodo contenedor y un desplazamiento. En un nodo de texto, este cuenta unidades de código UTF-16; en un elemento, cuenta los nodos hijos anteriores al límite, no solo los elementos hijos. Range pertenece al DOM, no a ECMAScript 2024; el entorno debe proporcionar un DOM.

extractContents() retira el contenido del rango y devuelve un DocumentFragment. Mueve los nodos completamente contenidos, copia las porciones de texto seleccionadas y clona, cuando hace falta, los elementos parcialmente contenidos para conservar la estructura. deleteContents() retira el contenido sin devolver un fragmento (undefined). Ambos métodos reducen el rango a un punto. Si ya está reducido, la extracción devuelve un fragmento vacío y la eliminación no hace nada.

insertNode(newNode) inserta en el límite inicial sin sustituir el contenido del rango. Si el límite está en un nodo de texto, lo divide en ese punto. Si se pasa un DocumentFragment, mueve sus hijos y lo deja vacío. La inserción puede ampliar un rango reducido a un punto. Una jerarquía de nodos no válida puede provocar HierarchyRequestError. La inserción no sanea el contenido: coloca el texto plano no fiable en un nodo de texto en vez de interpretarlo como HTML.

setStartAfter(referenceNode) coloca el inicio justo después del nodo de referencia, en su padre. Si el nodo no tiene padre, se produce InvalidNodeTypeError. Si el nuevo inicio queda después del final o en otro árbol, el final también se mueve a ese punto. collapse(true) reduce el rango a su inicio; collapse(false) y collapse() lo reducen a su final. Estos dos métodos e insertNode() devuelven undefined.

cloneRange() devuelve un Range independiente con los mismos límites iniciales, sin copiar nodos. Cambiar el límite de un rango no mueve directamente el del otro, pero ambos siguen siendo dinámicos: las mutaciones del DOM pueden ajustar los límites de ambos. El clon no es una instantánea del contenido.

Ejemplos

<!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>

Resultado

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

Guarda el ejemplo como archivo HTML, ábrelo en un navegador y consulta la consola de desarrollo. Reducir la copia a un punto deja `B` en el rango original. El nodo extraído se inserta entre `X` e `Y`, el fragmento queda vacío y después se elimina `Y`.

Lecciones relacionadas

  • JavaScript · Lección 33 · Intermedio · Versión: 3

Fuentes