Joplin 的 ENEX 导入容错机制：表格中非法标签的解析与 Markdown 转换

本篇以 Joplin 的 ENEX（Evernote 导出格式）导入测试用例 table_with_invalid_content 为中心，讲解当 <table> 内混入 HTML 规范不允许的 <div> 标签时，Joplin 的转换器如何安全地忽略非法内容并稳定产出 Markdown 表格。读完后，你能理解这套「忽略非法结构、保留有效数据」的容错设计在 SAX 解析、Section 树构建与 drawTable 渲染三个环节的具体落地方式，并能定位到每一处对应的源码与测试依据。

测试用例本体：期望输出的 Markdown 文件

本文的主体文件是 table_with_invalid_content.md，它是 ENEX 导入单元测试的期望输出文件，完整内容只有 4 行：

|     |     |
| --- | --- |
| one | two |
| three | four |

这 4 行看似简单，却精确编码了一组关键行为约定：

• 第 1 行是一个空表头行（两个空白单元格），说明源数据中没有任何 <th>，转换器仍需按 Markdown 表格规范补出表头；
• 第 2 行的 | --- | --- | 是由源码固定生成的 3 个连字符构成的分隔行（3 是 Markdown 单元格的最小可渲染宽度）；
• 第 3、4 行保留了全部有效数据 one、two、three、four，证明混入的非法 <div> 标签没有污染任何单元格内容。

它的输入文件是同一目录下的 table_with_invalid_content.html，完整内容如下：

<table>
	<div></div> <!-- INVALID! -->
	<tr>
		<td>one</td>
		<td>two</td>
	</tr>
	<tr>
		<div></div> <!-- INVALID! -->
		<td>three</td>
		<td>four</td>
	</tr>
</table>

按照 HTML 规范，<table> 的直接子元素只应是 <tr>、<caption>、<colgroup> 等，<tr> 内也只应有 <td>/<th>。而这份输入在表格顶层和 <tr> 内部各放了一个空 <div>（源码中以 INVALID! 注释标明）。这类"脏 HTML"并非人为构造的异常，而是真实场景的缩影：从网页剪藏过来的笔记常常带有用于页面布局的多余容器标签，Evernote 里同样会显得杂乱，ENEX 文件自然继承了这些结构。

测试如何驱动：全量扫描式的转换比对

这个用例不是孤立存在的，它被一个"目录级"的测试循环自动覆盖。在 import-enex-md-gen.test.ts 中：

1. 测试扫描 enex_to_md 目录（见 test 文件第 14 行 的 enexSampleBaseDir 定义），遍历所有 .html 文件；
2. 对每个文件，把 HTML 内容包进 <div>...</div> 后调用 enexXmlToMd（第 47 行）；
3. 与同名 .md 期望文件逐字符比对（Windows 下先做 \r\n 归一化），不一致时打印逐行差异并断言失败。

也就是说，本文主体文件 table_with_invalid_content.md 与 table_with_invalid_content.html 构成一组"输入/期望输出"对：只要转换器的表格行为发生任何变化（多输出一行、空表头消失、单元格被污染），这个用例就会失败。同目录下还有 table1、tableWithCaption、tableWithNewLines 等一系列表格用例，共同锁定 drawTable 的行为边界。更上层的导入流程则另有 InteropService_Importer_EnexToMd.test.ts 等集成测试覆盖完整 ENEX 文件导入。

源码纵深一：SAX 状态机如何"容忍"非法标签

转换核心位于 import-enex-md-gen.ts。它用 SAX 流式解析器（非严格模式，见 第 622 行 的 strict = false）逐事件地把 HTML 构建成一棵 Section 树，节点类型由 SectionType 枚举 定义（text / tr / td / table / caption / hidden / code）。

关键在 opentag 事件的处理（第 705 行至 769 行）：

• 遇到 <table> 就压入一个 Table 节；<tbody>/<thead> 直接被忽略；
• 遇到 <tr> 时，即使当前上下文并不是 table（即标签出现在"错误的位置"），源码也只打印告警而不中断，仍然创建 Tr 节。这里的注释（第 716-726 行）解释得很直白：这类无效 HTML 多半来自被剪藏的网页，"在 Evernote 里就是一团乱麻，在 Joplin 里也一样乱——但数据至少还在"，而且如果直接丢弃节，后续 drawTable() 反而会出错；
• <td>/<th> 同理（第 741-745 行），且 <th> 会把所在行标记为 isHeader = true；
• <caption> 在非表格上下文中也仅告警。

