把富文本从 WebView 里拽出来：HarmonyOS 原生富文本组件踩坑记

这个项目起因很朴素：资讯详情页的正文，官方给的两条路都不太合脚。 Web 组件渲染没问题，但滚动位置、图片手势、字体跟原生一套体系隔着一条缝； RichText 组件又只认自己那套结构化标签，拿到后台编辑器吐出来的 HTML 只能干瞪眼。

于是我用十七天重写了一个：手写递归下降解析器 + ArkUI 原生渲染，中间产物是一棵渲染树， 最后落成一组扁平的 RenderBlock。现在它支持 h1~h6、下划线、 删除线、高亮、行内 code、上标 x²、 下标 H₂O、链接、图片、嵌套列表、引用块、代码块和表格。

这一段刻意写成后台编辑器的典型产出：margin:0px;padding:0px;text-indent:2em。 浏览器会给首行缩进两个字，组件不认 text-indent，会顶格显示——这是本次重点记录的一处差异。 另外注意 margin 简写也不被解析（只认 margin-top / margin-bottom），所以段落间距仍按组件的 paragraphSpacing 走。

这篇是我自己整理的验收清单，写完直接扔进数据库当测试数据用。 每一节都对应一组真实踩过的坑，文末有完整用例表。

一、标题层级：先把 h1~h6 全部摆出来

组件默认给六级标题配了递减的字号（24/21/19/17/16/15）、字重（700/700/700/700/600/600） 和独立的颜色。下面这一段是全量对照，肉眼扫一遍就能看出有没有塌陷、有没有和正文混在一起：

三级标题：H3 · 19vp / 700

四级标题：H4 · 17vp / 700

五级标题：H5 · 16vp / 600

六级标题：H6 · 15vp / 600

顺带测三种"标题里的花样"：

带行内代码与加粗的标题

被内联 style 改色的标题（应覆盖默认色）

写了 text-align:center 的标题（内联样式应覆盖标题默认样式，居中生效）

写了 align 属性的标题（组件不读 align，应保持左对齐）

二、行内标签：一次全量核对

正文里最容易被吞掉的就是这些"看起来一样"的标签。下面按类别排开， 每一组后面括号里是期望表现。

strong 加粗、b 加粗、em 斜体、i 斜体、 cite 斜体引用、var 变量斜体、u 下划线、ins 下划线、 s 删除线、del 删除线、strike 删除线。

mark 默认黄底、 行内 code、 Ctrl + S、samp 等宽、tt 等宽、 small 小两号、big 大两号、x² + y₁、 ABBR 缩写、q 短引用、 裸 span、label、time 标签、 data 标签、bdi、bdo。

嵌套叠加：加粗里套斜体再套下划线最后套代码， 以及 加粗 + 删除线、斜体 + 高亮。 期望：多属性并行生效、互不覆盖。

font 标签—— 编辑器从老 CMS 里带出来的老写法，组件不读 font 的属性， 期望样式不变（继承正文），文字正常显示不丢失。

三、内联 style：能继承什么，不能继承什么

这一整段是内联 style：橙色、18vp、加粗。

换行测试：局部 span 覆盖蓝色， 然后回到段落自己的绿色，并带浅黄底纹。背景色应随文字行而不是整段铺满。

字间距 2px 的段落，中文间距拉开后仍应正常换行不断行。

居中文本

右对齐文本

两端对齐文本（ArkUI 无 Justify 枚举，组件会退化成左对齐，这是已知取舍）。

行高 2.2 倍的段落，用于确认行高确实按倍数乘字号换算成 vp，而不是被忽略。

同时给了外边距、左内边距与圆角。 期望：上下间距明显变大、整段左缩进 20vp；圆角对纯文本块无视觉影响（不报错即可）。

四种颜色写法各来一处： 三位简写 / rgb() / rgba() 半透明 / 英文色名；字体族也试一个： Consolas 等宽字体。

