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 einen benutzerdefinierten Elemente-Konstruktor ausführt.

TypeError

Ein String wird als einer der Parameter übergeben, wenn vertrauenswürdige Typen durchgesetzt werden und keine Standardrichtlinie definiert wurde, um TrustedHTML Objekte zu erstellen.

Beschreibung

Die Methode ist im Wesentlichen die gleiche wie document.write(), fügt aber einen Zeilenumbruch hinzu (Informationen im verlinkten Thema gelten auch für diese Methode). Dieser Zeilenumbruch ist nur sichtbar, wenn er in ein Element eingefügt wird, in dem Zeilenumbrüche angezeigt werden. Die zusätzlichen Informationen in document.write() gelten auch für diese Methode.

Sicherheitsüberlegungen

Die Methode ist ein potenzieller Vektor für Cross-Site-Scripting (XSS) Angriffe, bei denen potenziell unsichere Strings, die von einem Benutzer bereitgestellt werden, in den DOM eingefügt werden, ohne vorher bereinigt zu werden. Obwohl 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 Wege, auf denen Angreifer HTML erstellen können, um schädliches JavaScript auszuführen.

Sie können diese Probleme mindern, indem Sie immer TrustedHTML Objekte anstelle von Strings übergeben und vertrauenswürdige Typen durchsetzen unter Verwendung 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ährliches Markup (wie <script>-Elemente und Event-Handler-Attribute) zu entfernen, bevor sie eingefügt wird.

Beispiele

Schreiben von TrustedHTML

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

Das Beispiel zeigt zunächst einen Standardtext und einen Button. Wenn der Button geklickt wird, wird das aktuelle Dokument geöffnet, einige HTML-Strings werden in TrustedHTML Instanzen umgewandelt und ins 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 JavaScripts, das das Update vorgenommen 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 die Methode createPolicy(), um eine Richtlinie namens "docPolicy" zu definieren.

Die neue Richtlinie definiert eine Transformationsfunktion createHTML() zur Erstellung von TrustedHTML Objekten, die wir an die writeln() Methode übergeben werden. Diese Methode kann mit dem Input-String machen, was sie möchte: Die Trusted Types API verlangt nur, dass Sie den Input durch eine Richtlinien-Transformationsfunktion leiten, nicht dass die Transformationsfunktion etwas Bestimmtes macht.

Sie würden die Methode verwenden, um den Input zu bereinigen, indem potenziell unsichere Features wie <script>-Tags oder Event-Handler-Attribute entfernt werden. Sanitisierung ist schwer richtig zu machen, daher wird dieser Prozess typischerweise mit einer anerkannten Drittanbieter-Bibliothek wie DOMPurify durchgeführt.

Hier implementieren wir einen rudimentären "Sanitizer", der < Symbole in den öffnenden und schließenden Script-Tags mit dem < Zeichen ersetzt. Die eingefügten Strings in diesem Beispiel enthalten tatsächlich keine schädlichen Elemente, das ist also rein zur Demonstration gedacht.

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

Wir können dann die Methode TrustedTypePolicy.createHTML() auf der zurückgegebenen Richtlinie verwenden, um TrustedHTML Objekte aus unseren ursprünglichen Eingabestrings 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 auf den Button. Beachten Sie, dass nach jedem Aufruf von writeln() ein Zeilenumbruch hinzugefügt wird, dieser jedoch nur im <pre> Element sichtbar ist, da dessen Layout standardmäßig Leerzeichen bewahrt.

Spezifikationen

Browser-Kompatibilität