XML DOM - obiekt Range

obiekt Range reprezentuje ciągły zakres w dokumencie.

obiekt Range

obiekt Range reprezentuje ciągły obszar dokumentu, który użytkownik wybiera za pomocą myszy w oknie przeglądarki.

Jeśli implementacja obsługuje moduł Range, to obiekt Documentdefiniuje metoda createRange()، wywołanie której tworzy nowy obiekt Range.

Uwaga:IE zdefiniował niekompatybilny metodę Document.createRange(), która zwraca obiekt podobny do interfejsu Range, ale niekompatybilny.

Interfejs Range definiuje wiele metod do określenia obszaru "wybranego" w dokumencie, a także kilka metod do wykonywania operacji wycinania i wklejania w wybranym obszarze.

Właściwości interfejsu Range dostarczają metod do uzyskiwania węzłów granicznych i przesunięć zakresu. Metody te dostarczają metod do ustawiania granic zakresu. Uwaga, granice zakresu mogą być ustawione na Document lub obiekt DocumentFragmentw którym znajdują się węzły. Po zdefiniowaniu punktów granicznych zakresu, można użyć metod deleteContents(), extractContents(), cloneContents() i insertNode() do wykonania operacji wycinania, kopiowania i wklejania.

Kiedy zmienia się dokument poprzez operacje wstawiania lub usuwania, wszystkie obiekty Range reprezentujące część dokumentu zmienią się (jeśli to konieczne), aby ich punkty graniczne pozostały ważne i aby (jak najbardziej zbliżenie) reprezentowały to samo zawartość dokumentu.

Terminologia: zakres, punkt graniczny i przesunięcie

Zakres ma dwa punkty graniczne, to znaczy punkt początkowy i punkt końcowy. Każdy punkt graniczny jest określony przez węzeł i przesunięcie tego węzła. Węzeł ten jest zazwyczaj węzeł Element,węzeł Documentlub węzeł TextDla węzłów Element i Document, przesunięcie oznacza podwęzły tego węzła. Przesunięcie wynoszące 0 oznacza, że punkt graniczny znajduje się przed pierwszym podwęzłem tego węzła. Przesunięcie wynoszące 1 oznacza, że punkt graniczny znajduje się za pierwszym podwęzłem, przed drugim podwęzłem. Jednakże, jeśli węzeł graniczny to węzeł Text, przesunięcie oznacza pozycję między dwoma znakami w tekście.

Stałe obiektu Range

Te stałe określają sposób porównywania punktów granicznych obiektów Range.

Są to stałe używane przez metodę compareBoundaryPoints(). how Dopuszczalne wartości parametrów:

Stałe Opis
START_TO_START Porównaj punkt początkowy określonego zakresu z punktem początkowym bieżącego zakresu.
START_TO_END Porównaj punkt początkowy określonego zakresu z punktem końcowym bieżącego zakresu.
END_TO_END Porównaj punkt końcowy określonego zakresu z punktem końcowym bieżącego zakresu.
END_TO_START Porównaj punkt końcowy określonego zakresu z punktem początkowym bieżącego zakresu.

Atrybuty obiektu Range

Uwaga:Wszystkie atrybuty są jedynie do odczytu, nie można zmienić początkowego i końcowego punktu zakresu poprzez ustawienie tych atrybutów, konieczne jest wywołanie metod setEnd() i setStart().

Uwaga:Każda odczytowa operacja tych atrybutów po wywołaniu metody detach() spowoduje rzucony błąd INVALID_STATE_ERR. DOMException wyjątek.

Atrybuty Opis
collapsed Jeśli punkt początkowy i końcowy zakresu znajdują się w tym samym miejscu w dokumencie, wynosi true, co oznacza, że zakres jest pusty lub złożony.
commonAncestorContainer Punkt początkowy i końcowy zakresu (czyli ich przodkowie), najgłębszy węzeł Document.
endContainer Węzeł Document zawierający punkt końcowy zakresu.
endOffset Pozycja punktu końcowego w endContainer.
startContainer Węzeł Document zawierający punkt początkowy zakresu.
startOffset Pozycja punktu początkowego w startContainer.

Metody obiektu Range

Uwaga:Jeśli wywołano metodę detach() zakresu, każde dalsze wywołanie metody obiektu Range spowoduje rzucony błąd INVALID_STATE_ERR. DOMException wyjątek.

Metoda Opis
cloneContents() Zwraca nowy obiekt DocumentFragment, który zawiera kopię obszaru dokumentu reprezentowanego przez ten zakres.
cloneRange() Utwórz nowy obiekt Range, który reprezentuje ten sam obszar dokumentu, co bieżący obiekt Range.
collapse() Złóż zakres, aby jego granice były współlokalizowane.
compareBoundaryPoints() Porównaj granice zakresów, zwracając -1, 0 lub 1 w zależności od ich kolejności. Porównywane granice są określone przez pierwszy parametr, jego wartość musi być jednym z zdefiniowanych wcześniej stałych.
deleteContents() Usuń obszar dokumentu reprezentowany przez bieżący obiekt Range.
detach() Powiadomienie o tym, że implementacja przestała używać bieżącego zakresu, można zatrzymać śledzenie. Jeśli został wywołany ten metodę zakresu, każda kolejna wywoływana metoda zakresu wywoła wyjątek o kodzie INVALID_STATE_ERR. DOMException wyjątek.
extractContents() Usuń obszar dokumentu reprezentowany przez bieżący zakres i zwróć zawartość tego obszaru w formie obiektu DocumentFragment. Ta metoda jest bardzo podobna do kombinacji metod deleteContents() i cloneContents().
insertNode() Wstaw określony węzeł na początku zakresu dokumentu.
selectNode() Ustaw granice zakresu tak, aby obejmował określony węzeł i jego wszystkie potomki.
selectNodeContents() Ustaw granice zakresu tak, aby obejmował potomków określonego węzła, ale nie węzeł sam w sobie.
setEnd() Ustaw koniec zakresu na określonym węźle i offset.
setEndAfter() Ustaw koniec zakresu na bezpośrednio po określonym węźle.
setEndBefore() Ustaw koniec zakresu na bezpośrednio przed określonym węzłem.
setStart() Ustaw początek zakresu na określonej odległości od określonego węzła.
setStartAfter() Ustaw początek zakresu na bezpośrednio po określonym węźle.
setStartBefore() Ustaw początek zakresu na bezpośrednio przed określonym węzłem.
surroundContents() Wstaw określony węzeł na początku zakresu dokumentu, a następnie przypisz wszystkie węzły w zakresie jako potomków nowo wstawionego węzła.
toString() Zwraca czysty tekst zawartości obszaru dokumentu reprezentowanego przez ten zakres.