本文为您详细介绍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的流式读写处理异常方式类似。