这条写了五个组件不支持或不完整支持的属性 （display / box-shadow / float / border 简写 / text-shadow）。期望：安静地忽略，不抛异常、不丢文字。

这条只用了"简写以外的变体"： padding-top / padding-bottom / margin-left / margin-right。 组件只认 padding-left / padding-right / margin-top / margin-bottom， 所以这四个属性全部无效——期望视觉上没有任何变化，这是已知边界。

四、链接：一个 href 的十种写法

先是最常规的四种，全部点一遍： 官方站点（绝对 https）、 组件官网（http）、 带路径的文档链接、 另一个域名。

样式变体：链接内联改色改字重、 链接里套加粗、 链接里套代码。 期望：链接色（或内联色）+ 下划线仍在，点击仍可跳转。

相对路径与协议相对：相对路径链接（需配 baseUrl 才可点开）、 协议相对链接。 期望：不崩溃、可渲染；无 baseUrl 时相对路径拼不出完整地址，点击后跳转失败属预期。

换行链接（v1.0.2 修过的点，两行都要能点）： 第一行写着超长链接文字
第二行继续写着超长链接文字。

链接包图片：  后面跟一段普通文字，确认图片不会被挤到下一行。无 href 的链接：这行没有 href， 空 href 的链接：这行 href 是空的。 编辑器常带的属性：带 target 与 rel 的链接 （这两个属性组件不读，期望照常渲染并可点）。

五、图片：大图自适应、小图不放大、坏图有占位

正文大图，尺寸写在 style 里 （编辑器就是这么干的，不写 width 属性）。声明 800×450，超过屏宽 60%，应铺满宽度并按比例缩放，即忽略后台设的固定宽高：

只有宽度、没有高度（style 写法）：， 期望保持比例不拉伸、不塌成一条线。

写成百分比宽度的（编辑器拖拽缩放图片时常产出百分比）：， parseLen 对 % 返回 undefined， 等于没给尺寸，期望按原尺寸或自适应，至少不能 0 高。

没有写任何尺寸：， 期望按原尺寸或自适应渲染，至少不能为 0 高。

小图 / 图标 / 表情（48×48，低于屏宽 60%，应保持原名尺寸不放大）： 图标与文字在同段内混排，期望基线大致对齐、文字正常换行。

属性与 style 冲突的图：。 属性写的是 400×200、style 写的是 800×400。浏览器里 CSS 优先，会按 800×400 渲染； 组件读的是 attrs.get('width') ?? style.width， 属性优先，会拿到 400×200。这是一处需要记录的差异（400 低于屏宽 60%，按小图保持原尺寸）。

坏图（域名不可解析）：， 期望显示占位底色、不闪退，并触发 onImageLoadError 回调。

内嵌图一（base64 PNG，80×40）：

内嵌图二（base64 SVG，120×60）：

懒加载图（src 是真的，另有 data-original / data-src / data-w 等编辑器加的属性， 组件不读 data-*，期望不影响渲染）：

被拦截的图片协议： 期望：整张图不渲染， 不出现空白占位框，也不报错。（这一行里除了本句文字，不应再有别的内容。）

六、列表：嵌套三层之后最容易出错

无序列表（三级嵌套 + 多种 marker）

• 一级：纯文本项
• 一级：含加粗、行内代码与链接的项
  • 二级 marker 期望为空心圆 ○
  • 二级：含较长文本，用于确认换行后悬挂缩进是否与 marker 对齐，不会让第二行跑到圆点下面
    • 三级 marker 期望为实心方块 ▪
    • 三级：再嵌套一层就到极限了
• 一级：最后一项

有序列表（含长项与行内标签）

1. 第一步：把 HTML 字符串塞给组件（@Prop html，变化自动重解析）
2. 第二步：按需注入 RichTextConfig，不传就用默认样式
3. 第三步：验证斜体、下划线在列表项里不被吞掉
4. 第四步：确认序号是 1. 2. 3. 4. 连续递增，不跳号
5. 第五步：写了 start="9" 的有序列表另起一段测试（见下）

