Dokument: writeln()-Methode

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

InvalidStateError DOMException

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, wenn vertrauenswürdige Typen erzwungen werden und keine Standardrichtlinie definiert wurde zum Erstellen von TrustedHTML-Objekten.

Beschreibung

Die Methode ist im Wesentlichen die gleiche wie document.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 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, 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 (siehe Intervening 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 immer TrustedHTML-Objekte anstelle von Zeichenfolgen übergeben und vertrauenswürdige Typen durchsetzen, indem Sie die require-trusted-types-for CSP-Direktive verwenden. Dies gewährleistet, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu bereinigen, 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 die Trusted 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 in TrustedHTML-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 id="replace" type="button">Replace document content</button>

JavaScript

Zunächst 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() zum Erstellen der TrustedHTML-Objekte, die wir an die writeln()-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 zu bereinigen. Bereinigung ist schwer richtig umzusetzen, daher wird dieser Prozess typischerweise mit einer renommierten Drittanbieter-Bibliothek wie DOMPurify 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 die TrustedTypePolicy.createHTML()-Methode auf der zurückgegebenen Richtlinie verwenden, um TrustedHTML-Objekte aus unseren ursprünglichen Eingabezeichenfolgen zu erstellen. Diese werden dann der writeln()-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 von writeln() 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