DOMParser: parseFromString() Methode

Syntax

parseFromString(input, mimeType)

Parameter

input

Eine Instanz von TrustedHTML oder ein String, der das zu parsende 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 parsen.

Erlaubte Werte sind:

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

Rückgabewert

Ein Document mit contentType, das dem angegebenen mimeType entspricht.

Ausnahmen

TypeError

Dies wird ausgelöst, wenn:

• mimeType einen Wert zugewiesen bekommt, der nicht einer der erlaubten Werte ist.
• input einen Stringwert zugewiesen bekommt, wenn Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die parseFromString() Methode parst eine Eingabe, die entweder HTML oder XML enthält, und gibt ein Document zurück, dessen contentType dem mimeType entspricht. Dieses Document enthält ein vollständiges In-Memory-DOM, das vom Hauptdokument auf der zugehörigen Seite getrennt ist.

Wenn der mimeType text/html ist, wird die Eingabe als HTML geparst und <script> Elemente werden als nicht ausführbar markiert, Ereignisse werden nicht ausgelöst und Event-Handler werden nicht aufgerufen, um Inline-Skripte auszuführen. Während das Dokument Ressourcen herunterladen kann, die in <iframe> und <img> Elementen spezifiziert sind, ist es im Wesentlichen inert. Dies ist nützlich, da Sie HTML-Eingaben parsen können, die deklarative Shadow-Roots enthalten, und Operationen auf dem Dokument durchführen können, ohne die sichtbare Seite zu beeinflussen. Zum Beispiel können Sie dies verwenden, um den Eingabebaum zu säubern und Teile der Eingabe bei Bedarf in das sichtbare DOM einzufügen.

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

Nicht erlaubte mimeType Werte führen zu einem TypeError.

Sicherheitsüberlegungen

Diese Methode parst ihre Eingabe in ein separates In-Memory-DOM, deaktiviert alle <script> Elemente und verhindert, dass Event-Handler ausgeführt werden. Während das zurückgegebene Dokument im Wesentlichen inert ist, können Event-Handler und Skripte in seinem DOM ausgeführt werden, wenn sie in das sichtbare DOM eingefügt werden. Die Methode ist daher ein potenzieller Vektor für Cross-Site-Scripting (XSS) Angriffe, bei denen potenziell unsichere Eingaben zuerst in ein Document gepaart werden, ohne dass sie bereinigt werden, und dann in das sichtbare/aktive DOM injiziert werden, wo Code ausführbar ist.

Sie sollten dieses Risiko mindern, indem Sie immer TrustedHTML Objekte anstelle von Strings übergeben und Trusted Types erzwingen mit der require-trusted-types-for CSP-Direktive verwenden. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu bereinigen, um potenziell gefährliches Markup (wie <script> Elemente und Event-Handler-Attribute) zu entfernen, bevor sie injiziert wird.

Die Verwendung von TrustedHTML ermöglicht es, zu prüfen und sicherzustellen, dass die Bereinigung des Codes an nur wenigen Stellen effektiv ist, anstatt verstreut über alle Ihre Injection Sinks. Sie sollten nicht ein Bereinigungswerkzeug an die Methode übergeben müssen, wenn Sie TrustedHTML verwenden.

Beachten Sie, dass, selbst wenn Sie die Eingabe von Elementen und Attributen bereinigen, die Code ausführen können, Sie dennoch vorsichtig sein müssen, wenn Sie Benutzereingaben entgegennehmen. Zum Beispiel könnte Ihre Seite Daten in einem XML-Dokument verwenden, um Dateien abzurufen, die sie dann ausführt.

Beispiele

Parsen einer Eingabe mit Trusted Types

In diesem Beispiel parsen wir sicher eine potenziell schädliche HTML-Eingabe und fügen sie dann in das DOM der sichtbaren Seite ein.

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

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 parsen. Beachten Sie, dass das resultierende Document ein vollständiges HTML-Dokument mit einem Wurzel-<html>, <head> und <body> darstellt, auch wenn die Eingabe 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 nun ein DOM, das von schädlichen Elementen gemäß unserer Richtlinie bereinigt worden ist. Unten verwenden wir Element.replaceWith(), um den body des sichtbaren DOMs durch den body unseres Dokuments zu ersetzen: Skripte im neuen Body werden ausgeführt, ebenso wie Code, wenn Event-Handler ausgelöst werden.

document.body.replaceWith(safeDocument.body);

Parsen von XML, SVG und HTML

Der folgende Code zeigt, wie Sie die Methode verwenden, um jeden der Inhaltstypen zu parsen. Während Sie in realem 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 schließt keine SVG-spezifischen Parseregeln ein.

Fehlerbehandlung

Wenn Sie den XML-Parser mit einem String verwenden, der kein gut geformtes XML darstellt, enthält das durch 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 an die JavaScript-Konsole des Browsers gemeldet werden.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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