XML DOM - Range-object

Een Range-object vertegenwoordigt een continue bereik in het document.

Range-object

Een Range-object vertegenwoordigt een continue bereik van het document, zoals het gebied dat de gebruiker selecteert door met de muisschuur in het browservenster te slepen.

Als een implementatie de Range-module ondersteunt, dan Document-objectdefinieert createRange() methodewaarbij het oproepen ervan een nieuwe Range-object kan creëren.

Opmerking:IE definieerde een niet-compatibele Document.createRange() methode, de objecten die deze methode retourneert zijn vergelijkbaar met het Range-interface, maar zijn niet compatibel.

Het Range-interface definieert een groot aantal methoden voor het definiëren van het geselecteerde gebied in een document, daarnaast zijn er enkele methoden die kunnen worden gebruikt voor knippen en plakkensoortige operaties in het geselecteerde gebied.

De properties van het Range-interface bieden methoden om de randknooppunten en offsets van het bereik te verkrijgen. Zijn methoden bieden de mogelijkheid om de randen van het bereik in te stellen. Let op, de randen van het bereik kunnen worden ingesteld op Document of DocumentFragment-objectvan de knopen. Zodra de randpunten van het bereik zijn gedefinieerd, kunnen de methoden deleteContents(), extractContents(), cloneContents() en insertNode() worden gebruikt om het knippen, kopiëren en plakken uit te voeren.

Wanneer de inhoud van het document wordt gewijzigd door het uitvoeren van een insertie- of verwijderingsoperatie, zullen alle Range-objects die een deel van het document vertegenwoordigen veranderen (indien nodig), zodat hun randpunten geldig blijven en ze (zo dicht mogelijk) dezelfde inhoud van het document weergeven.

Terminologie: bereik, randpunt en offset

Een bereik heeft twee randpunten, namelijk een beginpunt en een eindpunt. Elk randpunt wordt gespecificeerd door een knoop en de offset van die knoop. De knoop is meestal Element-knoopenDocument-knoopof Text-knoopVoor de Element-knoop en Document-knoop, verwijst de offset naar de onderliggende knopen van de knoop. Een offset van 0 betekent dat de randpunt zich bevindt voor de eerste onderliggende knoop van de knoop. Een offset van 1 betekent dat het randpunt zich bevindt na de eerste onderliggende knoop van de knoop, maar voor de tweede onderliggende knoop. Als het randknoop een Text-knoop is, verwijst de offset naar de positie tussen twee tekens in de tekst.

Constanten van het Range object

Deze constanten specificeren hoe de grenspunten van het Range object worden vergeleken.

Ze zijn de parameters van de compareBoundaryPoints() methode. how Geldige waarden voor de parameter:

Constanten Beschrijving
START_TO_START Vergelijk het beginpunt van de opgegeven range met het beginpunt van de huidige range.
START_TO_END Vergelijk het beginpunt van de opgegeven range met het eindpunt van de huidige range.
END_TO_END Vergelijk de eindpunt van de opgegeven range met het eindpunt van de huidige range.
END_TO_START Vergelijk de eindpunt van de opgegeven range met het beginpunt van de huidige range.

Eigenschappen van het Range object

Opmerking:Alle eigenschappen zijn alleen lezen, het is niet mogelijk deze eigenschappen te wijzigen om de begin- en eindpunten van de range te veranderen; dit moet worden gedaan door de setEnd() en setStart() methoden aan te roepen.

Opmerking:Elke leesoperatie op deze eigenschappen zal een INVALID_STATE_ERR fout gooien nadat de detach() methode is aangeroepen. DOMException-exception.

Eigenschappen Beschrijving
collapsed Als het begin- en eindpunt van de range op dezelfde locatie in het document liggen, is dit true, dat wil zeggen dat de range leeg is of is ingekollapsed.
commonAncestorContainer De gemeenschappelijke ouderknoop van het begin- en eindpunt van de range (dus hun vooroudernode), het diepst geneste Document knoop.
endContainer Document knoop die het eindpunt van de range bevat.
endOffset Eindpuntpositie in endContainer.
startContainer Document knoop die de startpunt van de range bevat.
startOffset Startpuntpositie in startContainer.

Methoden van het Range object

Opmerking:Als de detach() methode van de range is aangeroepen, zal elke volgende aanroep van een methode op het Range object een INVALID_STATE_ERR fout gooien. DOMException-exception.

Methode Beschrijving
cloneContents() Geef een nieuwe DocumentFragment object terug dat een kopie van de door de range vertegenwoordigde documentregio bevat.
cloneRange() Maak een nieuwe Range object aan die dezelfde documentregio vertegenwoordigt als de huidige Range object.
collapse() Vou het bereik samen zodat de grenspunten samenvallen.
compareBoundaryPoints() Vergelijk de grenspunten van het opgegeven bereik met de grenspunten van het huidige bereik en retourneer -1, 0 of 1 op basis van hun volgorde. Welk grenspunt wordt vergeleken, wordt bepaald door de eerste parameter, zijn waarde moet een van de eerder gedefinieerde constanten zijn.
deleteContents() Verwijder het documentgebied dat wordt weergegeven door het huidige Range-object.
detach() Meld dat de implementatie de huidige bereik niet langer gebruikt en kan stoppen met het volgen. Als deze methode van het bereik wordt aangeroepen, zal de volgende aanroep van elke methode van het bereik een INVALID_STATE_ERR-exception gooien. DOMException-exception.
extractContents() Verwijder het documentgebied dat wordt weergegeven door het huidige bereik en retourneer de inhoud van dat gebied in de vorm van een DocumentFragment-object. Deze methode is zeer vergelijkbaar met de combinatie van de deleteContents() en cloneContents() methoden.
insertNode() Plaats het opgegeven knooppunt in het beginpunt van het documentbereik.
selectNode() Stel de grenspunten van het bereik in zodat het het opgegeven knooppunt en al zijn afstammelingen bevat.
selectNodeContents() Stel de grenspunten van het bereik in zodat het de afstammelingen van het opgegeven knooppunt bevat, maar het opgegeven knooppunt zelf niet.
setEnd() Stel het eindpunt van het bereik in op het opgegeven knooppunt en de opgegeven offset.
setEndAfter() Stel het eindpunt van het bereik in op direct na het opgegeven knooppunt.
setEndBefore() Stel het eindpunt van het bereik in op direct naast het opgegeven knooppunt.
setStart() Stel het beginpunt van het bereik in op de opgegeven afstand binnen het opgegeven knooppunt.
setStartAfter() Stel het beginpunt van het bereik in op direct na het opgegeven knooppunt.
setStartBefore() Stel het beginpunt van het bereik in op direct naast het opgegeven knooppunt.
surroundContents() Plaats de opgegeven knooppunt in het beginpunt van het documentbereik en wijzig de ouderknooppunten van alle knooppunten in het bereik, zodat ze kinderen van het nieuw ingevoegde knooppunt worden.
toString() Geef de puur tekstinhoud van het documentgebied dat wordt weergegeven door deze bereik terug.