Element#
Element.insertaAdjacentElement()#
Metoda insertaAdjacentElement() dodaje przekazany węzeł elementowy (drugi argument) w określone miejsce względem danego elementu (pierwszy argument) i zwraca referencje do przekazanego węzła elementowego.
Opis działania#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var other = element.insertaAdjacentElement(where, other);gdzie poszczególne człony oznaczają:
- other - referencja do przekazanego węzła elementowego dodawanego w określone miejsce względem danego elementu.
- element - węzeł będący obiektem kontekstu.
- where - łańcuch znakowy reprezentujący pozycję dodawanego węzła elementowego 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).
- "
- other - referencja do przekazanego węzła elementowego dodawanego w określone miejsce względem danego elementu.
Algorytm wywołania metody insertaAdjacentElement(where, other) nie jest skomplikowany. Dla lepszego zrozumienia tematu prezentuję go w całości:
- Zwróć wynik wstawienia sąsiada z przekazaniem obiektu kontekstu, where i other. Zrzuć ponownie każdy wyjątek.
Warto podkreślić, że dla pozycji "beforebegin" lub "afterend" i dla elementów, które nie posiadają rodzica, metoda insertaAdjacentElement() zawsze zwróci wartość null (bez zgłoszenia jakiegokolwiek błędu), w przeciwieństwie do podobnie działającej metody Element.insertAdjacentHTML().
Analizując dokładnie wszystkie powiązane z metodą insertaAdjacentElement() algorytmy można zauważyć, że przekazany węzeł będący drugim argumentem nie może istnieć jednocześnie w kilku miejscach drzewa węzłów. Najpierw zostanie usunięty z drzewa węzłów, a następnie wstawiony w nowe miejsce drzewa węzłów (z ewentualnym skorygowaniem jego właściciela). Jeśli zależy nam na wstawieniu drugiego identycznego węzła należy go najpierw sklonować i dopiero dołączyć do konkretnego drzewa węzłów. Trzeba pamiętać, że kopia nigdy nie będzie zsynchronizowana z oryginałem (są to dwa osobne obiekty), każda zmiana oryginału nie będzie miała żadnego wpływu na wykonaną kopię.
Metoda insertAdjacentHTML() 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 insertAdjacentHTML() jest mało elastyczna (dodaje wyłącznie elementy), 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 insertElement(context){
var box = document.getElementById("box"); // referencja do kontenera
var input_val = context.value;
num += 1;
var new_span = document.createElement("span");
new_span.textContent = "Nowy element SPAN " + num + " (" + input_val + "). ";
box.insertAdjacentElement(input_val, new_span);
}
</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 element SPAN względem kontenera DIV.</p>
<input type="button" value="beforebegin" onclick="insertElement(this)">
<input type="button" value="afterbegin" onclick="insertElement(this)">
<input type="button" value="beforeend" onclick="insertElement(this)">
<input type="button" value="afterend" onclick="insertElement(this)">
</body>
</html>Na chwilę obecną jedynie przeglądarki Firefox i Chrome obsługują metodę insertAdjacentHTML() zgodnie ze wszystkimi wymaganiami specyfikacji DOM4. Pozostałe programy mogą zawierać drobne uchybienia.
Metoda insertAdjacentHTML() pojawia się dopiero w specyfikacji DOM4.
Składnia Web IDL#
interface Element : Node { Element? insertAdjacentElement(DOMString where, Element other); // historical }