Element: insertAdjacentHTML() Methode

position

Ein String, der die Position relativ zum Element angibt. 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 eine DOMException von einem der folgenden Typen auslösen:

NoModificationAllowedError DOMException

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

SyntaxError DOMException

Wird ausgelöst, wenn:

• position nicht einer der vier aufgelisteten Werte ist.
• Die Eingabe unwohlgeformtes XML ist.

TypeError

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

Die insertAdjacentHTML() Methode parst das Element, auf dem sie angewendet wird, nicht erneut, sodass bestehende Elemente innerhalb dieses Elements nicht beschädigt werden. Dies vermeidet den zusätzlichen Schritt der Serialisierung und macht sie deutlich schneller als die direkte Manipulation mit innerHTML.

Wenn <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 beinhaltet keine spezielle Behandlung für <template> Elemente. In den meisten Fällen sollten Entwickler insertAdjacentHTML() auf der content Eigenschaft des Templates und nicht direkt an den Kindknoten eines Template-Elements verwenden.

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

Wenn Sie HTML in eine Seite mit insertAdjacentHTML() einfügen, sollten Sie TrustedHTML Objekte anstelle von Strings übergeben und Trusted Types erzwingen, indem Sie die require-trusted-types-for CSP-Direktive verwenden. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Chance hat, die Eingabe zu sanitisieren, bevor sie 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 parsen.

Dieses Beispiel demonstriert die vier Einfügepositionen. Alle eingefügten Texte sind fett, während im Element eingefügter 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

Trusted Types werden noch nicht in allen Browsern unterstützt, daher definieren wir zuerst den 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 Policy namens some-content-policy, um TrustedHTML Objekte aus der Eingabe zu erstellen (wir sollten auch die some-content-policy mit CSP erzwingen). Der Code implementiert eine No-Op-Policy, um zu ermöglichen, dass dieses Beispiel ohne Abhängigkeit von Drittanbietern funktioniert. Ihr eigener Anwendungscode sollte eine Drittanbieterbibliothek wie die "DOMPurify"-Bibliothek verwenden, um sanisierten Inhalt aus der nicht vertrauenswürdigen 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

• Element.insertAdjacentElement()
• Element.insertAdjacentText()
• XMLSerializer: Serialisiert einen DOM-Baum in einen XML-String
• Trusted Types API