本文为您详细介绍HTMLStream相关的API信息及异常错误处理。

重写器

重写器是用于注册重写指示的对象，实际为包含两个元素的数组。对数组的具体说明如下：
  • 数组的第一个元素必须为String或null。
    • String：表示一个元素选择器，该选择器始终用于定位一个元素或标签。
    • null：表示整个重写器是针对整个文档的。
      说明 多数情况下您不需要用文档级别的重写器，文档级别的重写器无法定位元素。
  • 数组的第二个元素是一个JS对象，表示您注册的回调函数对象。

    当您使用元素选择器时，其注册对象称为“元素选择器回调”；当您使用文档选择器时，其注册对象称为“文档选择器回调”。

说明 同一个HTMLStream可以设置多个不同的重写器，但只能设置一个文档选择器以及支持设置多个元素选择器。

元素选择器语法

元素选择器是CSS选择器的语法子集，语法是子集不代表语言和CSS选择器一模一样。元素选择器的语法如下：
  • *：所有元素或标签。
  • div：名为div的标签。您可以以此类推其他的标签名称，可以是HTML标签或定制化标签。
  • E#id：名为E的标签，标签的属性ID是值id。
  • E.Class：名为E的标签，标签的属性Class是值Class。
  • E[attr]：名为E的标签，标签的属性中含有名称attr。
  • 元素属性选择：
    • E[attr="a"]：选择标签E，标签的属性含有名attr，且值为a，注意区分大小写。
    • E[attr^="a"]：选择标签E，标签的属性含有名attr，且值为a，不区分大小写。
    • E[attr$="a"]：选择标签E，标签的属性含有名attr，且值以“a”结尾。
    • E[attr^="a"]：选择标签E，标签的属性含有名attr，且值以“a”开头。
    • E[attr*="a"]：选择标签E，标签的属性含有名attr，且值含有“a”。
    • E[attr|="a"]：选择标签E，标签的属性含有名attr，且值以“a-”开头的一串英文逗号（,）分隔的列表，例如en-ch, en-us。
  • 序列选择：
    • E F：选择标签F，且F存在父节点元素E中。
    • E > F：选择标签F，且F的直接父节点元素为E。
  • E:not(S)：选择元素E，S是另外一个选择器，当选择器值为false时，才能选中元素E。

元素选择器回调

元素选择器回调包含以下三个回调函数。
回调函数 说明 回调函数签名
element 该属性必须为一个非异步函数，该属性会在元素被解析完毕时调用。 回调函数的签名为function(e)，传入对象为Element对象。更多信息，请参见Element。
comments 该属性必须为一个非异步函数，该属性会在元素选择器选中的元素中存在注释时被调用。 回调函数的签名为function(e)，传入对象为Comments对象。更多信息，请参见Comments。
text 该属性必须为一个非异步函数，该属性会在元素选择器的元素text部分被解析时被调用。 回调函数的签名为function(e)，传入对象为TextChunk对象。更多信息，请参见TextChunk。
说明 该函数会被调用多次，当HTMLStream每次都从HTML原始数据流中读一部分出来text时，每次解析完毕就会调用这个函数。如果您想看到整个text，需要自己缓冲text后拼接起来。
说明 元素选择器可以不包含以上三个函数，此时对应的元素会被直接输出。如果您只想修改某一部分内容，只需要注册对应的回调函数。

文档选择器

文档选择器主要用于选择文档级别的内容。文档选择器用null表示，同一个HTMLStream中只能设置一个文档选择器。

文档选择器回调

文档选择器回调函数和元素选择器回调函数类似，文档选择器回调包含以下四个回调函数。
回调函数 说明 回调函数签名
doctype 该属性必须为一个非异步函数，该属性会在文档的doctype被解析后被调用。 回调函数的签名为function(e)，传入对象为Doctype对象。更多信息，请参见Doctype。
comments 该属性必须为一个非异步函数，该属性会在文档级别的comments被调用。 回调函数的签名为function(e)，传入对象为Comments对象。更多信息，请参见Comments。
text 该属性必须为一个非异步函数，该属性会在文档级别非元素的text节点遇到时被调用。 回调函数的签名为function(e)，传入对象为TextChunk对象。更多信息，请参见TextChunk。
说明 该函数会被调用多次，当HTMLStream每次都从HTML原始数据流中读一部分出来text时，每次解析完毕就会调用这个函数。如果您想看到整个text，需要自己缓冲text后拼接起来。
docend 该属性必须为一个非异步函数，该属性会在文档被解析完毕时调用，主要为了追加内容到文档末端，通常可以以注释的形式记录一些debug信息到HTML末尾，用于后续排查和追踪问题。 回调函数签名为function(e)，传入对象为Docend对象。更多信息，请参见Docend。

异常错误处理

以上任何一个回调函数中抛出的JS异常，都会在ER运行时被捕获，同时HTMLStream将停止处理HTML流，并且将您的异常顺势传播到外层。
  • 如果HTMLStream的reader.read是在JS中被触发，您的异常会被重新抛出。
  • 如果HTMLStream的reader.read是在ER运行时被调用，例如返回给客户端，那么异常将被ER运行时吞掉，客户端会看到一个被截断的内容，原因是HTMLStream是一个流，可能一部分已经发送至客户端。该操作与现在的TransformStream的流式读写处理异常方式类似。