Range#

Range.surroundContents()#

Metoda surroundContents() otacza zawartość danego zakresu przekazanym węzłem i ustawia dany zakres na przekazany węzeł.

Opis działania#

Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:

  1. L
  2. K
  3. T'
  4. T
  5. A
  6. O
  7. Z'
  8. Z
  9. #
range.surroundContents(newParent);

gdzie poszczególne człony oznaczają:

Algorytm wywołania metody surroundContents(newParent) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:

  1. Jeśli węzeł inny niż Text jest częściowo zawarty w obiekcie kontekstu, to zrzuć wyjątek "InvalidStateError".
  2. Jeśli newParent jest węzłem typu Document, DocumentType lub DocumentFragment, to zrzuć wyjątek "InvalidNodeTypeError".
  3. Niech fragment będzie rezultatem wyciągania zawartości w obiekcie kontekstu.
  4. Jeśli newParent ma dzieci, to zastąp wszystko wartością null w newParent.
  5. Wstaw newParent do obiektu kontekstu.
  6. Dodaj fragment do newParent.
  7. Wybierz newParent w obiekcie kontekstu.

Działanie metody surroundContents() to zlepek kilku algorytmów, z których każdy może wprowadzać jakieś obostrzenia. Najciekawsza sytuacja występuje dla węzłów częściowo zawartych w zakresie, dla których wywołanie metody zawsze zrzuci błąd (prócz węzłów tekstowych). Dzieje się tak dlatego, że próba otoczenia węzłów częściowo zawartych przekazanym węzłem wygenerowałaby nieprawidłową strukturę drzewa węzłów. W przypadku węzła tekstowego nastąpi jego odpowiedni podział na dwa osobne węzły tekstowe, i tylko jeden z nich otoczony zostanie przekazanym węzłem.

Prosty przykład:

  1. L
  2. K
  3. T'
  4. T
  5. A
  6. O
  7. Z'
  8. Z
  9. #
<script>

	var box = document.createElement("div");
	box.innerHTML = "Pierwszy węzeł tekstowy.";

	var parent = document.createElement("p");
	parent.textContent = "Początkowa zawartość nowego rodzica";

	document.write(box.childNodes.length); // 1
	document.write("<br>");
	document.write(box.textContent); // Pierwszy węzeł tekstowy.
	document.write("<br>");
	document.write(parent.childNodes.length); // 1
	document.write("<br>");
	document.write(parent.textContent); // Początkowa zawartość nowego rodzica.

	document.write("<br><br>");

	// Tworzymy nowy zakres
	var range = document.createRange();

	// Ustawiamy zakres na słowo 'węzeł' w kontenera DIV
	range.setStart(box.childNodes[0], 9);
	range.setEnd(box.childNodes[0], 14);

	document.write(range.startContainer); // [object Text]
	document.write("<br>");
	document.write(range.startOffset); // 9
	document.write("<br>");
	document.write(range.endContainer); // [object Text]
	document.write("<br>");
	document.write(range.endOffset); // 14
	document.write("<br>");
	document.write(range); // węzeł

	document.write("<br><br>");

	// Otaczamy zawartość zakresu węzłem 'parent' i rozciągamy zakres na ten węzeł
	range.surroundContents(parent);

	document.write(box.childNodes.length); // 3
	document.write("<br>");
	document.write(box.textContent); // Pierwszy węzeł tekstowy.
	document.write("<br>");
	document.write(parent.childNodes.length); // 1
	document.write("<br>");
	document.write(parent.textContent); // węzeł - początkowa zawartość została usunięta
	document.write("<br>");
	document.write(box.childNodes[1] == parent); // true - węzeł 'parent' wstawiony został do węzła 'box'

	document.write("<br><br>");

	document.write(range.startContainer); // [object HTMLDivElement], w IE [object Text]
	document.write("<br>");
	document.write(range.startOffset); // 1, w IE 9
	document.write("<br>");
	document.write(range.endContainer); // [object HTMLDivElement], w IE [object Text]
	document.write("<br>");
	document.write(range.endOffset); // 2, w IE 10
	document.write("<br>");
	document.write(range); // węzeł

</script>

Na chwilę obecną wszystkie aktualne przeglądarki obsługują metodę surroundContents() zgodnie z najnowszymi wymaganiami specyfikacji DOM4. Wyjątkiem będzie IE, które działa po swojemu, tzn. źle ustala punkty graniczne po zmianach, co widać w powyższym przykładzie.

Składnia Web IDL#

  1. L
  2. K
  3. T'
  4. T
  5. A
  6. O
  7. Z'
  8. Z
  9. #
interface Range {
	void surroundContents(Node newParent);
}

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

Range (H1) Range.surroundContents() (H2) Opis działania (H3) Składnia Web IDL (H3) Specyfikacje i inne materiały (H3)