Biome Markdown 格式化器如何处理 CJK 文本:splitCjkText 测试与 Prettier 兼容性解析
Biome Markdown 格式化器如何处理 CJK 文本:splitCjkText 测试与 Prettier 兼容性解析
Biome 在其 Markdown 格式化器中引入了与 Prettier 兼容的测试套件,其中 splitCjkText 目录专门用于覆盖中日韩(CJK)文本的换行与排版行为。本文以 space.md 为切入点,结合同目录测试用例、忽略清单与格式化快照,剖析 Biome 对 CJK 文本的实际处理策略、与 Prettier 的差异,以及底层段落格式化实现。读完本文,你将理解 Biome 为何刻意忽略 Prettier 的 "splitCjkText" 特性,以及如何通过快照机制验证 CJK 文档的格式化结果。
splitCjkText 目录:Prettier 兼容性测试中的 CJK 特例
splitCjkText 位于 Biome Markdown 格式化器的 Prettier 兼容性测试目录下,完整的相对路径是 crates/biome_markdown_formatter/tests/specs/prettier/markdown/splitCjkText。该目录共包含 7 个测试输入文件:
| 文件名 | 覆盖场景 |
|---|---|
space.md |
含空格的超长中英混合段落 |
mixed.md |
无空格的中英混排长段落 |
chinese-japanese.md |
中文、日文(含假名、浊点)与全形空白 |
korean.md |
韩文与英文混排、人名列表 |
han-kana-alnum.md |
汉字、假名与字母数字交替的长文本 |
link.md |
含参考式链接定义的长中文段落 |
symbolSpaceNewLine.md |
中日标点、括号、引用符号与换行 |
这些用例的共同特征是:文本长度远超格式化器默认行宽(80 字符),且包含 CJK 字符与拉丁字符的混排。它们最初是 Prettier 自身的测试用例,Biome 将其引入仓库用于对照验证。
space.md:一个超长中英混合段落的输入
关联文档 space.md 的全部内容仅有一行(外加一个尾部换行),是一个典型的"超宽 CJK 段落":
這是一個 English 混合著中文的一段 Paragraph!這是一個 English 混合著中文的一段 Paragraph!…(反复 16 次)
这行文本在技术上有三个值得注意的特征:
- 中英混排且带空格:中文与英文单词之间用半角空格分隔,这是中文技术写作中的常见排版方式;
- 单行超宽:整体长度远超 80 字符的行宽上限,构成格式化器的换行压力测试;
- 重复句式:同一句式重复 16 次,确保无论在哪里断行,输出都应当保持一致、幂等。
在 Prettier 中,这类文本会被 splitCjkText 特性处理——即把 CJK 字符当作可与拉丁字符互相断行的"软换行点",从而把超长段落拆成多行。Biome 对该特性的处理策略则不同,详见下文。
同目录用例:CJK 排版的典型难题
为了让读者理解 splitCjkText 要解决的问题域,这里展开几个代表性用例:
mixed.md:无空格的中英混排
mixed.md 与 space.md 形成对照——同样是"這是一個English混合著中文的一段Paragraph"的超长重复段落,但中英文之间没有空格。这种写法在中文内容中同样常见(如"MarkdownフォーマッターPrettierはサイコー"),对依赖空格断行的英文换行算法是直接挑战。
chinese-japanese.md:全形空白与日文浊点
chinese-japanese.md 覆盖了三类 CJK 排版细节:
- 全形空白:
全 形 空白中嵌入的全角空格(U+3000); - 日文浊点/半浊点:
カ゚キ゚ク゚ケ゚コ゚でガギグゴ(组合用记号 U+3099/U+309A); - 日文历史假名:
ワ゛、ヰ゛、ヱ゛、ヲ゛等罕见写法。
korean.md:韩英混排与字符级断行
korean.md 展示了韩文的特殊性:韩文音节(如 예문)与英文单词(如 Latin)混排时,韩文按音节单位天然可断行,且用例中包含大量人名枚举(李承晩 과 許政 과 …),用于验证 CJK 字符间是否允许断行。
symbolSpaceNewLine.md:禁则处理(kinsoku)
symbolSpaceNewLine.md 是排版难度最高的用例,涉及东亚排版中的禁则处理(kinsoku shori):
- 行首禁则:句号(
。)、逗号(、)、闭引号(」)等标点不应出现在行首; - 行尾禁则:开引号(
「)、开括号(()不应出现在行尾; - 参考式链接定义
[ウィキペディア]: https://ja.wikipedia.org/的断行行为。
Biome 的明确选择:忽略 splitCjkText 特性
一个关键事实是:Biome 刻意忽略了 整个 splitCjkText 目录。证据在 prettier_ignored_tests 文件中,其中有一行明确注释:
# CJK text splitting (Prettier-specific feature)
markdown/splitCjkText/
该清单文件还同时忽略了一大批 Prettier 扩展特性(如 wiki-link、footnote、math、front matter、删除线、内嵌语言格式化等),并说明:"忽略的文件不产生快照,并会被排除在兼容性报告之外。"
这意味着:
- splitCjkText 被定性为 "Prettier-specific feature"——即 Prettier 特有的、Biome 不打算复刻的行为;
- 这些测试文件不会生成
.snap快照,也不会进入格式兼容性差异统计。
Biome 的实际行为:不拆分 CJK 段落
虽然 splitCjkText 目录本身被忽略,但 Biome 对同类 CJK 段落的行为可以通过另一份快照直接观察:cjk.md.snap。该快照的输入 markdown/paragraph/cjk.md 与 space.md 高度同源,包含"這是一個English混合著中文的一段Paragraph"的超长段落、全形空白段落、CJK 引号、::: warning 容器、IVS(表意文字变体选择符)等。
快照揭示了 Biome 与 Prettier 的关键差异:
- Biome 不对超长 CJK 段落进行拆分:输入与输出中的 CJK 长段落完全一致,保持单行原样;
- Biome 保留全部原始间距:全形空白、半角空格均不被改动;
- Biome 会报告超宽行:快照末尾的 "Lines exceeding max width of 80 characters" 部分列出了第 1、3、5 行超出了 80 字符上限,其中就包括与
space.md相同的超长中英混合段落。
快照中的 Prettier 差异(diff)段落也印证了差异范围:两处 @@ 变更均来自有序列表(1.a / 2.b / 3.中 是否合并为一行),而所有 CJK 长段落文本在输入、输出中逐字一致——Biome 在 CJK 段落上保持原样输出。
这一设计取向可以概括为:Biome 的 Markdown 格式化器不会为了行宽而强行拆分 CJK 文本,而是尊重作者原始的断行与排版,仅把超宽问题作为可报告的诊断信息。
源码视角:段落如何被格式化
Biome 的 Markdown 段落格式化入口是 paragraph.rs(FormatMdParagraph 规则)。其核心逻辑:
is_suppressed:当段落包含注释后代节点时跳过格式化(保留原样);fmt_fields:将段落内容委托给FormatMdFormatInlineItemListOptions,并传入两个关键参数:print_mode: TextPrintMode::fill()——行内元素的填充打印模式,即"尽量放满一行,放不下再处理换行";text_context: TextContext::Neutral——段落所处的文档上下文(由标题、引用等位置决定)。
TextPrintMode::fill 是理解"不拆分 CJK"的关键:Markdown 行内内容被视为一组可以顺序打印的 token,格式化器按可用宽度填充。当 CJK 文本本身不包含可断行点(如空格)时,fill 模式不会像 Prettier 的 splitCjkText 那样在每个 CJK 字符之间制造断行机会。
此外,段落规则还支持 FormatMdParagraphOptions(trim_mode 与 text_context),供标题等外层结构在格式化段落时微调首尾空白与文本语境,例如 TextPrintMode 用于控制段落起始处的裁剪行为。
如何运行这些测试
splitCjkText 目录下的用例由 Biome Markdown 格式化器测试框架驱动。测试入口在 spec_tests.rs,通过 tests_macros::gen_tests! 宏扫描 tests/specs/markdown/**/*.md 并逐个执行 crate::spec_test::run。也就是说:
- 凡位于
tests/specs/markdown/下且未被 prettier_ignored_tests 排除的.md文件都会作为格式化输入参与测试; prettier/前缀的目录(如prettier/markdown/)是 Prettier 兼容性测试的镜像;- 由于
markdown/splitCjkText/在忽略清单中,该目录用例不产生快照,运行时会被跳过。
若要在本地复现 Biome 对 CJK 段落的真实输出,可以直接运行 cargo test -p biome_markdown_formatter,然后查看 tests/specs/markdown/paragraph/ 下 cjk.md 对应的快照(现有快照为 cjk.md.snap)。
小结
- Biome 引入了 Prettier 的
splitCjkText测试目录(含space.md等 7 个用例),但通过 prettier_ignored_tests 明确将其标记为 "Prettier-specific feature" 并整体忽略; - Biome 对超长 CJK 段落的策略是保持原样、不做字符级拆分,仅通过快照报告超宽行,这与 Prettier 主动在 CJK 字符间断行的行为形成鲜明对比;
- 段落格式化由 paragraph.rs 中的
FormatMdParagraph配合TextPrintMode::fill()实现,CJK 文本因缺少可断行点而保持单行; - 若你使用 Biome 格式化中文 Markdown 文档,可以预期:中英混排段落不会被自动拆行,超宽行需要通过手动断行或调整原始排版来解决。