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 besitzt.

"afterbegin"

Direkt innerhalb des Elements, vor seinem ersten Kind.

"beforeend"

Direkt innerhalb des Elements, nach seinem letzten Kind.

"afterend"

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

input

Eine TrustedHTML Instanz oder ein String, der das zu parsende HTML oder XML definiert.

Rückgabewert

Keiner (undefined).

Ausnahmen

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

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 aufgelisteten Werte ist.
• Die Eingabe XML ist, das nicht wohlgeformt ist.

TypeError

Wird ausgelöst, wenn die Eigenschaft auf einen String gesetzt wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die Methode insertAdjacentHTML() parst das Element, auf dem sie verwendet wird, nicht erneut, und beeinflusst somit nicht die bestehenden Elemente innerhalb dieses Elements. Dies vermeidet den zusätzlichen Schritt der Serialisierung und macht es wesentlich 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. Entwickler sollten in den meisten Fällen insertAdjacentHTML() auf der content Eigenschaft des Templates verwenden, anstatt die Kindknoten eines Template-Elements direkt zu manipulieren.

Sicherheitsüberlegungen

Die Methode führt keine Sanitierung durch, um XSS-unsichere Elemente wie <script> oder Inhalte von Event-Handlern zu entfernen.

Beim Einfügen von HTML in eine Seite mit insertAdjacentHTML() sollten Sie TrustedHTML Objekte anstelle von Strings verwenden und Trusted Types erzwingen mithilfe der CSP-Direktive require-trusted-types-for. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu sanitizen, um potenziell gefährliche Markups zu entfernen, bevor sie eingefügt wird.

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

Beispiele

Einfügen von HTML

Dieses Beispiel demonstriert die vier Einfügepositionen. Alle eingefügten Texte sind fett, während Texte, die innerhalb des Elements eingefügt werden, zusätzlich als roter Monotyp (Code) gestylt sind.

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

Trusted Types 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, um TrustedHTML Objekte aus der Eingabe zu erstellen (wir sollten auch die some-content-policy mithilfe von CSP erzwingen). Der Code implementiert eine No-Op-Richtlinie, um zu ermöglichen, dass dieses Beispiel ohne eine Drittanbieter-Abhängigkeit funktioniert. Ihr eigener Anwendungscode sollte eine Drittanbieter-Bibliothek wie die "DOMPurify" Bibliothek verwenden, um bereinigte Inhalte aus unzuverlässiger 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: Ein DOM-Baum in eine XML-Zeichenfolge serialisieren
• Trusted Types API