DOMParser: parseFromString() Methode

Syntax

parseFromString(input, mimeType)

Parameter

input

Eine TrustedHTML- oder String-Instanz, die das zu analysierende HTML definiert. Das Markup muss entweder ein HTML, XML, XHTML oder SVG Dokument enthalten.

mimeType

Ein String, der angibt, ob der XML-Parser oder der HTML-Parser verwendet wird, um den String zu analysieren.

Zulässige Werte sind:

• text/html
• text/xml
• application/xml
• application/xhtml+xml
• image/svg+xml

Rückgabewert

Ein Document mit contentType, das mit dem angegebenen mimeType übereinstimmt.

Ausnahmen

TypeError

Dies wird ausgelöst, wenn:

• mimeType ein Wert übergeben wird, der nicht einer der zulässigen Werte ist.
• input ein String-Wert übergeben wird, wenn Trusted Types durch eine CSP durchgesetzt und keine Standardrichtlinie definiert ist.

Beschreibung

Die parseFromString() Methode analysiert einen Input, der entweder HTML oder XML enthält, und gibt ein Document mit dem contentType zurück, das mit dem mimeType übereinstimmt. Dieses Document enthält ein vollständiges in-memory DOM, das vom Hauptdokument auf der zugehörigen Seite getrennt ist.

Wenn das mimeType text/html ist, wird der Input als HTML analysiert und <script>-Elemente werden als nicht ausführbar markiert, Ereignisse werden nicht ausgelöst und Ereignishandler werden nicht aufgerufen, um Inline-Skripte auszuführen. Obwohl das Dokument Ressourcen herunterladen kann, die in <iframe> und <img> Elementen angegeben sind, ist es im Wesentlichen inert. Dies ist nützlich, da Sie HTML-Eingaben analysieren können, die deklarative Shadow Roots enthalten und Operationen am Dokument durchführen können, ohne die sichtbare Seite zu beeinflussen. Beispielsweise können Sie dies verwenden, um den Eingabe-Baum zu bereinigen und Teile des Inputs bei Bedarf in das sichtbare DOM einzufügen.

Für die anderen zulässigen Werte (text/xml, application/xml, application/xhtml+xml, und image/svg+xml) wird der Input als XML analysiert. Dies ist nützlich, wenn Sie XML-Dateien importieren, ihre Struktur validieren und Daten extrahieren möchten. Wenn der Input kein gut geformtes XML darstellt, enthält das zurückgegebene Dokument einen <parsererror> Knoten, der die Art des Parsing-Fehlers beschreibt.

Unzulässige mimeType-Werte verursachen, dass ein TypeError ausgelöst wird.

Sicherheitsüberlegungen

Diese Methode analysiert ihren Input in ein separates in-memory DOM, deaktiviert alle <script>-Elemente und verhindert, dass Ereignishandler ausgeführt werden. Obwohl das zurückgegebene Dokument im Wesentlichen inert ist, können Ereignishandler und Skripte in seinem DOM ausgeführt werden, wenn sie in das sichtbare DOM eingefügt werden. Die Methode ist daher ein möglicher Vektor für Cross-Site-Scripting (XSS) Angriffe, bei denen potenziell unsicherer Input ohne Bereinigung zuerst in ein Document analysiert und dann in das sichtbare/aktive DOM eingefügt wird, wo Code ausgeführt werden kann.

Sie sollten dieses Risiko mindern, indem Sie immer TrustedHTML Objekte anstelle von Strings übergeben und Trusted Types durchsetzen mit der require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass der Input durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, den Input zu bereinigen, um potenziell gefährliches Markup (wie <script>-Elemente und Ereignishandlerattribute) zu entfernen, bevor es eingefügt wird.

Die Verwendung von TrustedHTML ermöglicht es, die Wirksamkeit der Bereinigung an nur wenigen Stellen zu überprüfen, anstatt über alle Ihre Injection-Einstiege verstreut. Sie sollten keinen Sanitizer an die Methode übergeben müssen, wenn Sie TrustedHTML verwenden.

