Dokument: writeln()-Methode

Syntax

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

Parameter

markup, …, markupN

TrustedHTML oder String-Objekte, die den zu schreibenden Text in das Dokument enthalten.

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidStateError DOMException

Die Methode wurde auf einem XML-Dokument aufgerufen oder während der Parser gerade einen benutzerdefinierten Elemente-Konstruktor ausführt.

TypeError

Eine Zeichenfolge wurde als einer der Parameter übergeben, wenn Trusted Types erzwungen werden und keine Standardrichtlinie definiert wurde zum Erstellen von TrustedHTML-Objekten.

Beschreibung

Die Methode ist im Wesentlichen dieselbe wie document.write(), fügt jedoch einen Zeilenumbruch hinzu (Informationen im verlinkten Thema gelten auch für diese Methode). Dieser Zeilenumbruch ist nur sichtbar, wenn er innerhalb eines Elements eingefügt wird, bei dem Zeilenumbrüche angezeigt werden. Die zusätzlichen Informationen in document.write() gelten auch für diese Methode.

Sicherheitsüberlegungen

Die Methode ist eine mögliche Angriffsfläche für Cross-Site-Scripting (XSS)-Angriffe, bei denen potenziell unsichere Zeichenfolgen von einem Benutzer in das DOM eingefügt werden, ohne vorher bereinigt zu werden. Während die Methode möglicherweise <script>-Elemente blockiert, wenn sie in einigen Browsern eingefügt werden (siehe Intervening against document.write() für Chrome), ist sie anfällig für viele andere Möglichkeiten, wie Angreifer HTML gestalten können, um bösartigen JavaScript-Code auszuführen.

Sie können diese Probleme mindern, indem Sie immer TrustedHTML-Objekte anstelle von Zeichenfolgen übergeben und Trusted Types erzwingen mit der require-trusted-types-for-CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu bereinigen, um potenziell gefährlichen Markup (wie <script>-Elemente und Ereignishandlerattribute) zu entfernen, bevor sie eingefügt wird.

Beispiele

Schreiben von TrustedHTML

Dieses Beispiel verwendet die Trusted Types API, um HTML-Zeichenfolgen zu bereinigen, bevor sie in ein Dokument geschrieben werden. Sie sollten immer Trusted Types verwenden, wenn Sie nicht vertrauenswürdige Zeichenfolgen an unsichere APIs übergeben.

Das Beispiel zeigt zunächst einen Standardtext und einen Button an. Wenn der Button geklickt wird, wird das aktuelle Dokument geöffnet, einige HTML-Zeichenfolgen werden in TrustedHTML-Instanzen konvertiert und in das Dokument geschrieben, und das Dokument wird dann geschlossen. Dies ersetzt das Dokument im Beispielrahmen, einschließlich des ursprünglichen HTMLs für den Button und des JavaScript-Codes, der die Aktualisierung durchgeführt hat!

HTML

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

JavaScript

Zuerst verwenden wir die Window.trustedTypes-Eigenschaft, um auf die globale TrustedTypePolicyFactory zuzugreifen, und verwenden deren createPolicy()-Methode, um eine Richtlinie namens "docPolicy" zu definieren.

Die neue Richtlinie definiert eine Transformationsfunktion createHTML(), um die TrustedHTML-Objekte zu erstellen, die wir an die writeln()-Methode übergeben werden. Diese Methode kann beliebig mit der Eingabezeichenfolge verfahren: Die Trusted Types API erfordert nur, dass Sie die Eingabe durch eine Richtlinientransformationsfunktion leiten, nicht dass die Transformationsfunktion irgendetwas Bestimmtes tut.

Sie würden die Methode verwenden, um die Eingabe durch Entfernen potenziell unsicherer Funktionen wie <script>-Tags oder Ereignishandlerattribute zu bereinigen. Die Bereinigung ist schwer richtig zu machen, daher wird dieser Prozess typischerweise mit einer seriösen Drittanbieterbibliothek wie DOMPurify durchgeführt.

Hier implementieren wir einen rudimentären "Sanitizer", der <-Symbole in Skriptöffnungs- und - schließtags durch das <-Zeichen ersetzt. Die in diesem Beispiel eingefügten Zeichenfolgen enthalten tatsächlich keine schädlichen Elemente, daher dient dies lediglich der Demonstration.

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

Wir können dann die TrustedTypePolicy.createHTML()-Methode auf der zurückgegebenen Richtlinie verwenden, um TrustedHTML-Objekte aus unseren ursprünglichen Eingabezeichenfolgen zu erstellen. Diese werden dann an die writeln()-Funktion übergeben, wenn der Benutzer den Button 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 den Button. Beachten Sie, dass nach jedem Aufruf von writeln() ein Zeilenumbruch hinzugefügt wird, der jedoch nur innerhalb des <pre>-Elements sichtbar ist, da dessen Layout standardmäßig Leerzeichen bewahrt.

Spezifikationen

Browser-Kompatibilität