CKTIS / JavaScript
Úpravy DOM pomocí Range
Vyjímejte, vkládejte a odstraňujte obsah DOM. Naučte se nastavit hranice rozsahu, zúžit ho na jediný bod a rozlišit, co kopíruje `cloneRange()`.
Verze: 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() → RangeRange je živý rozsah v DOM s počáteční a koncovou hranicí. Každou hranici tvoří uzel a posun v něm. V textovém uzlu posun počítá kódové jednotky UTF-16, v elementu předcházející podřízené uzly, nejen podřízené elementy. Range je součástí DOM, ne ECMAScriptu 2024; běhové prostředí musí DOM poskytovat.
extractContents() vyjme obsah rozsahu a vrátí DocumentFragment. Zcela zahrnuté uzly přesune, zahrnuté části textu zkopíruje a podle potřeby naklonuje částečně zahrnuté elementy, aby zachoval strukturu. deleteContents() odstraní obsah bez vrácení fragmentu (undefined). Obě metody zúží rozsah na jediný bod. Je-li už zúžený, vyjmutí vrátí prázdný fragment a odstranění nic neudělá.
insertNode(newNode) vloží uzel na počáteční hranici, aniž nahradí obsah rozsahu. Pokud je hranice uvnitř textového uzlu, rozdělí ho v daném místě. U DocumentFragment přesune jeho podřízené uzly a fragment zůstane prázdný. Vložení může rozsah zúžený na bod znovu rozšířit. Neplatná hierarchie může vyvolat HierarchyRequestError. Vložení obsah neočišťuje; nedůvěryhodný prostý text vložte jako textový uzel, nikoli jako HTML.
setStartAfter(referenceNode) nastaví začátek těsně za referenční uzel v jeho rodiči. Uzel bez rodiče vyvolá InvalidNodeTypeError. Pokud nový začátek leží za koncem nebo v jiném stromu, přesune se tam i konec. collapse(true) zúží rozsah na začátek, collapse(false) a collapse() na konec. Tyto dvě metody a insertNode() vracejí undefined.
cloneRange() vrátí samostatný Range se stejnými počátečními hranicemi, aniž zkopíruje uzly. Nastavení hranice jednoho rozsahu nepřemístí přímo druhý, oba však zůstávají živé: změny DOM mohou upravit hranice obou. Klon není snímek obsahu.
Příklady
<!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>Výsledek
before: B / true moved: AC / XBY / 0 final: XB / true
Uložte příklad jako soubor HTML, otevřete ho v prohlížeči a podívejte se na výstup v konzoli pro vývojáře. Zúžení kopie na bod ponechá `B` v původním rozsahu. Vyjmutý uzel se vloží mezi `X` a `Y`, fragment se vyprázdní a nakonec se odstraní `Y`.
Související lekce
- JavaScript · Lekce 33 · Středně pokročilá · Verze: 3
Zdroje
- Range - Web APIs | MDN
- Range: extractContents() method - Web APIs | MDN
- Range: insertNode() method - Web APIs | MDN
- Range: deleteContents() method - Web APIs | MDN
- Range: setStartAfter() method - Web APIs | MDN
- Range: collapse() method - Web APIs | MDN
- Range: cloneRange() method - Web APIs | MDN
- Range: setStart() method - Web APIs | MDN
- StaticRange - Web APIs | MDN
- DOMException - Web APIs | MDN
- Element: innerHTML property - Web APIs | MDN