下面是 <ol start="9">，组件不读 start 属性： 期望从 1 开始编号，这是已知限制，不算 bug。

9. 期望显示为 1. 而不是 9.
10. 第二项

<ul type="square"> 同理，type 属性被忽略，marker 仍按层级走。

• 期望 marker 仍是 •

列表项的边界写法

• 第一行内容
  第二行用 br 换行，期望两行同属一个列表项，marker 只在第一行
• 项里有图片： 期望不撑破列表宽度
• 项上写了内联 style 改色改字号：期望不生效——li 自身的样式不参与计算 （walkListItem 只摊平 li 的 children），所以这一项应保持正文颜色与字号， 但 li 内部的 span 是有效的：这个 span 的绿色加粗应当生效。
• 空项上面那个应该没有内容，期望不渲染空行或只留极小高度
• 项里嵌代码块（<pre> 在 li 内，组件只按行内文本处理，属已知降级）

  const a = 1;
  console.log(a);

七、引用块：那个 669vp 的幽灵

v1.0.2 之前，引用块的高度会莫名其妙变成 669vp，跟内容多少无关。 根因是左侧竖线用了一个 height('100%') 的子组件， 在外层 Scroll 的无界高度约束下被解析成"最大可用高度"。现在竖线改用 border.left 实现，高度完全由内容驱动。

单段引用：这一块的背景高度应当紧紧贴着文字，上下各留一个 padding，不能拉长。 注意这里 blockquote 自带背景/边框/内边距的内联样式，组件不读这些属性， 背景色、左侧竖线、内边距全由 RichTextConfig 的 quoteBackground / quoteBorderColor / quotePadding 决定； 但 color 是会被继承的， 所以引用块里的文字色用的是上面那个 #57606A。

多段引用第一段：用来确认段间距不会跑到背景外面形成一条空白带。

多段引用第二段：中间段落之间应该保留正常段间距，作为视觉分隔。

多段引用第三段：最后一段的下边距应被清零，背景底部不留多余空白。

引用块里放列表：

• 列表项一
• 列表项二

引用块里放代码块（这个 pre 刻意写了深色背景与亮色文字，模拟后台代码高亮插件）：

git commit -m "fix: quote height" && git tag v1.0.2

组件的代码块样式不读内联 style， 会回落到 config 的 codeBlockBackground / codeBlockTextColor，所以这里应当是浅底深字，而不是黑底白字。

引用块里放标题

标题应继承引用块的文字颜色，而不是用标题自己的深色，视觉上要"陷进去"。

引用里再嵌套一层引用，确认不会崩、层级缩进合理。

八、代码块：要横向滚动，不要断行毁缩进

代码块会把空格替换成不换行空格，保证每行不自动折行，超宽靠横向滚动条解决。 下面这段每行都带缩进，重点看四层缩进是否对齐、能否左右滑动。 语言识别用的是 data-language 属性 （后台若用 class="language-xxx"，组件也认）：

// 轻量语法高亮：注释、关键字、字符串、数字、函数名
import { RichTextConfig } from './core/RichTextConfig';

export class RichTextBuilder {
  private readonly maxCacheSize: number = 32;      // 常量
  private cache: Map<string, RichNode> = new Map(); // 泛型尖括号在 HTML 里必须转义

  build(html: string): RenderBlock[] {
    const root: RichNode = HtmlParser.parse(html);
    const blocks = new Array<RenderBlock>();
    if (html.length > 0 && this.cache.has(html)) {
      console.log("cache hit: " + html.length + " chars, ratio = " + 0.8732);
      return this.cache.get(html)!;
    }
    return blocks;
  }
}

没有任何语言标记的代码块（高亮应关闭/走纯文本路径，颜色回退到代码块默认色）：

这是一段没有 data-language 的 pre 内容
  第二行缩进两个空格
    第三行缩进四个空格
	第四行是 tab 缩进（应展开为四个空格宽）
末尾行

代码块里的空行（应该保留行高，而不是被吃掉）：

