Range: Methode createContextualFragment()
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Juli 2015 browserübergreifend verfügbar.
Warnung:
Diese Methode parst ihre Eingabe als HTML oder XML und schreibt das Ergebnis in ein DocumentFragment, das anschließend möglicherweise in das DOM eingefügt wird.
APIs wie diese werden als Injection Sinks bezeichnet. Wenn die Eingabe ursprünglich von einem Angreifer stammt, können sie als Angriffsvektor für Cross-Site-Scripting-Angriffe (XSS) dienen.
Sie können das Risiko verringern, indem Sie statt Strings TrustedHTML-Objekte übergeben und Trusted Types mithilfe der CSP-Direktive erzwingen require-trusted-types-for.
Dadurch wird sichergestellt, dass die Eingabe eine Transformationsfunktion durchläuft, die potenziell gefährliches Markup bereinigen kann, etwa <script>-Elemente und Event-Handler-Attribute.
Die Methode Range.createContextualFragment() der Range-Schnittstelle gibt ein DocumentFragment zurück, das die geparste HTML- oder XML-Eingabe enthält.
Syntax
createContextualFragment(input)
Parameter
input-
Eine
TrustedHTML-Instanz oder ein String mit dem Text und den Tags, die in ein Dokumentfragment umgewandelt werden sollen.
Rückgabewert
Ein DocumentFragment-Objekt.
Ausnahmen
TypeError-
Wird ausgelöst, wenn als Wert ein String übergeben wird, obwohl Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.
Beschreibung
Die Methode Range.createContextualFragment() gibt ein DocumentFragment zurück. Dazu ruft sie den Algorithmus zum Parsen von HTML-Fragmenten oder XML-Fragmenten auf und verwendet den Anfang des Bereichs (das Elternelement des ausgewählten Knotens) als Kontextknoten.
Der Algorithmus zum Parsen von HTML-Fragmenten wird verwendet, wenn der Bereich zu einem Document gehört, dessen HTMLness-Bit gesetzt ist.
Falls der Kontextknoten bei HTML html wäre, wird der Algorithmus zum Parsen von Fragmenten aus historischen Gründen stattdessen mit body als Kontext aufgerufen.
Sicherheitshinweise
Die Methode bereinigt die Eingabe nicht um Elemente wie <script> oder Event-Handler-Content-Attribute, die für XSS-Angriffe genutzt werden können.
Wenn die Eingabe von einem Benutzer stammt und das zurückgegebene DocumentFragment anschließend in das DOM eingefügt wird, kann diese Methode als Angriffsvektor für Cross-Site-Scripting-Angriffe (XSS) dienen.
Der folgende Code würde beispielsweise einen vom Benutzer bereitgestellten, potenziell gefährlichen String 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);
Wenn Sie mit createContextualFragment() HTML in eine Seite einfügen, sollten Sie statt Strings TrustedHTML-Objekte übergeben und Trusted Types mithilfe der CSP-Direktive erzwingen require-trusted-types-for.
Dadurch wird sichergestellt, dass die Eingabe eine Transformationsfunktion durchläuft, die potenziell gefährliches Markup bereinigen kann, bevor es eingefügt wird.
Beispiele
createContextualFragment() mit TrustedHTML verwenden
Trusted Types werden noch nicht von allen Browsern unterstützt. Daher definieren wir zunächst den Trusted Types Tinyfill. Dieser 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 (wir sollten some-content-policy außerdem mithilfe einer CSP erzwingen).
Der Code implementiert eine Richtlinie, die keine Änderungen vornimmt, damit dieses Beispiel ohne Drittanbieter-Abhängigkeit funktioniert.
In Ihrem eigenen Anwendungscode sollten Sie eine Drittanbieter-Bibliothek wie „DOMPurify“ verwenden, um aus der nicht vertrauenswürdigen Eingabe bereinigte Inhalte 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);
Anschließend können wir mit der vertrauenswürdigen Version des ursprünglichen Textes ein DocumentFragment 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
| Spezifikation |
|---|
| HTML # dom-range-createcontextualfragment |