Edge Security Acceleration：HTMLStream API

背景介紹

舉例說明

• 情境描述

  假設您需要將HTML頁面中所有的<a/> 標籤修改後全部指向http://www.taobao.com，在ER中您可以使用以下代碼實現。

• 程式碼範例

  async function handleRequest(request) {
    // 1.假設exmaple頁面返回的是待修改的HTML頁面。
    const response = await fetch("http://www.example.com");
    // 2.您需要設定好HTML流式解析器。流式解析器允許您設定多個不同CSS Selector
    //    文法的捕獲方式，然後註冊回呼函數進行改寫。
    const htmlStream = new HTMLStream(
      response.body, // 放入需要改寫的HTML流
      [[
        "a",         // 元素選取器，表示選擇所有的`a`標籤。
        {  
          // 註冊回呼函數對象，名為element的回呼函數會在a標籤（在DOM中為ElementNode）被調用。
          // 調用時您可以傳入object來更改e的資訊。
          element: function(e) {
            // 更改屬性href
            e.setAttribute("href", "http://www.taobao.com");
          }
        }
      ]]);
    
    // 3.返回修改後的請求到瀏覽器。HTMLStream是個ReadableStream，所以任何能使用
    //    ReadableStream的地方均可使用HTMLStream。
    return new Response(htmlStream);
  }
  
  export default {
    async fetch(request) {
      return handleRequest(request);
    }
  };

• 結果分析

  以上代碼便是簡單的使用HTMLStream即時修改HTML頁面流的方法，具體分析如下：

  • 通過Fetch您可以得到一個對請求回複的流的表示，實際ER可能沒有從網路層讀取body，該設計可以減少緩衝引起的大量GC問題。

  • HTMLStream也是一個流，他的作用是TransformStream，即接受一個流，然後通過您註冊的重寫handler即時更改HTML頁面。如果您要修改一個HTML頁面，需要得到對應HTML的未經處理資料流，再把這個流當作輸入，放入到新建立的HTML流中，例如上述程式碼範例中的樣本2。

    • HTMLStream的第一個參數是一個流，表示HTML未經處理資料。

    • HTMLStream的第二個參數是個數組，表示一組重寫器。重寫器實際是一個數組，它包含一個選取器，用於選擇需要改寫的HTML及選擇一個對象，對象中的部分property會被當作回呼函數調用。例如上述例子中["a" , {....}] 用於聲明一個重寫器，實際表示一個元素為2的數組。第一個字串“a”表示元素選取器，在上述例子中表示找出文檔中的所有a標籤。第二個對象表示回調對象，對使用元素選取器而言，該對象可以包含以下三個函數：

      • element函數，簽名為function(e)，當元素選取器選擇的element被解析時調用該函數。

      • comments函數，簽名為function(e)，當element中嵌套的注釋被解析時調用該函數。

      • text函數，簽名為function(e)，當element中的文字被解析時調用該函數。該函數支援調用多次，因為串流的原因，HTMLStream可能只是正在處理一個字串片段。

  • HTMLStream是一個流，您可以直接回複這個流，但HTMLStream內部不會進行資料緩衝，且HTMLStream和常見的parse5、htmlparser2不同，HTMLStream不會產生DOM樹，大大減少了處理時間和記憶體消耗，確保進行HTML解析的同時，保持高吞吐和並發。

重寫器

元素選取器文法

元素選取器回調

文檔選取器

文檔選取器主要用於選擇文檔層級的內容。文檔選取器用null表示，同一個HTMLStream中只能設定一個文檔選取器。

文檔選取器回調

異常錯誤處理

回調參數

每個回呼函數都會收到一個對象，表示選擇的HTML標籤或相關部分，該對象稱為回調參數。本文為您介紹Element、TextChunk和Comments等回調參數。

Element

• 定義

  該對象會在Element回呼函數被調用時提供給您，表示某個被選擇的HTML標籤。