回到本文的用例：两个 <div></div> 既不是 tr/td/caption，也不携带任何文本，最终会以空片段的形式出现在对应 Section.lines 中，等待渲染阶段被丢弃。另一个重要的"降噪"机制在 text 事件处理器（第 659-660 行）：当当前节是 table、tr 或 tbody 时，空白文本直接被丢弃，保证标签之间的换行和缩进不会渗进单元格。

源码纵深二：drawTable 的非法行跳过与表头补全

渲染阶段的核心函数是 drawTable()。它对 table.lines 逐行遍历，而跳过非法内容的代码就在本用例的源码注释里被点名（第 1257-1263 行）：

if (typeof tr === 'string') {
    // A <TABLE> tag should only have <TR> tags as direct children.
    // However certain Evernote notes can contain other random tags
    // such as empty DIVs. In that case we just skip the content.
    // See test "table_with_invalid_content.html".
    continue;
}

<tr> 内部的非法碎片走的是同一套逻辑（第 1272-1275 行）。于是本文用例中的两个空 <div> 在此被安静地跳过，one/two/three/four 四个单元格完整保留——这正是期望输出只有 4 行表格、没有任何多余内容的由来。

接下来逐行复盘期望输出的生成过程：

1. 空表头行：输入中第一行不含 <th>（isHeader 为 false），于是 emptyHeader 逻辑被触发——用空白填充的单元格占位（第 1327-1334 行），并在数据行输出后补出表头行与分隔行（第 1344-1348 行）。这对应输出第 1 行的两个空白单元格；
2. | --- | --- |：分隔符是 '-' 重复 width 次生成，而 width 被固定为 3（第 1320-1325 行 的注释说明：3 是 Markdown 解析器能渲染单元格的最小宽度，此前按内容自适应宽度在长文本下会产出不可读的 Markdown）；
3. 数据行清洗：单元格内的换行会被替换成 <br>（第 1310-1315 行），字面 | 字符会被转义为 \|（第 1317-1318 行），最后统一右填充到 3 字符宽——所以 one、two 等恰好 3 字符的内容原样出现；
4. 首尾空行修剪：enexXmlToMd 收尾时调用 postProcessMarkdown()，削掉结果首尾的空行并规范空格。其注释明确指出这是为了让输出"更确定、便于单元测试"——这也解释了为什么期望文件 .md 可以逐字符比对而不必容忍空白差异。

设计权衡：扁平化嵌套表格与"保数据"原则

这一容错思路还延伸到嵌套表格。Markdown 不支持表格套表格，而整页剪藏来的网页 HTML 里这非常常见。转换器的策略（drawTable 上方的设计注释）是：凡包含子表格的外层表格一律"扁平化"为普通文本行渲染（tableHasSubTables() 判定，见 第 1212-1229 行），只有最内层、不含嵌套表格的表格才渲染成真正的 Markdown 表格（嵌套部分通过 第 1277-1306 行 的递归 drawTable 调用插入）。因为外层表格通常承担布局职能，内层才是内容。

把三处机制合起来看，本用例验证的其实是一条完整的容错链：

环节	机制	源码位置
解析	非严格 SAX；tr/td/caption 出现在错误位置时告警但不丢节点	import-enex-md-gen.ts
解析	table/tr/tbody 内空白文本直接丢弃	import-enex-md-gen.ts
渲染	table.lines 中的字符串碎片（空 <div> 等）被跳过	import-enex-md-gen.ts
渲染	无 <th> 时自动补空表头与 3 连字符分隔行	import-enex-md-gen.ts
测试	全量扫描 .html 并逐字符比对 .md 期望输出	import-enex-md-gen.test.ts

如何本地验证

该用例是自动化测试的一部分，无需手工操作数据。在仓库的 packages/lib 包中运行其 jest 测试套件（配置文件为 packages/lib/jest.config.js），import-enex-md-gen 用例会遍历 enex_to_md 目录，把包括 table_with_invalid_content.html 在内的所有 HTML 样本转成 Markdown，并与各自的 .md 期望文件比对。若你修改了 drawTable 的任何行为（例如单元格宽度、空表头补全规则），这个 4 行的期望文件会立刻暴露差异，失败信息还会按行打印实际值与期望值的对照，方便定位。

小结

table_with_invalid_content.md 这 4 行期望输出，浓缩了 Joplin ENEX 导入器对"脏表格"的完整处理契约：非法容器标签被解析与渲染双层忽略，有效单元格数据无损保留，缺失的表头按 Markdown 规范自动补齐，输出经过确定化修剪后接受逐字符测试。这套「保数据、弃结构噪声、结果可测试」的做法，也适用于理解同目录下其他表格与列表用例背后的实现。