XML DOM - Range-objektet

Range-objektet repræsenterer en kontinuerlig område i dokumentet.

Range-objektet

Range-objektet repræsenterer en kontinuerlig områder i dokumentet, såsom det område, brugeren markerer ved at trække med musen i browservinduet.

Hvis en implementering understøtter Range-modulen, så Document-objektetdefinerer createRange() metodenfor at oprette nye Range-objekter.

Bemærk:IE har defineret en ikke-kompatibel Document.createRange() metode, der returnerer et objekt, der ligner Range-grænsefladen, men er ikke kompatibelt.

Range-grænsefladen definerer mange metoder til at specificere det valgte område i dokumentet, og derudover er der flere metoder, der kan bruges til at udføre klipning og indsætning i det valgte område.

Egenskaberne for Range-grænsefladen tilbyder metoder til at få fat i grænsepunkterne og afstanden for området. Dets metoder tilbyder metoder til at sætte områdets grænser. Bemærk, at områdets grænser kan sættes til Document eller DocumentFragment-objektmed noder. Når grænsepunkterne for området er defineret, kan man udføre klipning, kopi og indsætning ved hjælp af metoderne deleteContents(), extractContents(), cloneContents() og insertNode().

Når dokumentet ændres gennem indsat eller sletning, ændres alle Range-objekter, der repræsenterer en del af dokumentet (hvis nødvendigt), så deres grænsepunkter forbliver gyldige, og de (så tæt som muligt) repræsenterer samme dokumentindhold.

Termer: område, grænsepunkt og afstand

En område har to grænsepunkter, nemlig en startpunkt og et slutpunkt. Hver grænsepunkt defineres af en node og dens afstand. Denne node er typisk Element-nodeogDocument-nodeeller Text-nodeFor Element og Document-noder, refererer afstand til deres undernoder. En afstand på 0 betyder, at grænsepunktet ligger før den første undernode af noden. En afstand på 1 betyder, at grænsepunktet ligger efter den første undernode og før den anden undernode. Hvis grænsepunktet er en Text-node, refererer afstanden til positionen mellem to tegn i teksten.

Konstanter for Range-objektet

Disse konstanter specificerer, hvordan Range-objekters grænsepunkter skal sammenlignes.

De er parametrene for metoden compareBoundaryPoints(). how Gyldige værdier for parametrene:

Konstanter Beskrivelse
START_TO_START Sammenlign den angivne rækkes startpunkt med det nuværende Range-objekts startpunkt.
START_TO_END Sammenlign den angivne rækkes startpunkt med det nuværende Range-objekts slutpunkt.
END_TO_END Sammenlign den angivne rækkes slutpunkt med det nuværende Range-objekts slutpunkt.
END_TO_START Sammenlign den angivne rækkes slutpunkt med det nuværende Range-objekts startpunkt.

Egenskaber for Range-objektet

Bemærk:Alle egenskaber er skrivebeskyttede, og det er ikke muligt at ændre rækens start- og slutpunkter ved at sætte disse egenskaber. Dette skal gøres ved at kalde metoderne setEnd() og setStart().

Bemærk:Enhver læseoperation af disse egenskaber efter kald af metoden detach() vil kaste en fejl med kode INVALID_STATE_ERR. DOMException undtagelse.

Egenskaber Beskrivelse
collapsed Er sandt, hvis rækens start- og slutpunkter er på samme sted i dokumentet, dvs. rækken er tom eller foldet.
commonAncestorContainer Rækens start- og slutpunkter (dvs. deres ankerknuder), den dybeste indlejrede Dokument-knude.
endContainer Dokumentknuden, der indeholder rækens slutpunkt.
endOffset Slutpunktets position i endContainer.
startContainer Dokumentknuden, der indeholder rækens startpunkt.
startOffset Startpunktets position i startContainer.

Metoder for Range-objektet

Bemærk:Hvis metoden detach() for rækken er blevet kaldt, vil enhver yderligere kaldelse af metoder på Range-objektet kaste en fejl med kode INVALID_STATE_ERR. DOMException undtagelse.

Metode Beskrivelse
cloneContents() Returnerer et nyt DocumentFragment-objekt, der indeholder en kopi af den dokumentområde, som rækken repræsenterer.
cloneRange() Opret et nyt Range-objekt, der repræsenterer den samme dokumentområde som det nuværende Range-objekt.
collapse() Fold området sammen, så grænsepunkterne overlapper.
compareBoundaryPoints() Sammenlign grænsepunkterne for den angivne område og den aktuelle område, og returner -1, 0 eller 1 baseret på deres rækkefølge. Hvilken grænsepunkt der sammenlignes, bestemmes af den første parameter, dens værdi skal være en af de konstanter, der er defineret tidligere.
deleteContents() Slet den dokumentområde, som den aktuelle Range-objekt repræsenterer.
detach() Meddeler, at implementeringen ikke længere bruger den aktuelle område, og kan stoppe med at spore det. Hvis denne metode kaldes på området, vil den næste kaldede metode på området kaste en undtagelse med koden INVALID_STATE_ERR. DOMException undtagelse.
extractContents() Slet den dokumentområde, som den aktuelle område repræsenterer, og returner indholdet af området i form af en DocumentFragment-objekt. Denne metode sammen med kombinationen af cloneContents() og deleteContents() metoderne er meget ligner.
insertNode() Indsæt den angivne knude i begyndelsen af dokumentområdet.
selectNode() Sæt grænserne for området, så det inkluderer den angivne knude og alle dens efterkommere.
selectNodeContents() Sæt grænserne for området, så det inkluderer alle efterkommere af den angivne knude, men ikke inkluderer knuden selv.
setEnd() Sæt slutningen af området til den angivne knude og offset.
setEndAfter() Sæt slutningen af området til at være tæt ved den angivne knude efter.
setEndBefore() Sæt slutningen af området til at være tæt ved den angivne knude før.
setStart() Sæt begyndelsen af området til den angivne offset i den angivne knude.
setStartAfter() Sæt begyndelsen af området til at være tæt ved den angivne knude efter.
setStartBefore() Sæt begyndelsen af området til at være tæt ved den angivne knude før.
surroundContents() Indsæt den angivne knude i begyndelsen af dokumentområdet, og juster forældrenoderne i området, så de bliver efterkommere af den ny indsatte knude.
toString() Returner ren tekstindholdet af den dokumentområde, som denne område repræsenterer.