Diewriteln()-Methode derDocument-Schnittstelle schreibt Text in einem oder mehrerenTrustedHTML- oder Zeichenfolgen-Parametern in einen durchdocument.open() geöffneten Dokumentenstrom, gefolgt von einem Zeilenumbruchszeichen.

Syntax

writeln(markup)writeln(markup, markup2)writeln(markup, markup2, /* …, */ markupN)

Parameter

markup, …,markupN

TrustedHTML- oder Zeichenfolgen-Objekte, die den Text enthalten, der in das Dokument geschrieben werden soll.

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidStateErrorDOMException

Die Methode wurde für ein XML-Dokument aufgerufen oder während der Parser derzeit einen benutzerdefinierten Elementkonstruktor ausführt.

TypeError

Eine Zeichenfolge wurde als einer der Parameter übergeben, wennvertrauenswürdige Typen erzwungen werden undkeine Standardrichtlinie definiert wurde zum Erstellen vonTrustedHTML-Objekten.

Beschreibung

Die Methode ist im Wesentlichen die gleiche wiedocument.write(), fügt jedoch eine neue Zeile hinzu (Informationen im verlinkten Thema gelten auch für diese Methode).Diese neue Zeile wird nur sichtbar sein, wenn sie in ein Element eingefügt wird, in dem Zeilenumbrüche angezeigt werden.Die zusätzlichen Informationen indocument.write() gelten auch für diese Methode.

Sicherheitsüberlegungen

Die Methode ist eine mögliche Angriffsfläche fürCross-Site-Scripting (XSS)-Angriffe, bei denen potenziell unsichere Zeichenfolgen, die von einem Benutzer bereitgestellt werden, ohne vorherige Bereinigung in das DOM injiziert werden.Obwohl die Methode möglicherweise<script>-Elemente von der Ausführung blockieren kann, wenn sie in einigen Browsern injiziert werden (sieheIntervening against document.write() für Chrome), ist sie anfällig für viele andere Möglichkeiten, HTML zu gestalten, um bösartiges JavaScript auszuführen.

Sie können diese Probleme mindern, indem Sie immerTrustedHTML-Objekte anstelle von Zeichenfolgen übergeben undvertrauenswürdige Typen durchsetzen, indem Sie dierequire-trusted-types-for CSP-Direktive verwenden.Dies gewährleistet, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zubereinigen, um potenziell gefährliche Markup-Elemente (wie<script>-Elemente und Event-Handler-Attribute) zu entfernen, bevor sie injiziert werden.

Beispiele

Schreiben von TrustedHTML

Dieses Beispiel verwendet dieTrusted Types API, um HTML-Zeichenfolgen zu bereinigen, bevor sie in ein Dokument geschrieben werden.Sie sollten immer vertrauenswürdige Typen verwenden, um unzuverlässige Zeichenfolgen an unsichere APIs zu übergeben.

Das Beispiel zeigt zunächst einen Standardtext und einen Knopf an.Wenn der Knopf geklickt wird, wird das aktuelle Dokument geöffnet, einige Zeichenfolgen von HTML werden inTrustedHTML-Instanzen umgewandelt und in das Dokument geschrieben, das dann geschlossen wird.Dadurch wird das Dokument im Beispielrahmen ersetzt, einschließlich des ursprünglichen HTML für den Knopf und des JavaScript, das die Aktualisierung vorgenommen hat!

HTML

<p>Some original document content.</p><button type="button">Replace document content</button>

JavaScript

Zunächst verwenden wir dieWindow.trustedTypes-Eigenschaft, um auf die globaleTrustedTypePolicyFactory zuzugreifen, und verwenden derencreatePolicy()-Methode, um eine Richtlinie namens"docPolicy" zu definieren.

Die neue Richtlinie definiert eine TransformationsfunktioncreateHTML() zum Erstellen derTrustedHTML-Objekte, die wir an diewriteln()-Methode übergeben werden.Diese Methode kann mit der Eingabezeichenfolge alles machen, was sie möchte: die Trusted Types API erfordert nur, dass Sie die Eingabe durch eine Richtlinien-Transformationsfunktion leiten, nicht, dass die Transformationsfunktion etwas Bestimmtes tut.

Sie würden die Methode verwenden, um die Eingabe durch Entfernen potenziell unsicherer Merkmale wie<script>-Tags oder Event-Handler-Attribute zubereinigen.Bereinigung ist schwer richtig umzusetzen, daher wird dieser Prozess typischerweise mit einer renommierten Drittanbieter-Bibliothek wieDOMPurify durchgeführt.

Hier implementieren wir einen rudimentären "Sanitizer", der<-Symbole in skriptöffnenden und -schließenden Tags durch das<-Zeichen ersetzt.Die eingefügten Zeichenfolgen in diesem Beispiel enthalten eigentlich keine schädlichen Elemente, daher ist dies rein zur Demonstration.

const policy = trustedTypes.createPolicy("docPolicy", {  createHTML(string) {    return string      .replace("<script", "&lt;script")      .replace("</script", "&lt;/script");  },});

Wir können dann dieTrustedTypePolicy.createHTML()-Methode auf der zurückgegebenen Richtlinie verwenden, umTrustedHTML-Objekte aus unseren ursprünglichen Eingabezeichenfolgen zu erstellen.Diese werden dann derwriteln()-Funktion übergeben, wenn der Benutzer den Knopf klickt.

const replace = document.querySelector("#replace");const oneInput = "<h1>Out with";const twoInput = "the old</h1>";const threeInput = "<pre>in with";const fourInput = "the new!</pre>";replace.addEventListener("click", () => {  document.open();  document.writeln(policy.createHTML(oneInput));  document.writeln(policy.createHTML(twoInput), policy.createHTML(threeInput));  document.writeln(policy.createHTML(fourInput));  document.close();});

Ergebnisse

Klicken Sie auf den Knopf.Beachten Sie, dass nach jedem Aufruf vonwriteln() eine neue Zeile hinzugefügt wird, diese aber nur innerhalb des<pre>-Elements sichtbar ist, da dessen Layout standardmäßig Leerzeichen beibehält.

Spezifikationen

Browser-Kompatibilität