Edge Security Acceleration:HTMLStream API

Información de contexto

Ejemplo

• Escenario

  Si necesita modificar todas las etiquetas de anclaje <a/> de una página HTML para que apunten a http://www.taobao.com, utilice en Edge Routine el código que se muestra a continuación.

• Código de ejemplo

  async function handleRequest(request) {
    // 1. In this example, the HTML page that you want to modify is returned. 
    const response = await fetch("http://www.example.com");
    // 2. Configure the stream processing-based parser to manage HTML content. The parser supports multiple CSS selectors.
    // Specify the method for capturing the syntax and register a callback function for rewriting. 
    const htmlStream = new HTMLStream(
      response.body, // Specify the HTML flow that you want to modify.
      [[
        "a",         // The element selector. This specifies that all the anchor tags are selected. 
        {  
          // Register a callback function. The element callback function can be called in the anchor tags or in the element nodes of the Document Object Model (DOM) API. 
          // In the callback function, you can change the event object (e). 
          element: function(e) {
            // Modify the href attribute.
            e.setAttribute("href", "http://www.taobao.com");
          }
        }
      ]]);
    
    // 3. Return the modified request to the browser. HTMLStream is a readable stream.
    // You can use HTMLStream in all scenarios that support ReadableStream. 
    return new Response(htmlStream);
  }
  
              export default {
    async fetch(request) {
      return handleRequest(request);
    }
  };            

• Análisis del resultado

  El código de ejemplo anterior muestra cómo modificar un flujo HTML en tiempo real mediante la API HTMLStream. A continuación se describe el funcionamiento de HTMLStream:

  • La API Fetch recupera una expresión de flujo para la solicitud. Sin embargo, es posible que Edge Routine aún no haya recuperado el cuerpo de la respuesta de la capa de red. Como resultado, se reduce la frecuencia de la recolección de elementos no utilizados causada por el almacenamiento en búfer de datos.

  • HTMLStream también es un flujo compatible con la operación TransformStream. Después de que HTMLStream recibe un flujo, llama a la función de callback de reescritura para modificar la página HTML especificada en tiempo real. Si desea modificar una página HTML, debe obtener el flujo de datos sin procesar de la página HTML. A continuación, puede colocar el flujo de datos sin procesar en el flujo HTML que haya creado, como se describe en el paso 2 del código de ejemplo anterior.

    • El primer parámetro de HTMLStream es un flujo, que representa el flujo de datos sin procesar de la página HTML.

    • El segundo parámetro de HTMLStream es una matriz, que representa un grupo de reescritores. Un reescritor es una matriz que incluye un selector. El selector se usa para especificar el contenido HTML que desea modificar y seleccionar un objeto. Algunos atributos del objeto se llamarán como funciones de callback. ["a" , {....}] en el ejemplo anterior se usa para declarar un reescritor, que representa una matriz con dos elementos. La cadena "a" del ejemplo anterior representa el selector de elementos que se usa para localizar todas las etiquetas de anclaje del documento. El objeto del ejemplo anterior especifica el objeto de callback. Si decide usar un selector de elementos, el objeto puede contener las funciones de callback que se describen a continuación:

      • La función de callback element. La firma de esta función de callback es function(e). Esta función de callback se llama cuando se analizan los elementos seleccionados por el selector de elementos.

      • La función de callback comments. La firma de esta función de callback es function(e). Esta función de callback se llama cuando se analizan los comentarios que están anidados dentro de los elementos.

      • La función de callback text. La firma de esta función de callback es function(e). Esta función de callback se llama cuando se analiza el texto de los elementos. Esta función de callback puede llamarse varias veces. Debido al procesamiento de flujos, HTMLStream puede estar procesando un fragmento de una cadena.

  • Puede responder directamente a HTMLStream. Sin embargo, HTMLStream no almacena datos en búfer. A diferencia de parse5 y htmlparser2, HTMLStream no genera un árbol DOM, lo que reduce significativamente el tiempo de procesamiento y el consumo de memoria. De esta manera, HTMLStream puede ofrecer un throughput y una concurrencia altos al analizar contenido HTML.

Reescritor

Sintaxis de los selectores de elementos

Funciones de callback para selectores de elementos

Selector de documento

Un selector de documento se usa para seleccionar un documento especificado. Para usar un selector de documento, establezca el primer elemento de la matriz del reescritor en null. En la operación de HTMLStream, solo se puede configurar un selector de documento.

Funciones de callback para selectores de documento

Manejo de errores

Parámetros de callback

Cada función de callback recibe un objeto que representa las etiquetas HTML seleccionadas u otra información relevante. Este objeto también se conoce como parámetro de callback. Este tema describe los parámetros de callback como Element, TextChunk y Comments.

Element

• Definición

  Este objeto se devuelve cuando se llama a la función de callback de Element. Este objeto representa las etiquetas HTML seleccionadas.