{
  "name": "htmlrichtext",

  "version": "1.0.2",

  "tags": ["harmonyos", "arkui", "rich-text"]
}

超长单行（必须横向滚动，绝不能折行把变量拆成两半）：

const url = "https://cdn.example.com/a/really/really/really/long/path/segment/segment/segment/segment/segment/asset.png?v=20260911&format=webp&width=1080&quality=85";

代码块与内联 HtmlParser.parse(html) 混在同一段， 然后是普通文字。期望行内代码有底色和粉色文字，代码块有灰底和圆角。

九、表格：最难啃的一块骨头

表格单独拆了一个 TableBlockView： 用 onAreaChange + 双 minHeight 测量行高， 斑马纹、表头样式、底部边框都在它内部管。下面按"从简到繁"排开， 所有表格都写成编辑器的产出形态——border/cellpadding/cellspacing 属性和 border-collapse、width:100% 内联样式都会带上， 这些组件全都不读，边框与内边距一律由 config 的 tableBorderColor / tableCellPadding 决定。

9.1 最简表格（无表头）：

单元格 A1	单元格 B1
单元格 A2	单元格 B2

9.2 标准表格（thead + tbody + th，被测最多的一种）：

能力项	实现方式	状态
行内样式	Text + Span	已完成
图片	独立 Image + Flex wrap	已完成
表格	Grid + 列模板	已完成

9.3 colspan / rowspan：这是最容易出问题的一组， 已知限制是"跨列单元格位于行中间时，起始列按数组索引定位，可能与相邻行重叠（colspan=1 不受影响）"。 请重点看下面这张表的第 2 行是不是错位：

表头跨三列（colspan=3）
普通单元格	跨两列，且位于行中间（高风险用例）
行首跨两列		行尾单列
纵向跨两行（rowspan=2）	右侧第一行	右侧第一行
	右侧第二行	右侧第二行

9.4 单元格样式与对齐：组件只读 align 属性。 单元格上的内联 style 完全不生效（连 color 都不行，因为 td 自身不参与样式计算）， 只有单元格内部的 span 样式有效。三行都看一眼：

align=left	align=center	align=right
style 居中 + style 改红（预期两者都无效）	style 右对齐（预期无效）	单元格内 span 改色（预期有效）

9.5 单元格里的富内容（加粗/代码/链接/多行/空单元格/长文本混在一起）：

类型	内容
行内标签	加粗 + 斜体 + code + 链接
强制换行	第一行 第二行 第三行 第四行
长文本自动换行	这一格塞了很长的一段中文，用来验证单元格内部的自动换行以及同一行其余单元格的高度是否被同步撑高，避免出现行高错乱或内容被裁切的情况。
超长无空格串	https://cdn.example.com/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.png
空单元格
仅一个短字	x

9.6 宽表（6 列，窄屏下考验列宽分配与是否溢出）：

版本	类型	核心改动	影响面	风险	状态
1.0.0	首个稳定版	手写解析器 + 原生渲染	全量	中	已发布
1.0.1	修复	大图自适应、预览手势、协议白名单	图片	低	已发布
1.0.2	修复	表格重构、引用块高度、混排换行	表格/引用	高	已发布
1.1.0	新增	解析错误回调 + AST 导出	解析层	中	规划中

9.7 被 div 包裹的表格（v1.0.2 修过的点，之前会整表丢失或退化成文本。 编辑器在表格外面套一层可拖拽容器是常态）：

9.8 引用块里的表格（引用块内部会再走一遍块级遍历，表格应正常存活）：

参数	默认值
tableMinRowHeight	0
tableHeaderTextWeight	600

9.9 单元格里嵌表格（已知降级）：外层收集行时会在 td 处停止下钻， 内层表格不会被外层吞掉；内层表格本身按行内文本降级处理。期望：不崩、外层行列数不错乱。

外层表头	含内嵌表格的单元格
普通格	内层 A 内层 B 内层表格后面的文字

