Element: insertAdjacentHTML() Methode

Syntax

insertAdjacentHTML(position, input)

Parameter

position

Ein String, der die Position relativ zum Element darstellt. Muss einer der folgenden Strings sein:

"beforebegin"

Vor dem Element. Nur gültig, wenn das Element im DOM-Baum ist und ein übergeordnetes Element hat.

"afterbegin"

Direkt innerhalb des Elements, vor dessen erstem Kind.

"beforeend"

Direkt innerhalb des Elements, nach dessen letztem Kind.

"afterend"

Nach dem Element. Nur gültig, wenn das Element im DOM-Baum ist und ein übergeordnetes Element hat.

input

Eine TrustedHTML Instanz oder ein String, der das HTML oder XML definiert, das geparst werden soll.

Rückgabewert

Keiner (undefined).

Ausnahmen

Diese Methode kann eine DOMException auslösen, eine der folgenden Typen:

NoModificationAllowedError DOMException

Wird ausgelöst, wenn position "beforebegin" oder "afterend" ist und das Element entweder kein übergeordnetes Element hat oder dessen übergeordnetes Element das Document Objekt ist.

SyntaxError DOMException

Wird ausgelöst, wenn:

• position nicht einer der vier aufgeführten Werte ist.
• Die Eingabe XML ist, das nicht wohlgeformt ist.

TypeError

Wird ausgelöst, wenn die Eigenschaft auf einen String gesetzt wird, wenn Trusted Types von einer CSP durchgesetzt werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die insertAdjacentHTML() Methode parst das Element, auf dem sie verwendet wird, nicht neu und beschädigt daher die vorhandenen Elemente innerhalb dieses Elements nicht. Dies vermeidet den zusätzlichen Schritt der Serialisierung und macht sie viel schneller als die direkte Manipulation von innerHTML.

Wo <p> das Element ist, können wir die möglichen Positionen für den eingefügten Inhalt "foo" wie folgt visualisieren:

<!-- beforebegin -->
<p>
  <!-- afterbegin -->
  foo
  <!-- beforeend -->
</p>
<!-- afterend -->

Die Methode enthält keine spezielle Behandlung für <template> Elemente. In den meisten Fällen sollten Entwickler insertAdjacentHTML() auf der content Eigenschaft des Templates verwenden, anstatt die untergeordneten Knoten eines Template-Elements direkt zu manipulieren.

Sicherheitsüberlegungen

Die Methode führt keine Reinigung durch, um XSS-unsichere Elemente wie <script> oder Event-Handler-Inhaltsattribute zu entfernen.

Wenn HTML auf einer Seite mit insertAdjacentHTML() eingefügt wird, sollten Sie TrustedHTML Objekte anstelle von Strings übergeben und vertrauenswürdige Typen durchsetzen über die require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu säubern, um potenziell gefährliches Markup zu entfernen, bevor es eingefügt wird.

Die Methode Element.insertAdjacentText() oder Node.textContent sollte verwendet werden, wenn Sie wissen, dass der vom Benutzer bereitgestellte Inhalt als reiner Text vorliegen sollte. Dies fügt die Eingabe als Rohtext und nicht als HTML ein.

Beispiele

Einfügen von HTML

Dieses Beispiel demonstriert die vier Einfügepositionen. Der gesamte eingefügte Text ist fett, während der innerhalb des Elements eingefügte Text zusätzlich als roter Monotyp (Code) formatiert ist.

HTML

<select id="position">
  <option>beforebegin</option>
  <option>afterbegin</option>
  <option>beforeend</option>
  <option>afterend</option>
</select>

<button id="insert">Insert HTML</button>
<button id="reset">Reset</button>

<p>
  Some text, with a <code id="subject">code-formatted element</code> inside it.
</p>

CSS

code {
  color: red;
}

JavaScript

Vertrauenswürdige Typen werden noch nicht von allen Browsern unterstützt, daher definieren wir zuerst das Trusted Types Tinyfill. Dies fungiert als transparenter Ersatz für die Trusted Types JavaScript API:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Als nächstes definieren wir eine Richtlinie namens some-content-policy zur Erstellung von TrustedHTML Objekten aus der Eingabe (wir sollten die some-content-policy auch über CSP durchsetzen). Der Code implementiert eine No-Op-Richtlinie, um dieses Beispiel ohne Drittanbieterabhängigkeit zum Laufen zu bringen. Ihr eigener Anwendungscode sollte eine Drittanbieter-Bibliothek wie die "DOMPurify" Bibliothek verwenden, um bereinigten Inhalt aus der untrusted Eingabe zurückzugeben.

const policy = trustedTypes.createPolicy("some-content-policy", {
  createHTML(input) {
    return input; // Do not do this in your own code!
    // Instead do something like:
    // return DOMPurify.sanitize(input);
  },
});

const unsafeText = "<strong>inserted text</strong>";
const trustedHTML = policy.createHTML(unsafeText);

Der verbleibende Code fügt das vertrauenswürdige HTML an der ausgewählten Position relativ zu dem Element mit der ID subject ein.

const insert = document.querySelector("#insert");
insert.addEventListener("click", () => {
  const subject = document.querySelector("#subject");
  const positionSelect = document.querySelector("#position");
  subject.insertAdjacentHTML(positionSelect.value, trustedHTML);
});

const reset = document.querySelector("#reset");
reset.addEventListener("click", () => {
  document.location.reload();
});

Ergebnis

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Element.insertAdjacentElement()
• Element.insertAdjacentText()
• XMLSerializer: Serialisieren eines DOM-Baums in einen XML-String
• Trusted Types API