Element: Methode insertAdjacentHTML()

Syntax

insertAdjacentHTML(position, input)

Parameter

position

Eine Zeichenfolge, die die Position relativ zum Element angibt. Sie muss eine der folgenden Zeichenfolgen sein:

"beforebegin"

Vor dem Element. Nur gültig, wenn sich das Element im DOM-Baum befindet und ein Elternelement hat.

"afterbegin"

Innerhalb des Elements, vor seinem ersten Kindknoten.

"beforeend"

Innerhalb des Elements, nach seinem letzten Kindknoten.

"afterend"

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

input

Eine TrustedHTML-Instanz oder eine Zeichenfolge, die 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 den Wert "beforebegin" oder "afterend" hat und das Element entweder kein Elternelement hat oder sein Elternelement das Document-Objekt ist.

SyntaxError DOMException

Wird ausgelöst, wenn:

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

TypeError

Wird ausgelöst, wenn der Eigenschaft eine Zeichenfolge zugewiesen wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die Methode insertAdjacentHTML() parst das Element, auf das sie angewendet wird, nicht erneut und verändert daher die bereits darin enthaltenen Elemente nicht. Dadurch entfällt der zusätzliche Schritt der Serialisierung, was die Methode deutlich schneller macht als eine direkte Bearbeitung von innerHTML.

Wenn <p> das Element ist, lassen sich die möglichen Positionen für den einzufügenden Inhalt „foo“ wie folgt veranschaulichen:

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

Die Methode behandelt <template>-Elemente nicht gesondert. In den meisten Fällen sollten Sie insertAdjacentHTML() auf die content-Eigenschaft des Templates anwenden, anstatt die Kindknoten eines Template-Elements direkt zu bearbeiten.

Sicherheitshinweise

Die Methode bereinigt die Eingabe nicht, um für XSS unsichere Elemente wie <script> oder Event-Handler-Inhaltsattribute zu entfernen.

Wenn Sie mit insertAdjacentHTML() HTML in eine Seite einfügen, sollten Sie statt Zeichenfolgen TrustedHTML-Objekte übergeben und Trusted Types erzwingen, indem Sie die CSP-Direktive require-trusted-types-for verwenden. Dadurch wird die Eingabe durch eine Transformationsfunktion geleitet, die sie bereinigen und potenziell gefährliches Markup entfernen kann, bevor sie eingefügt wird.

Wenn Sie wissen, dass von Benutzern bereitgestellte Inhalte reiner Text sein sollen, sollten Sie die Methode Element.insertAdjacentText() oder Node.textContent verwenden. Dadurch wird die Eingabe als reiner Text eingefügt, statt als HTML geparst zu werden.

Beispiele

HTML einfügen

Dieses Beispiel zeigt die vier Einfügepositionen. Der gesamte eingefügte Text wird fett dargestellt; Text, der innerhalb des Elements eingefügt wird, erscheint zusätzlich rot und in einer nichtproportionalen Schriftart (wie Code).

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 zunächst den Trusted Types Tinyfill. Er dient 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 aus der Eingabe TrustedHTML-Objekte zu erstellen (die Richtlinie some-content-policy sollten wir außerdem mittels CSP erzwingen). Der Code implementiert eine No-op-Richtlinie, damit dieses Beispiel ohne Abhängigkeit von Drittanbietern funktioniert. In Ihrem Anwendungscode sollten Sie eine Drittanbieterbibliothek wie „DOMPurify“ verwenden, um aus nicht vertrauenswürdigen Eingaben bereinigte Inhalte zu erzeugen.

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 zum 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: Serialisiert einen DOM-Baum in eine XML-Zeichenfolge
• Trusted Types API