9.10 表头样式与斑马纹配置验证（默认配置下奇偶行同色，即看不出斑马纹； 把 tableOddRowBackground 改成 #FAFAFA 后， 下面这张表的第 2、4 行应出现浅灰底。注意单元格里写的 background-color 内联样式是不生效的，别被它误导）：

序号	行类型	期望背景
1	表头	#F5F6F7
2	偶数数据行	tableEvenRowBackground
3	奇数数据行	tableOddRowBackground
4	偶数数据行	tableEvenRowBackground

9.11 只有表头、没有数据行的表格（预期：既然存在 tr 就会成表， 应正常渲染出这一行表头，不崩、不变形）：

只有表头

9.12 完全没有行的表格（预期：整块不渲染，不留空白——判据是与上下两段之间没有多余空隙。 编辑器删空表格内容后常常残留这种空壳）：

十、HTML 实体与编码：别让 emoji 变成方块

这一节全部是编码问题，配合 utf8mb4 一起看。编辑器把 & 转义成 & 是常规操作， 所以实体解码这条链路一定要通。

命名实体：& < > ' "   © ® ™ … — – « » · • × ÷ ¥ € ° ± µ ² ³ ½ ¼ ‘ ’ “ ” ′ § ¶ ¢ £ ∑ √ ∞ ≤ ≥ ≠ ≈ π（末尾五项依次是 ≤ ≥ ≠ ≈ π， 若未替换会在这里看到 &le; 这样的原始写法）

数字实体（十进制）：' " © 中 文 好 😀 这一行依次是单引号、双引号、©、中、文、好、😀——少一个都会在这里露出破绽。

数字实体（十六进制）：' 中 文 𠮷（生僻字：𠮷，4 字节 UTF-8）😀（😀）🚀（🚀）

未收录实体原样保留：α β γ ω &unknown;（这四个组件未收录，期望原样输出，不变成空）。 无分号写法：  ©（缺少分号，正则不匹配，期望原样输出）。

换行实体与制表实体（预期存在差异，不算 bug）：换行实体 → ，制表实体 → 。 若组件把它们解码成真实的换行与缩进、而浏览器把它们折叠成一个空格，这属于两边排版模型的固有差异，记录下来即可。

直接写入的字符：emoji 😀🚀🎉👍、全角标点：，。；：？！""''（）【】《》、破折号——省略号…… 数学符号：±×÷≈≠≤≥∑∏√∞、箭头 → ← ↑ ↓ ⇒、货币 ¥ $ € £ ₩、形近字符 O0oO·Il1|、易混淆空格： 普通空格| |全角空格(　)|（第二种是 &nbsp; 不换行空格、第三种是 U+3000 全角空格， 三种宽度应当肉眼可分）。

中文编码边界：起始字符（U+4E00）一、末尾字符（U+9FFF）鿿、扩展 A 区（U+3400）㐀、 代理对边界（U+FFFD）�、零宽连接符（U+200D）与变体选择符（U+FE0F）组合：👨‍👩‍👧‍👦（一个家庭 emoji， 由多个码点加 ZWJ 组成）——这一项最容易在入库阶段被截断。

十一、容错：喂给它一堆脏 HTML

后台编辑器、手工粘贴、爬虫抓取，什么脏 HTML 都会遇到。下面这些写法都不规范， 期望结果只有一条：不抛异常、不闪退、能渲染多少渲染多少。

大写标签强转小写、大写 EM、大写 U、 大写 A 带大写属性、

大写 P 段落，内联样式也应照常解析

。

属性三种引号写法：双引号、 单引号、 无引号、裸属性、 。

自闭合与 void 标签：
换行自闭合、
换行不闭合、

---

、

---

、 图片自闭合 。

文本里出现尖括号：3 < 5 且 7 > 2，以及没转义的 3 < 5 —— 第二个"小于号"后面跟的是空格与数字，不是合法标签名，组件应按普通字符输出，不能把它后面的内容当标签吞掉。

下面这一行是五个"凭空多出来的闭合标签"，它们对应的开始标签根本不存在：