• 屬性

  • tagName（string）：標籤名字。

  • attributes（iterator）：返回一個迭代器，該迭代器返回所有的屬性[name, value]。

  • removed（bool)：唯讀，表示該元素是否被刪除。刪除一個元素使用remove，多數情況下需要根據這個標籤跳過該元素，因為元素已經被刪除。

  • namespaceURI：唯讀，表示該元素的命名空間URI，例如svg或script元素。

• 方法

  • 修改屬性

    • getAttribute(name)：查詢某個元素的屬性名稱。

    • setAttribute(name, value)：設定和修改某個元素的屬性名稱。

    • hasAttribute(name)：查詢某個元素的屬性名稱是否存在。

    • removeAttribute(name)：刪除某個元素的屬性名稱。

    說明

    屬性名稱和值要求必須是string類型。

  • 修改內容

    • before(data, option)：將內容插入到該元素之前，即元素的標籤之前。

    • after(data, option)：將內容插入到該元素之後，即元素的標籤之後。

    • prepend(data, option)：將內容插入到該元素的內容之前，即元素的開啟標籤結束的後方，例如<div>(prepend) |aaaa|（append）</div>。

    • append(data, option)：將內容插入到該元素的內容之後，即元素的結束標籤結束的前方，例如<div>(prepend) |aaaa|（append）</div>。

    • replace(data, option)：替換整個元素，包括標籤和嵌套的標籤都會被替換。

    • setInnerContent(data, option)：設定元素內容，標籤和屬性不變。

    • remove()：刪除該元素，removed屬性為true。

    • removeAndKeepContent()：刪除元素的標籤和屬性，保留內容。

TextChunk

• 定義

  該對象會在text回呼函數被調用時提供給您，代表某個被選擇的HTML的Text部分。

• 屬性

  • removed（bool)：唯讀，表示該元素是否被刪除。刪除一個元素使用remove，多數情況下需要根據這個標籤跳過該元素，因為元素已經被刪除。

  • text（string）：唯讀，表示該text的內容。該text有可能只是一部分text，如果此字串為空白，代表這是最後一個chunk，您可以趁機把所有的text拼接起來。

  • lastInTextNode（bool）：唯讀，表示是否為最後一個text。如果為true，text屬性返回Null 字元串。

• 方法

  修改內容的方法如下：

  • before(data, option)：將內容插入到該元素之前，即元素的標籤之前。

  • after(data, option)：將內容插入到該元素之後，即元素的標籤之後。

  • replace(data, option)：替換整個元素，包括標籤和嵌套的標籤都會被替換。

  • remove()：刪除該元素，removed屬性為true。

Comments

• 定義

  該對象會在comments回呼函數被調用時提供給您，代表某個被選擇的HTML的注釋部分。

• 屬性

  • removed（bool)：唯讀，表示該元素是否被刪除。刪除一個元素使用remove，多數情況下需要根據這個標籤跳過該元素，因為元素已經被刪除。

  • text（string）：可讀可寫，表示注釋的內容或改變注釋內容。

• 方法

  修改內容的方法如下：

  • before(data, option)：將內容插入到該元素之前，即元素的標籤之前。

  • after(data, option)：將內容插入到該元素之後，即元素的標籤之後。

  • replace(data, option)：替換整個元素，包括標籤和嵌套的標籤都會被替換。

  • remove()：刪除該元素，removed屬性為true。

Doctype

• 定義

  該對象會在doctype回呼函數被調用時提供給您，代表某個被選擇的HTML的Doctype部分。

• 屬性

  • name（string）：唯讀，表示doctype名字。

  • publicId（string）：唯讀，如果有表示public identifier，否則返回null。

  • systemId（string）：唯讀，如果有表示system identifier，否則返回null。

Docend

• 定義

  該對象會在docend回呼函數被調用時提供給您，代表整個HTML的末尾部分。

• 方法

  append(string, option) ：用於向HTML流末尾加入若干內容。