文件：writeln() 方法

語法

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

引數

markup, …, markupN

TrustedHTML 或字串物件，包含要寫入文件的文字。

返回值

無（undefined）。

異常

InvalidStateError DOMException

此方法是在 XML 文件上呼叫的，或者在解析器當前正在執行自定義元素建構函式時呼叫的。

TypeError

當強制執行可信型別（Trusted Types）且沒有定義預設策略來建立 TrustedHTML 物件時，字串被作為其中一個引數傳遞。

描述

此方法與 document.write() 基本相同，但會新增一個換行符（連結主題中的資訊也適用於此方法）。此換行符僅在注入到顯示換行符的元素內部時才可見。document.write() 中的其他資訊也適用於此方法。

安全注意事項

此方法是跨站指令碼（XSS）攻擊的一個潛在載體，其中使用者提供的潛在不安全的字串在未首先進行清理的情況下被注入到 DOM 中。儘管此方法在某些瀏覽器中可能會阻止<script>元素在注入時執行（有關 Chrome 的資訊，請參閱Intervening against document.write()），但它易受到攻擊者以多種其他方式精心構造 HTML 以執行惡意 JavaScript 的攻擊。

您可以透過始終傳遞 TrustedHTML 物件而不是字串，並使用 require-trusted-types-for CSP 指令強制執行可信型別來緩解這些問題。這確保了輸入透過轉換函式傳遞，該函式有機會在注入之前清理輸入，以移除潛在危險的標記（例如<script>元素和事件處理程式屬性）。

示例

寫入 TrustedHTML

此示例使用 Trusted Types API 在將 HTML 字串寫入文件之前對其進行清理。您應始終使用可信型別來將不受信任的字串傳遞給不安全的 API。

該示例最初顯示一些預設文字和一個按鈕。當點選按鈕時，當前文件被開啟，一些 HTML 字串被轉換為 TrustedHTML 例項並寫入文件，然後文件被關閉。這會替換示例框架中的文件，包括按鈕的原始 HTML 和進行更新的 JavaScript！

HTML

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

JavaScript

首先，我們使用 Window.trustedTypes 屬性訪問全域性 TrustedTypePolicyFactory，並使用其 createPolicy() 方法定義一個名為 "docPolicy" 的策略。

新策略定義了一個轉換函式 createHTML()，用於建立我們將傳遞給 writeln() 方法的 TrustedHTML 物件。此方法可以對輸入字串進行任何操作：可信型別 API 只是要求您將輸入透過策略轉換函式傳遞，而不是要求轉換函式執行任何特定操作。

您可以使用此方法透過移除潛在不安全的功能（例如 <script> 標籤或事件處理程式屬性）來清理輸入。清理很難做到正確，因此此過程通常使用信譽良好的第三方庫，例如 DOMPurify。

在這裡，我們實現了一個基本的“清理器”，它將指令碼開始和結束標籤中的 < 符號替換為 < 字元。此示例中注入的字串實際上不包含任何有害元素，因此這純粹是為了演示。

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

然後我們可以對返回的策略使用 TrustedTypePolicy.createHTML() 方法，從我們原始的輸入字串建立 TrustedHTML 物件。當用戶點選按鈕時，這些物件隨後會傳遞給 writeln() 函式。

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();
});

結果

點選按鈕。請注意，每次呼叫 writeln() 後都會新增一個換行符，但由於 <pre> 元素預設保留空白，因此此換行符僅在該元素內部可見。

規範

瀏覽器相容性