Element: insertAdjacentHTML() Methode

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 Elternelement hat.

"afterbegin"

Direkt im Element, vor seinem ersten Kind.

"beforeend"

Direkt im Element, nach seinem letzten Kind.

"afterend"

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

input

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

Keiner (undefined).

Diese Methode kann einen DOMException der folgenden Typen auslösen:

NoModificationAllowedError DOMException

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

SyntaxError DOMException

Wird ausgelöst, wenn:

• position nicht einer der vier aufgelisteten Werte ist.
• Die Eingabe ist XML, das nicht wohlgeformt ist.

TypeError

Wird ausgelöst, wenn die Eigenschaft auf eine Zeichenfolge gesetzt ist, wenn Trusted Types durch ein CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Die insertAdjacentHTML() Methode analysiert nicht das Element neu, auf dem sie angewendet wird, und beschädigt somit nicht die vorhandenen Elemente innerhalb dieses Elements. 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 Kindknoten eines Template-Elements direkt zu manipulieren.

Die Methode führt keine Bereinigung durch, um XSS-gefährliche Elemente wie <script> oder Ereignis-Handler-Inhaltsattribute zu entfernen.

Wenn HTML in eine Seite eingefügt wird, sollten Sie TrustedHTML Objekte anstelle von Zeichenfolgen verwenden und Trusted Types durchsetzen mit der require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Chance hat, die Eingabe zu bereinigen, um potenziell gefährliches Markup zu entfernen, bevor es injiziert wird.

Die Element.insertAdjacentText() Methode 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 analysieren.

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

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 in allen Browsern unterstützt, daher definieren wir zunächst die 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 die some-content-policy auch mithilfe von CSP durchsetzen). Der Code implementiert eine No-Op-Richtlinie, um dieses Beispiel ohne Drittanbieterabhängigkeit funktional zu machen. Ihr eigener Anwendungscode sollte eine Bibliothek wie die "DOMPurify" Bibliothek verwenden, um bereinigte Inhalte aus nicht vertrauenswürdiger 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 restliche Code fügt das vertrauenswürdige HTML an der gewä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

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