Prettier Markdown 段落中的 CJK 格式化以 cjk.md 测试用例解析中文字符排版规则【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier本篇文章以 Prettier 仓库中的格式化测试用例 tests/format/markdown/paragraph/cjk.md 为核心深入讲解 Prettier 在处理包含中文、日文、韩文等 CJK 字符的 Markdown 段落时的行为包括proseWrap三种模式的差异、换行与空白的转换规则、全角空格与 CJK 标点的特殊处理以及底层源码字符分类与空白决策逻辑是如何支撑这些行为的。读完本文你将能够准确预判 Prettier 对中文 Markdown 文档的排版结果并学会用proseWrap配置获得想要的行宽折行效果。一、cjk.md 是什么一个专测 CJK 段落的格式化用例在 Prettier 仓库中tests/format/markdown/paragraph 目录集中存放 Markdown 段落paragraph相关的格式化测试其中 cjk.md 专门用于覆盖中文、日文、韩文CJK与西文混排时的各种边界情况。文件本身并不含配置或说明文字而是由一行行精心设计的输入样本组成配合同目录下的 format.test.js 驱动快照测试。format.test.js 的源码只有三行却一次性覆盖了proseWrap的全部取值runFormatTest(import.meta, [markdown], { proseWrap: always }); runFormatTest(import.meta, [markdown], { proseWrap: never }); runFormatTest(import.meta, [markdown], { proseWrap: preserve });也就是说cjk.md中的每一段文本都会在always、never、preserve三种模式下各格式化一次并与snapshots/format.test.js.snap 中的期望输出做比对。你可以通过yarn test见根目录 package.json 的test脚本运行全部测试或仅运行该用例验证行为。cjk.md一共覆盖了七类典型场景下文逐一拆解。二、逐场景解析cjk.md 覆盖的七类 CJK 排版问题1. 纯中文长段落CJK 字符之间的换行不产生空格cjk.md第 1 行是一段不含任何标点和空格的繁体中文长句這是一段很長…的段落。在快照中可以看到无论proseWrap取何值输出都与输入完全一致——因为中日文不使用空格分词CJK 字符之间换行后不应被替换成空格Prettier 也不会强行在超长 CJK 段落中插入空格来折行。2. 中英混排按句子整体统计 CJK 空格风格第 3 行是中文 English 中文的长段落以分隔多个短句。这是最容易受proseWrap影响的场景当段落以always模式重排且超过printWidth默认 80快照头部有printWidth: 80 (default)标注时Prettier 需要决定折行处用空格还是直接断开。这里用到的是整句风格推断策略Prettier 会统计该句子里 CJK 与拉丁字符之间已有空格的数量若有空格占多数则换行可转换为空格否则换行直接删除。对应源码实现为 src/language-markdown/print/whitespace.js 中的isInSentenceWithCJSpaces——它遍历句子的相邻节点对中文—西文西文—中文边界上的空白 或分别计数并缓存结果到sentenceNode.usesCJSpaces。3. 全角空格U3000不允许出现在词边界第 5 行全 形 空白…使用了大量全角空格U3000。源码在 src/language-markdown/utilities.js 的appendNode中明确disallow leading/trailing full-width whitespace即相邻词首尾若含\u3000则不插入空白节点同时 src/language-markdown/constants.evaluate.js 的PUNCTUATION_REGEXP也把 U3000 和 UFF5EWindows 上常用的 U301C 替代符并入标点集合。因此快照中该行三种模式下原样保留全角空格不会被当作可折行的普通空白处理。4. 英文段落中的 CJK 引号第 7、9 行分别测试英文句子中包含中文引号中文与中文的情况。行为与普通英文段落一致proseWrap: always时按 printWidth 折行此两行未超宽故保持原样never与preserve不折行。可见 CJK 引号被视为普通标点字符不影响整句的拉丁分词逻辑。5. 中文正文中的内联代码第 11 行扩展运算符spread是三个点...。包含中文括号、英文单词和反引号内联代码。快照显示三种模式下输出均不变。这是因为内联代码节点inlineCode属于INLINE_NODE_TYPES见 src/language-markdown/utilities.js且 src/language-markdown/print/whitespace.js 中的SINGLE_LINE_NODE_TYPES会阻止在其内部折行。6. 容器块::: warning 注意第 13–15 行是 Markdown 容器块container语法。有趣的是在always模式下快照输出变为::: warning 注意该网站在国外无法访问故以下演示无效 :::即容器块被折叠为单行。其原理同样在 src/language-markdown/print/whitespace.js 中lineBreakBetweenTheseAndCJConvertsToSpace集合包含 ASCII 标点:因此:::与中文之间的换行会被转换为空格源码注释中给出了:::\n句子句子句子\n::: → ::: 句子句子句子 :::的等价示例。而never与preserve模式则保持原始三行结构。7. IVS 变体选择符与汉字结构描述符第 17 行IVS 麻羽‼️包含 Unicode 变体选择符Variation Selectors第 19 行⿰あ⿱あ…是汉字结构描述符IDSIdeographic Description CharactersU2FF0–U2FFF。这些字符能否被识别为 CJK取决于 src/language-markdown/constants.evaluate.js 中构造的CJK_REGEXP它由cjk-regex全量字符集加上unicode-regex按Script_ExtensionsHan、Katakana、Hiragana、Hangul、Bopomofo与若干General_Category如Other_Symbol、Nonspacing_Mark筛选出的字符合并而成且允许紧跟一个变体选择符。快照中两行在三种模式下均原样保留说明 Prettier 能稳定地将它们当作不可拆分的 CJK 文本单元。8. 有序列表编号与中文内容的紧凑排布第 21–23 行1.a、2.b、3.中是一组有序列表。快照显示always与never模式都会把三项合并为1.a 2.b 3.中列表项之间用空格连接而preserve保持每项独立成行。这与纯文本段落的行为一致同时涉及列表项间的空白决策逻辑shouldPreventBreak见 src/language-markdown/print/whitespace.js它会识别、*、#、\d[).]等可能改变语法的前缀字符来避免错误合并。三、proseWrap 三模式行为速查结合 docs/options.md 的官方说明与cjk.md快照结果可以归纳如下模式CLI 覆盖默认/说明cjk.md 中的表现always--prose-wrap always将散文折行到printWidth拉丁文本按 80 列折行容器块:::折叠成单行CJK 与西文之间按整句风格决定空格never--prose-wrap never每个散文块保持单行依赖编辑器软折行所有段落保持一行含有序列表项合并依赖查看器软折行preserve--prose-wrap preserve默认值v1.9.0 起保持原文折行保留作者手写换行包括容器块三行结构与逐项列表官方文档特别提醒默认的preserve是为了兼容 GitHub 评论、BitBucket 等对换行敏感的渲染器因为这类服务中手写换行会被渲染为br若希望 Prettier 统一按printWidth折行则应显式设置为always。四、源码级原理Prettier 如何判断一个字符是中文CJK 相关排版行为由三层代码共同支撑这也是cjk.md测试价值的直接来源字符集定义层src/language-markdown/constants.evaluate.js 中的CJK_REGEXP定义了何为 CJK 字符——包含汉字、假名、谚文、注音等并允许后接变体选择符PUNCTUATION_REGEXP定义了 CJK 标点含 U3000、UFF5E 与 Unicode 七大标点类。分词层src/language-markdown/utilities.js 的splitText将段落文本拆成交替出现的word与whitespace节点并为每个词打上KIND_NON_CJK拉丁等、KIND_CJ_LETTER中/日、KIND_K_LETTER韩文、KIND_CJK_PUNCTUATIONCJK 标点四种标签。值得注意的设计是韩文谚文Hangul被归入KIND_K_LETTER并模拟拉丁词处理——因为韩文用空格分词而中日文不用src/language-markdown/utilities.js 中注释了这一点同时关联了 prettier issue #6516。换行决策层src/language-markdown/print/whitespace.js 的lineBreakCanBeConvertedToSpace决定\n能否变为空格。规则依次是非 CJK/韩文之间总是可转CJK 标点两侧与 CJK 字符之间不可转CJK 与 ASCII 标点如:::之间可转CJK 与西文之间则交给上文提到的isInSentenceWithCJSpaces按整句风格统计。对应地isBreakable 决定某处能否折行其中对value CJK 字符间无空白的情况一律禁止折行这解释了纯中文长段落为何永远不被重排。最后所有 word/whitespace 节点会进入 src/language-markdown/print/paragraph.js 的printParagraph通过fill文档结构在printWidth内完成最终折行排版。五、实践建议如何让 Prettier 正确处理中文 Markdown团队默认值若团队主要在编辑器/IDE 中阅读文档推荐.prettierrc中设置proseWrap: always让长段落统一折行到printWidth若使用 GitHub 等换行敏感平台保持默认preserve更安全。配合printWidthproseWrap: always的折行宽度由printWidth默认 80决定中文团队可根据实际需要调大如 100并在 prettier.config.js 或.prettierrc中统一配置。不要手动混用空格Prettier 会按整句统计决定 CJK 与西文之间是否加空格isInSentenceWithCJSpaces的计数逻辑因此同一段落内请保持风格一致否则格式化结果可能不符合预期。测试即文档若你维护自己的 Markdown 格式化链可直接参照 cjk.md 的七类样本构建回归用例并结合 format.test.js 的三模式矩阵验证换行、空白与标点行为。【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Prettier Markdown 段落中的 CJK 格式化：以 cjk.md 测试用例解析中文字符排版规则
Prettier Markdown 段落中的 CJK 格式化以 cjk.md 测试用例解析中文字符排版规则【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier本篇文章以 Prettier 仓库中的格式化测试用例 tests/format/markdown/paragraph/cjk.md 为核心深入讲解 Prettier 在处理包含中文、日文、韩文等 CJK 字符的 Markdown 段落时的行为包括proseWrap三种模式的差异、换行与空白的转换规则、全角空格与 CJK 标点的特殊处理以及底层源码字符分类与空白决策逻辑是如何支撑这些行为的。读完本文你将能够准确预判 Prettier 对中文 Markdown 文档的排版结果并学会用proseWrap配置获得想要的行宽折行效果。一、cjk.md 是什么一个专测 CJK 段落的格式化用例在 Prettier 仓库中tests/format/markdown/paragraph 目录集中存放 Markdown 段落paragraph相关的格式化测试其中 cjk.md 专门用于覆盖中文、日文、韩文CJK与西文混排时的各种边界情况。文件本身并不含配置或说明文字而是由一行行精心设计的输入样本组成配合同目录下的 format.test.js 驱动快照测试。format.test.js 的源码只有三行却一次性覆盖了proseWrap的全部取值runFormatTest(import.meta, [markdown], { proseWrap: always }); runFormatTest(import.meta, [markdown], { proseWrap: never }); runFormatTest(import.meta, [markdown], { proseWrap: preserve });也就是说cjk.md中的每一段文本都会在always、never、preserve三种模式下各格式化一次并与snapshots/format.test.js.snap 中的期望输出做比对。你可以通过yarn test见根目录 package.json 的test脚本运行全部测试或仅运行该用例验证行为。cjk.md一共覆盖了七类典型场景下文逐一拆解。二、逐场景解析cjk.md 覆盖的七类 CJK 排版问题1. 纯中文长段落CJK 字符之间的换行不产生空格cjk.md第 1 行是一段不含任何标点和空格的繁体中文长句這是一段很長…的段落。在快照中可以看到无论proseWrap取何值输出都与输入完全一致——因为中日文不使用空格分词CJK 字符之间换行后不应被替换成空格Prettier 也不会强行在超长 CJK 段落中插入空格来折行。2. 中英混排按句子整体统计 CJK 空格风格第 3 行是中文 English 中文的长段落以分隔多个短句。这是最容易受proseWrap影响的场景当段落以always模式重排且超过printWidth默认 80快照头部有printWidth: 80 (default)标注时Prettier 需要决定折行处用空格还是直接断开。这里用到的是整句风格推断策略Prettier 会统计该句子里 CJK 与拉丁字符之间已有空格的数量若有空格占多数则换行可转换为空格否则换行直接删除。对应源码实现为 src/language-markdown/print/whitespace.js 中的isInSentenceWithCJSpaces——它遍历句子的相邻节点对中文—西文西文—中文边界上的空白 或分别计数并缓存结果到sentenceNode.usesCJSpaces。3. 全角空格U3000不允许出现在词边界第 5 行全 形 空白…使用了大量全角空格U3000。源码在 src/language-markdown/utilities.js 的appendNode中明确disallow leading/trailing full-width whitespace即相邻词首尾若含\u3000则不插入空白节点同时 src/language-markdown/constants.evaluate.js 的PUNCTUATION_REGEXP也把 U3000 和 UFF5EWindows 上常用的 U301C 替代符并入标点集合。因此快照中该行三种模式下原样保留全角空格不会被当作可折行的普通空白处理。4. 英文段落中的 CJK 引号第 7、9 行分别测试英文句子中包含中文引号中文与中文的情况。行为与普通英文段落一致proseWrap: always时按 printWidth 折行此两行未超宽故保持原样never与preserve不折行。可见 CJK 引号被视为普通标点字符不影响整句的拉丁分词逻辑。5. 中文正文中的内联代码第 11 行扩展运算符spread是三个点...。包含中文括号、英文单词和反引号内联代码。快照显示三种模式下输出均不变。这是因为内联代码节点inlineCode属于INLINE_NODE_TYPES见 src/language-markdown/utilities.js且 src/language-markdown/print/whitespace.js 中的SINGLE_LINE_NODE_TYPES会阻止在其内部折行。6. 容器块::: warning 注意第 13–15 行是 Markdown 容器块container语法。有趣的是在always模式下快照输出变为::: warning 注意该网站在国外无法访问故以下演示无效 :::即容器块被折叠为单行。其原理同样在 src/language-markdown/print/whitespace.js 中lineBreakBetweenTheseAndCJConvertsToSpace集合包含 ASCII 标点:因此:::与中文之间的换行会被转换为空格源码注释中给出了:::\n句子句子句子\n::: → ::: 句子句子句子 :::的等价示例。而never与preserve模式则保持原始三行结构。7. IVS 变体选择符与汉字结构描述符第 17 行IVS 麻羽‼️包含 Unicode 变体选择符Variation Selectors第 19 行⿰あ⿱あ…是汉字结构描述符IDSIdeographic Description CharactersU2FF0–U2FFF。这些字符能否被识别为 CJK取决于 src/language-markdown/constants.evaluate.js 中构造的CJK_REGEXP它由cjk-regex全量字符集加上unicode-regex按Script_ExtensionsHan、Katakana、Hiragana、Hangul、Bopomofo与若干General_Category如Other_Symbol、Nonspacing_Mark筛选出的字符合并而成且允许紧跟一个变体选择符。快照中两行在三种模式下均原样保留说明 Prettier 能稳定地将它们当作不可拆分的 CJK 文本单元。8. 有序列表编号与中文内容的紧凑排布第 21–23 行1.a、2.b、3.中是一组有序列表。快照显示always与never模式都会把三项合并为1.a 2.b 3.中列表项之间用空格连接而preserve保持每项独立成行。这与纯文本段落的行为一致同时涉及列表项间的空白决策逻辑shouldPreventBreak见 src/language-markdown/print/whitespace.js它会识别、*、#、\d[).]等可能改变语法的前缀字符来避免错误合并。三、proseWrap 三模式行为速查结合 docs/options.md 的官方说明与cjk.md快照结果可以归纳如下模式CLI 覆盖默认/说明cjk.md 中的表现always--prose-wrap always将散文折行到printWidth拉丁文本按 80 列折行容器块:::折叠成单行CJK 与西文之间按整句风格决定空格never--prose-wrap never每个散文块保持单行依赖编辑器软折行所有段落保持一行含有序列表项合并依赖查看器软折行preserve--prose-wrap preserve默认值v1.9.0 起保持原文折行保留作者手写换行包括容器块三行结构与逐项列表官方文档特别提醒默认的preserve是为了兼容 GitHub 评论、BitBucket 等对换行敏感的渲染器因为这类服务中手写换行会被渲染为br若希望 Prettier 统一按printWidth折行则应显式设置为always。四、源码级原理Prettier 如何判断一个字符是中文CJK 相关排版行为由三层代码共同支撑这也是cjk.md测试价值的直接来源字符集定义层src/language-markdown/constants.evaluate.js 中的CJK_REGEXP定义了何为 CJK 字符——包含汉字、假名、谚文、注音等并允许后接变体选择符PUNCTUATION_REGEXP定义了 CJK 标点含 U3000、UFF5E 与 Unicode 七大标点类。分词层src/language-markdown/utilities.js 的splitText将段落文本拆成交替出现的word与whitespace节点并为每个词打上KIND_NON_CJK拉丁等、KIND_CJ_LETTER中/日、KIND_K_LETTER韩文、KIND_CJK_PUNCTUATIONCJK 标点四种标签。值得注意的设计是韩文谚文Hangul被归入KIND_K_LETTER并模拟拉丁词处理——因为韩文用空格分词而中日文不用src/language-markdown/utilities.js 中注释了这一点同时关联了 prettier issue #6516。换行决策层src/language-markdown/print/whitespace.js 的lineBreakCanBeConvertedToSpace决定\n能否变为空格。规则依次是非 CJK/韩文之间总是可转CJK 标点两侧与 CJK 字符之间不可转CJK 与 ASCII 标点如:::之间可转CJK 与西文之间则交给上文提到的isInSentenceWithCJSpaces按整句风格统计。对应地isBreakable 决定某处能否折行其中对value CJK 字符间无空白的情况一律禁止折行这解释了纯中文长段落为何永远不被重排。最后所有 word/whitespace 节点会进入 src/language-markdown/print/paragraph.js 的printParagraph通过fill文档结构在printWidth内完成最终折行排版。五、实践建议如何让 Prettier 正确处理中文 Markdown团队默认值若团队主要在编辑器/IDE 中阅读文档推荐.prettierrc中设置proseWrap: always让长段落统一折行到printWidth若使用 GitHub 等换行敏感平台保持默认preserve更安全。配合printWidthproseWrap: always的折行宽度由printWidth默认 80决定中文团队可根据实际需要调大如 100并在 prettier.config.js 或.prettierrc中统一配置。不要手动混用空格Prettier 会按整句统计决定 CJK 与西文之间是否加空格isInSentenceWithCJSpaces的计数逻辑因此同一段落内请保持风格一致否则格式化结果可能不符合预期。测试即文档若你维护自己的 Markdown 格式化链可直接参照 cjk.md 的七类样本构建回归用例并结合 format.test.js 的三模式矩阵验证换行、空白与标点行为。【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考