Range: createContextualFragment() Methode
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since Juli 2015.
Warnung:
Diese Methode analysiert ihre Eingabe als HTML oder XML und schreibt das Ergebnis in ein DocumentFragment, das anschließend in das DOM injiziert werden könnte.
Solche APIs sind als Injection Sinks bekannt und potenziell eine Angriffsstelle für Cross-Site Scripting (XSS) Angriffe, wenn die Eingabe ursprünglich von einem Angreifer stammt.
Sie können das Risiko verringern, indem 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 Möglichkeit hat, die Eingabe zu sanitizen, um potenziell gefährliches Markup wie <script> Elemente und Event-Handler-Attribute zu entfernen.
Die Range.createContextualFragment() Methode der Range Schnittstelle gibt ein DocumentFragment zurück, das die analysierte Eingabe als HTML oder XML darstellt.
Syntax
createContextualFragment(input)
Parameter
input-
Eine
TrustedHTMLInstanz oder Zeichenfolge, die den Text und die Tags darstellt, die in ein Dokumentfragment umgewandelt werden sollen.
Rückgabewert
Ein DocumentFragment Objekt.
Ausnahmen
TypeError-
Wird ausgelöst, wenn die Eigenschaft auf eine Zeichenfolge gesetzt wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
Beschreibung
Die Range.createContextualFragment() Methode gibt ein DocumentFragment zurück, indem der HTML-Fragment-Parsing-Algorithmus oder der XML-Fragment-Parsing-Algorithmus mit dem Start des Bereichs (dem Elternelement des ausgewählten Knotens) als Kontextknoten aufgerufen wird.
Der HTML-Fragment-Parsing-Algorithmus wird verwendet, wenn der Bereich zu einem Document gehört, dessen HTMLbit gesetzt ist.
Im HTML-Fall, wenn der Kontextknoten html wäre, wird aus historischen Gründen der Fragment-Parsing-Algorithmus mit body als Kontext aufgerufen.
Sicherheitsüberlegungen
Die Methode führt keine Sanitizierung der Eingabe durch, um XSS-unsichere Elemente wie <script>, oder Event-Handler-Inhaltsattribute zu entfernen.
Wenn die Eingabe von einem Benutzer bereitgestellt wird, und das zurückgegebene DocumentFragment anschließend in das DOM eingefügt wird, kann diese Methode eine Angriffsstelle für Cross-Site Scripting (XSS) Angriffe werden.
Zum Beispiel würde der folgende Code die potenziell gefährliche benutzerbereitgestellte Zeichenfolge in das DOM einfügen.
const untrustedCode = "<script>alert('Potentially evil code!');</script>";
const range = document.createRange();
// Make the parent of the first div in the document become the context node
range.selectNode(document.getElementsByTagName("div").item(0));
const documentFragment = range.createContextualFragment(untrustedCode);
document.body.appendChild(documentFragment);
Beim Einfügen von HTML in eine Seite mit createContextualFragment() 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 Möglichkeit hat, die Eingabe zu sanitizen, um potenziell gefährliches Markup zu entfernen, bevor es eingefügt wird.
Beispiele
Verwendung von createContextualFragment() mit TrustedHTML
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 mit CSP durchsetzen).
Der Code implementiert eine No-Op-Richtlinie, um dieses Beispiel ohne Drittanbieterabhängigkeiten funktionsfähig zu machen.
Ihr eigener Anwendungscode sollte eine Drittanbieterbibliothek wie die "DOMPurify"-Bibliothek verwenden, um gereinigten Inhalt aus der unzuverlässigen 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 = "<script>alert('Potentially evil code!');</script>";
const trustedHTML = policy.createHTML(unsafeText);
Wir können dann ein DocumentFragment mithilfe unserer vertrauenswürdigen Version des Originaltexts erstellen und es sicher an das Dokument anhängen:
const range = document.createRange();
// Make the parent of the first div in the document become the context node
range.selectNode(document.getElementsByTagName("div").item(0));
const documentFragment = range.createContextualFragment(trustedHTML);
document.body.appendChild(documentFragment);
Spezifikationen
| Specification |
|---|
| HTML # dom-range-createcontextualfragment |