Element#

Element.insertaAjacentText()#

Metoda insertaAjacentText() zamienia przekazany łańcuch znakowy (drugi argument) na węzeł tekstowy i dodaje go w określone miejsce względem danego elementu (pierwszy argument).

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. #
element.insertaAjacentText(where, data);

gdzie poszczególne człony oznaczają:

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

  1. Niech text będzie nowym węzeł typu Text z danymi tekstowymi wskazywanymi przez data.
  2. Wykonaj wstawienie sąsiada z przekazaniem obiektu kontekstu, where i text. Zrzuć ponownie każdy wyjątek.

Warto podkreślić, że metoda insertaAjacentText() niczego nie zwraca, co jest konsekwencją jej wczesnej implementacji jeszcze przed etapem standaryzacji. Także dla pozycji "beforebegin" lub "afterend" i dla elementów, które nie posiadają rodzica, metoda nie zgłasza jakiegokolwiek błędu, w przeciwieństwie do podobnie działającej metody Element.insertAdjacentHTML().

Metoda insertaAjacentText() była (i do tej pory jest) rzadko stosowana przez programistów. Została ustandaryzowana dopiero w specyfikacji DOM4 w oparciu o działanie Chrome, głównie ze względów historycznych, i w przypadku niektórych przeglądarek internetowych jej pierwsza implementacja pojawia się stosunkowo późno (DOM - Bug 19962, Mozilla - Bug 811259).

W ujęciu praktycznym metoda insertaAjacentText() jest mało elastyczna (dodaje wyłącznie węzły tekstowe), najczęściej jest zastępowana przez umiejętne wykorzystanie metody Node.insertBefore(), choć w dłuższej perspektywie ich miejsce zajmą uniwersalniejsze metody ChildNode.before(), ChildNode.after(), ParentNode.prepend() i ParentNode.append().

Prosty przykład:

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

<head>

	<script>

		var num = 0;

		function insertText(context){

			var box = document.getElementById("box"); // referencja do kontenera
			var input_val = context.value;

			num += 1;

			var str = "Nowy węzeł tekstowy " + num + " (" + input_val + "). ";

			box.insertAdjacentText(input_val, str);

		}

	</script>

</head>

<body>
	<div id="box" style="width:300px; background-color:#e0a0b0;">Kontener będący docelowym elementem.</div>

	<p>Kliknij konkretny przycisk by wstawić nowy węzeł tekstowy względem kontenera DIV.</p>
	<input type="button" value="beforebegin" onclick="insertText(this)">
	<input type="button" value="afterbegin" onclick="insertText(this)">
	<input type="button" value="beforeend" onclick="insertText(this)">
	<input type="button" value="afterend" onclick="insertText(this)">
</body>

</html>

Na chwilę obecną jedynie przeglądarki Firefox i Chrome obsługują metodę insertAdjacentText() zgodnie ze wszystkimi wymaganiami specyfikacji DOM4. Pozostałe programy mogą zawierać drobne uchybienia.

Metoda insertAdjacentText() pojawia się dopiero w specyfikacji DOM4.

Składnia Web IDL#

  1. L
  2. K
  3. T'
  4. T
  5. A
  6. O
  7. Z'
  8. Z
  9. #
interface Element : Node {
	void insertAdjacentText(DOMString where, DOMString data); // historical
}

Specyfikacje i inne materiały#

Pasek społecznościowy

SPIS TREŚCI AKTUALNEJ STRONY

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