Dokument: writeln()-Methode

Syntax

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

Parameter

markup, …, markupN

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

Rückgabewert

Keiner (undefined).

Ausnahmen

InvalidStateError DOMException

Die Methode wurde für ein XML-Dokument aufgerufen oder während der Parser gerade den Konstruktor eines benutzerdefinierten Elements ausführt.

TypeError

Einer der Parameter ist eine Zeichenfolge, obwohl Trusted Types erzwungen werden und keine Standardrichtlinie definiert wurde, um TrustedHTML-Objekte zu erstellen.

Beschreibung

Die Methode entspricht im Wesentlichen document.write(), fügt jedoch einen Zeilenumbruch hinzu. Die Informationen auf der verlinkten Seite gelten auch für diese Methode. Dieser Zeilenumbruch ist nur sichtbar, wenn er innerhalb eines Elements eingefügt wird, das Zeilenumbrüche darstellt. Auch die zusätzlichen Informationen zu document.write() gelten für diese Methode.

Sicherheitsaspekte

Die Methode kann für Cross-Site-Scripting-Angriffe (XSS) genutzt werden, wenn potenziell unsichere Zeichenfolgen von Benutzern ohne vorherige Bereinigung in das DOM eingefügt werden. Zwar verhindert die Methode in manchen Browsern möglicherweise die Ausführung eingefügter <script>-Elemente (siehe Intervening against document.write() für Chrome), doch Angreifer können HTML auf viele andere Arten so gestalten, dass schädliches JavaScript ausgeführt wird.

Sie können diese Risiken verringern, indem Sie immer TrustedHTML-Objekte statt Zeichenfolgen übergeben und mithilfe der CSP-Direktive require-trusted-types-for Trusted Types erzwingen. Dadurch wird sichergestellt, dass die Eingabe eine Transformationsfunktion durchläuft. Diese kann die Eingabe bereinigen und potenziell gefährliches Markup (etwa <script>-Elemente und Event-Handler-Attribute) entfernen, bevor es eingefügt wird.

Beispiele

TrustedHTML schreiben

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

Das Beispiel zeigt zunächst einen Standardtext und eine Schaltfläche an. Wenn auf die Schaltfläche geklickt wird, wird das aktuelle Dokument geöffnet. Einige HTML-Zeichenfolgen werden in TrustedHTML-Instanzen umgewandelt und in das Dokument geschrieben. Anschließend wird das Dokument geschlossen. Dadurch wird das Dokument im Beispiel-Frame ersetzt – einschließlich des ursprünglichen HTML-Codes für die Schaltfläche und des JavaScript-Codes, der die Aktualisierung ausgelöst hat!

HTML

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

JavaScript

Zunächst greifen wir über die Eigenschaft Window.trustedTypes auf die globale TrustedTypePolicyFactory zu und definieren mit ihrer Methode createPolicy() eine Richtlinie namens "docPolicy".

Die neue Richtlinie definiert eine Transformationsfunktion createHTML(), mit der wir die TrustedHTML-Objekte erstellen, die wir an die Methode writeln() übergeben. Diese Funktion kann die Eingabezeichenfolge beliebig verarbeiten: Die Trusted Types API verlangt lediglich, dass die Eingabe eine Transformationsfunktion einer Richtlinie durchläuft, nicht aber, dass diese etwas Bestimmtes tut.

In der Praxis würden Sie die Funktion verwenden, um die Eingabe zu bereinigen, indem Sie potenziell unsichere Bestandteile wie <script>-Tags oder Event-Handler-Attribute entfernen. Eine korrekte Bereinigung ist schwierig. Daher wird dafür üblicherweise eine bewährte Bibliothek eines Drittanbieters wie DOMPurify verwendet.

Hier implementieren wir einen einfachen „Sanitizer“, der <-Zeichen in öffnenden und schließenden Script-Tags durch die Zeichenfolge < ersetzt. Die in diesem Beispiel eingefügten Zeichenfolgen enthalten keine schädlichen Elemente; dies dient lediglich der Veranschaulichung.

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

Anschließend können wir mit der Methode TrustedTypePolicy.createHTML() der zurückgegebenen Richtlinie aus unseren ursprünglichen Eingabezeichenfolgen TrustedHTML-Objekte erstellen. Diese werden an die Funktion writeln() übergeben, wenn der Benutzer auf die Schaltfläche 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();
});

Ergebnis

Klicken Sie auf die Schaltfläche. Beachten Sie, dass nach jedem Aufruf von writeln() ein Zeilenumbruch eingefügt wird. Dieser ist jedoch nur innerhalb des <pre>-Elements sichtbar, da dessen Darstellung standardmäßig Leerraum beibehält.

Spezifikationen

Browser-Kompatibilität