本文为您详细介绍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的流式读写处理异常方式类似。
在文档使用中是否遇到以下问题
更多建议
匿名提交