• Atributos

  • tagName(string): especifica el nombre de la etiqueta.

  • attributes(iterator): devuelve un iterador que localiza todos los atributos que se especifican en el formato [name, value].

  • removed(bool): especifica si se elimina el elemento. Este atributo es de solo lectura. Puede llamar al método remove() para eliminar un elemento. Por lo general, debe configurar este atributo para omitir los elementos que ya están eliminados.

  • namespaceURI: la URI de namespace de un elemento, como el elemento SVG o Script. Este atributo es de solo lectura.

• Métodos

  • Modificar atributos

    • getAttribute(name): consulta el nombre de un atributo de un elemento especificado.

    • setAttribute(name, value): establece un nombre de atributo para un elemento especificado y modifica el nombre de atributo de un elemento especificado.

    • hasAttribute(name): consulta si existe un nombre de atributo en un elemento especificado.

    • removeAttribute(name): elimina un nombre de atributo de un elemento especificado.

    Nota

    Tanto el nombre del atributo como el valor deben ser de tipo cadena.

  • Modificar contenido

    • before(data, option): inserta contenido antes del elemento especificado (la etiqueta del elemento).

    • after(data, option): inserta contenido después del elemento especificado (la etiqueta del elemento).

    • prepend(data, option): inserta contenido antes del contenido del elemento especificado (después de la etiqueta de apertura). Ejemplo: <div>(prepend) |aaaa|(append)</div>.

    • append(data, option): inserta contenido después del contenido del elemento especificado (antes de la etiqueta de cierre). Ejemplo: <div>(prepend) |aaaa|(append)</div>.

    • replace(data, option): reemplaza el elemento completo, incluidas las etiquetas y las etiquetas anidadas.

    • setInnerContent(data, option): especifica el contenido del elemento y conserva las etiquetas y los atributos.

    • remove(): elimina el elemento especificado. Después de eliminar el elemento, el valor del atributo removed cambia a true.

    • removeAndKeepContent(): elimina las etiquetas y los atributos del elemento especificado y conserva el contenido.

TextChunk

• Definición

  Este objeto se devuelve cuando se llama a la función de callback de Text. Este objeto representa un fragmento del texto HTML seleccionado.

• Atributos

  • removed(bool): especifica si se elimina el elemento. Este atributo es de solo lectura. Puede llamar al método remove() para eliminar un elemento. Por lo general, debe configurar este atributo para omitir los elementos que ya están eliminados.

  • text(string): especifica el contenido de texto. Este atributo es de solo lectura. El texto puede ser un fragmento de texto. Si la cadena está vacía, indica que se devuelve el último fragmento de texto. En este caso, puede combinar todos los fragmentos de texto.

  • lastInTextNode(bool): especifica si es el último fragmento de texto. Este atributo es de solo lectura. Si el valor de este atributo es true, el atributo text devuelve una cadena vacía.

• Métodos

  Modificar contenido

  • before(data, option): inserta contenido antes del elemento especificado (la etiqueta del elemento).

  • after(data, option): inserta contenido después del elemento especificado (la etiqueta del elemento).

  • replace(data, option): reemplaza el elemento completo, incluidas las etiquetas y las etiquetas anidadas.

  • remove(): elimina el elemento especificado. Después de eliminar el elemento, el valor del atributo removed cambia a true.

Comments

• Definición

  Este objeto se devuelve cuando se llama a la función de callback de Comments. Este objeto representa los comentarios del contenido HTML seleccionado.

• Atributos

  • removed(bool): especifica si se elimina el elemento. Este atributo es de solo lectura. Puede llamar al método remove() para eliminar un elemento. Por lo general, debe configurar este atributo para omitir los elementos que ya están eliminados.

  • text(string): especifica los comentarios existentes o los comentarios para sobrescribir los existentes. Este atributo es de lectura y escritura.

• Métodos

  Modificar contenido

  • before(data, option): inserta contenido antes del elemento especificado (la etiqueta del elemento).

  • after(data, option): inserta contenido después del elemento especificado (la etiqueta del elemento).

  • replace(data, option): reemplaza el elemento completo, incluidas las etiquetas y las etiquetas anidadas.

  • remove(): elimina el elemento especificado. Después de eliminar el elemento, el valor del atributo removed cambia a true.

Doctype

• Definición

  Este objeto se devuelve cuando se llama a la función de callback de DOCTYPE. Este objeto representa el DOCTYPE del contenido HTML seleccionado.

• Atributos

  • name(string): especifica el nombre de DOCTYPE. Este atributo es de solo lectura.

  • publicId(string): devuelve un identificador público. Si no existe ningún identificador público, se devuelve un valor de null. Este atributo es de solo lectura.

  • systemId(string): devuelve un identificador de sistema. Si no existe ningún identificador de sistema, se devuelve un valor de null. Este atributo es de solo lectura.

Docend

• Definición

  Este objeto se devuelve cuando se llama a la función de callback de Docend. Este objeto representa el final de un documento HTML.

• Métodos

  append(string, option): agrega contenido al final del documento HTML.