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:
element.insertaAjacentText(where, data);gdzie poszczególne człony oznaczają:
- element - węzeł będący obiektem kontekstu.
- where - łańcuch znakowy reprezentujący pozycję dodawanego węzła tekstowego względem danego elementu. Dostępne są tylko i wyłącznie następujące wartości (wielkość znaków nie ma znaczenia):
- "
beforebegin" - przed znacznikiem otwierającym dany element (czyli za jego bratem poprzedzającym, jeśli występuje). - "
afterbegin" - za znacznikiem otwierającym dany element (czyli przed pierwszym jego dzieckiem, jeśli występuje). - "
beforeend" - przed znacznikiem zamykającym dany element (czyli za ostatnim jego dzieckiem, jeśli występuje). - "
afterend" - za znacznikiem otwierającym dany element (czyli przed jego bratem następującym, jeśli występuje).
- "
- data - łańcuch znakowy automatycznie zamieniany na węzeł tekstowy i dodawany w określone miejsce względem danego elementu.
Algorytm wywołania metody insertaAjacentText(where, data) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Niech text będzie nowym węzeł typu
Textz danymi tekstowymi wskazywanymi przez data. - 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:
<!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#
interface Element : Node { void insertAdjacentText(DOMString where, DOMString data); // historical }