Beachten Sie, dass Sie auch dann, wenn Sie den Input von Elementen und Attributen bereinigen, die Code ausführen können, vorsichtig sein müssen, wenn Sie Benutzer-Input verarbeiten. Beispielsweise könnte Ihre Seite Daten in einem XML-Dokument verwenden, um Dateien abzurufen, die sie dann ausführt.

Beispiele

Analyse eines Inputs unter Verwendung von Trusted Types

In diesem Beispiel werden wir einen potenziell schädlichen HTML-Input sicher analysieren und dann in den DOM der sichtbaren Seite einfügen.

Um das Risiko von XSS zu verringern, erstellen wir ein TrustedHTML-Objekt aus dem String, der das HTML enthält. Trusted Types werden noch nicht von allen Browsern unterstützt, also 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 erstellen wir eine TrustedTypePolicy, die eine createHTML() definiert, um einen Eingabe-String in TrustedHTML-Instanzen zu transformieren. Normalerweise verwenden Implementierungen von createHTML() eine Bibliothek wie DOMPurify, um den Input zu bereinigen, wie unten gezeigt wird:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

Dann verwenden wir dieses policy Objekt, um ein TrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen und es in ein Document zu analysieren. Beachten Sie, dass das resultierende Document ein vollständiges HTML-Dokument mit einem <html>, <head> und <body> Wurzelknoten darstellen wird, auch wenn der Input diese Elemente nicht enthält:

// The potentially malicious string
const untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";

// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

// Parse the TrustedHTML (which contains a trusted string)
const safeDocument = parser.parseFromString(trustedHTML, "text/html");

Das safeDocument enthält jetzt einen DOM, der von schädlichen Elementen gemäß unserer Policy bereinigt ist. Unten verwenden wir Element.replaceWith(), um den body des sichtbaren DOM mit dem body unseres Dokuments zu ersetzen: Skripte im neuen body werden ausgeführt, ebenso wie Code, wenn Ereignishandler ausgelöst werden.

document.body.replaceWith(safeDocument.body);

Parsing von XML, SVG und HTML

Der folgende Code zeigt, wie Sie die Methode verwenden, um jede der Inhaltsarten zu analysieren. Während Sie in echtem Code Trusted Types verwenden sollten, werden sie hier der Kürze halber weggelassen.

const parser = new DOMParser();

const xmlString = "<warning>Beware of the tiger</warning>";
const doc1 = parser.parseFromString(xmlString, "application/xml");
console.log(doc1.contentType); // "application/xml"

const svgString = '<circle cx="50" cy="50" r="50"/>';
const doc2 = parser.parseFromString(svgString, "image/svg+xml");
console.log(doc2.contentType); // "image/svg+xml"

const htmlString = "<strong>Beware of the leopard</strong>";
const doc3 = parser.parseFromString(htmlString, "text/html");
console.log(doc3.contentType); // "text/html"

console.log(doc1.documentElement.textContent);
// "Beware of the tiger"

console.log(doc2.firstChild.tagName);
// "circle"

console.log(doc3.body.firstChild.textContent);
// "Beware of the leopard"

Beachten Sie, dass die application/xml und image/svg+xml MIME-Typen oben funktional identisch sind — der letztere enthält keine spezifischen Parsing-Regeln für SVG.

Fehlerbehandlung

Wenn Sie den XML-Parser mit einem String verwenden, der kein wohlgeformtes XML darstellt, enthält das von parseFromString zurückgegebene XMLDocument einen <parsererror> Knoten, der die Art des Parsing-Fehlers beschreibt.

const parser = new DOMParser();

const xmlString = "<warning>Beware of the missing closing tag";
const doc = parser.parseFromString(xmlString, "application/xml");
const errorNode = doc.querySelector("parsererror");
if (errorNode) {
  // parsing failed
} else {
  // parsing succeeded
}

Zusätzlich kann der Parsing-Fehler in der JavaScript-Konsole des Browsers gemeldet werden.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• XMLSerializer
• JSON.parse() - Gegenstück für JSON Dokumente.