Element: insertAdjacentHTML() Methode

Syntax

insertAdjacentHTML(position, input)

Parameter

position

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

"beforebegin"

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

"afterbegin"

Direkt innerhalb des Elements, vor seinem ersten Kind.

"beforeend"

Direkt innerhalb des Elements, nach seinem letzten Kind.

"afterend"

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

input

Eine TrustedHTML-Instanz oder Zeichenkette, die das zu analysierende HTML oder XML definiert.

Rckgabewert

Keiner (undefined).

Ausnahmen

Diese Methode kann eine DOMException der folgenden Typen auslsen:

NoModificationAllowedError DOMException

Wird ausgelst, 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 ausgelst, wenn:

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

TypeError

Wird ausgelst, wenn die Eigenschaft auf eine Zeichenkette gesetzt wird, whrend Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die Methode insertAdjacentHTML() analysiert nicht erneut das Element, auf dem sie verwendet wird, und beschdigt daher nicht die bereits vorhandenen Elemente innerhalb dieses Elements. Dies vermeidet den zustzlichen Schritt der Serialisierung und macht sie viel schneller als die direkte Manipulation von innerHTML.

Wenn <p> das Element ist, knnen wir die mglichen Positionen fr den eingefgten Inhalt "foo" wie folgt visualisieren:

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

Die Methode enthlt keine spezielle Behandlung fr <template>-Elemente. In den meisten Fllen sollten Entwickler insertAdjacentHTML() auf der content-Eigenschaft der Vorlage verwenden, anstatt die Kindknoten eines Vorlagenelements direkt zu manipulieren.

Sicherheitserwgungen

Die Methode fhrt keine Sanitierung durch, um XSS-unsichere Elemente wie <script> oder Event-Handler-Attributinhalte zu entfernen.

Wenn Sie HTML auf eine Seite einfgen, sollten Sie TrustedHTML-Objekte anstelle von Zeichenketten verwenden und vertrauenswrdige Typen erzwingen mit der CSP-Direktive require-trusted-types-for. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Chance hat, die Eingabe zu sanitieren, um potenziell gefhrliches Markup zu entfernen, bevor es eingefgt 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 fgt die Eingabe als Rohtext ein, anstatt sie als HTML zu analysieren.

Beispiele

HTML einfgen

Dieses Beispiel demonstriert die vier Einfgepositionen. Alle eingefgten Texte sind fett, whrend Texte, die innerhalb des Elements eingefgt werden, zustzlich als roter Monotyp (Code) formatiert 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

Vertrauenswrdige Typen werden nicht auf allen Browsern untersttzt, daher definieren wir zuerst den trusted types tinyfill. Dies fungiert als transparenter Ersatz fr die Trusted Types JavaScript API:

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

Als nchstes definieren wir eine Richtlinie namens some-content-policy, um TrustedHTML-Objekte aus der Eingabe zu erstellen (wir sollten die some-content-policy auch mit CSP erzwingen). Der Code implementiert eine No-Op-Richtlinie, um es diesem Beispiel zu ermglichen, ohne eine Drittanbieter-Abhngigkeit zu funktionieren. Ihr eigener Anwendungscode sollte eine Drittanbieter-Bibliothek wie die "DOMPurify"-Bibliothek verwenden, um bereinigte Inhalte aus der nicht vertrauenswrdigen Eingabe zurckzugeben.

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 fgt das vertrauenswrdige HTML an der ausgewhlten 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-Kompatibilitt

Siehe auch

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