DOMParser: parseFromString() Methode

Syntax

parseFromString(input, mimeType)

Parameter

input

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

mimeType

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

Erlaubte Werte sind:

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

Rckgabewert

Ein Document mit einem contentType, das dem angegebenen mimeType entspricht.

Ausnahmen

TypeError

Dies wird ausgelst, wenn:

• mimeType einen Wert erhlt, der nicht einer der erlaubten Werte ist.
• input einen Stringwert erhlt, wenn vertrauenswrdige Typen durch eine CSP durchgesetzt werden und keine Standardrichtlinie definiert ist.

Beschreibung

Die parseFromString() Methode analysiert eine Eingabe, die entweder HTML oder XML enthlt, und gibt ein Document mit einem contentType, das dem mimeType entspricht, zurck. Dieses Document enthlt ein vollstndiges In-Memory-DOM, das vom Hauptdokument auf der zugehrigen Seite getrennt ist.

Wenn der mimeType text/html ist, wird die Eingabe als HTML analysiert und <script> Elemente sind als nicht ausfhrbar markiert, Ereignisse werden nicht ausgelst und Ereignishandler werden nicht aufgerufen, um Inline-Skripte auszufhren. Obwohl das Dokument Ressourcen herunterladen kann, die in <iframe> und <img> Elementen spezifiziert sind, ist es im Wesentlichen inert. Dies ist ntzlich, weil Sie HTML-Eingaben analysieren knnen, die declarative shadow roots enthalten, und Operationen am Dokument durchfhren knnen, ohne die sichtbare Seite zu beeinflussen. Zum Beispiel knnen Sie dies verwenden, um den Eingabebaum zu bereinigen und Teile der Eingabe bei Bedarf in das sichtbare DOM zu injizieren.

Fr die anderen erlaubten Werte (text/xml, application/xml, application/xhtml+xml und image/svg+xml) wird die Eingabe als XML analysiert. Dies ist ntzlich, wenn Sie XML-Dateien importieren, ihre Struktur validieren und Daten extrahieren mchten. Wenn die Eingabe kein wohlgeformtes XML darstellt, enthlt das zurckgegebene Dokument ein <parsererror> Element, das die Art des Analysefehlers beschreibt.

Nicht erlaubte mimeType Werte fhren zu einem TypeError.

Sicherheitsberlegungen

Diese Methode analysiert ihre Eingabe in ein separates In-Memory-DOM, wobei alle <script> Elemente deaktiviert und Ereignishandler deaktiviert werden. Obwohl das zurckgegebene Dokument im Wesentlichen inert ist, knnen Ereignishandler und Skripte in seinem DOM ausgefhrt werden, wenn sie in das sichtbare DOM eingefgt werden. Die Methode ist daher ein potenzieller Vektor fr Cross-Site-Scripting (XSS) Angriffe, bei denen potenziell unsichere Eingaben zuerst ohne Bereinigung in ein Document analysiert und dann in das sichtbare/aktive DOM injiziert werden, wo der Code ausgefhrt werden kann.

Sie sollten dieses Risiko mindern, indem Sie immer TrustedHTML Objekte anstelle von Strings bergeben und vertrauenswrdige Typen mit der require-trusted-types-for CSP-Direktive durchsetzen. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geht, die die Mglichkeit hat, die Eingabe zu bereinigen, um potenziell gefhrliches Markup (wie <script> Elemente und Ereignishandler-Attribute) zu entfernen, bevor es injiziert wird.

Die Verwendung von TrustedHTML ermglicht es, zu prfen und zu berprfen, dass der Bereinigungscode in nur wenigen Stellen wirksam ist, anstatt berall in Ihren Injektionen verstreut zu sein. Sie sollten keinen Bereiniger an die Methode bergeben mssen, wenn Sie TrustedHTML verwenden.

Beachten Sie, dass selbst wenn Sie die Eingabe von Elementen und Attributen bereinigen, die Code ausfhren knnen, Sie dennoch vorsichtig sein mssen, wenn Sie Benutzereingaben verwenden. Zum Beispiel knnte Ihre Seite Daten in einem XML-Dokument verwenden, um Dateien abzurufen, die dann ausgefhrt werden.

Beispiele

Parsen einer Eingabe mit vertrauenswrdigen Typen

In diesem Beispiel analysieren wir sicher eine potenziell schdliche HTML-Eingabe und injizieren sie dann in das DOM der sichtbaren Seite.

Um das Risiko von XSS zu verringern, erstellen wir ein TrustedHTML Objekt aus dem String, der das HTML enthlt. Vertrauenswrdige Typen werden noch nicht von 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 erstellen wir eine TrustedTypePolicy, die eine createHTML() definiert, um einen Eingabestring in TrustedHTML Instanzen zu verwandeln. Hufig 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 analysieren. Beachten Sie, dass das resultierende Document ein vollstndiges HTML-Dokument mit einem Root-<html>, <head> und <body> darstellt, obwohl die Eingabe diese Elemente nicht enthlt:

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

// 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 enthlt nun ein DOM, das gem unserer Richtlinie von schdlichen Elementen bereinigt ist. Unten verwenden wir Element.replaceWith(), um den body des sichtbaren DOMs mit dem body unseres Dokuments zu ersetzen: Skripte im neuen body werden ausgefhrt, ebenso wie der Code, wenn Ereignishandler ausgelst werden.

document.body.replaceWith(safeDocument.body);

XML, SVG und HTML parsen

Der untenstehende Code zeigt, wie Sie die Methode verwenden, um die jeweiligen Inhaltstypen zu parsen. Whrend Sie in echtem Code vertrauenswrdige Typen verwenden sollten, werden sie hier der Krze halber ausgelassen.

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 MIME-Typen application/xml und image/svg+xml oben funktional identisch sind der letztere beinhaltet keine SVG-spezifischen Parsingregeln.

Fehlerbehandlung

Wenn der XML-Parser mit einem String verwendet wird, der kein wohlgeformtes XML darstellt, enthlt das von parseFromString zurckgegebene XMLDocument ein <parsererror> Element, das 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
}

Zustzlich knnte der Parsing-Fehler in der JavaScript-Konsole des Browsers gemeldet werden.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• XMLSerializer
• JSON.parse() - Gegenstck fr JSON Dokumente.