Markdown 文档界面一致性系统规范¶
意图¶
当核心 Markdown 与富文本界面 RichTextEditor、RichTextView 显示同一份 Markdown 文档时,用户看到的是同一份文档:每个界面上都具有相同的排版、块间距、行长、结构和方向。当产品在原位在该文档的阅读与编辑之间切换时,切换不会使任何块相对于其他块移动,也不会重排任何行;只有编辑辅助元素出现或消失。
非目标¶
- 字节级相同的 DOM。当渲染结果及其语义匹配时,每个界面保留自己的标记。
- Markdown 方言本身,以及 RichText 如何导入和导出 Markdown 源码。本记录管辖的是受支持的构造在渲染后呈现为何种形态、表达何种含义,而非哪些源码文本产生它或源码如何往返转换。唯一的例外是 DEC-5 共享的字符引用解码器。
- Markdown 插件与编辑器之间的协作、持久化、文档托管和插件适配器。
- 产品选择哪种编辑器引擎来编辑整个文档,以及产品存储的值。本记录管辖的是各界面如何渲染同一文档;RichText 自身的角色和值是 DEC-7。
- RichText 的发布渠道。包发布渠道元数据决定它(spec:AST-033 FR4),提升遵循 spec:AST-017 FR23;本记录不涉及。
- 只要满足本契约,等效的内部实现仍然有效,但字符引用解码器除外,DEC-5 使其成为唯一共享的公共函数。
要求¶
- FR1 — 由同一契约决定,而非任一渲染器。 当
Markdown与 RichText 界面针对相同的受支持内容存在分歧时,CommonMark 语义决定含义,共享的字体尺度、间距和颜色令牌决定呈现。任一界面当前的输出都不是参考基准:不一致之处按契约判定错误的一方修复,该方可能是Markdown。 - FR2 — 相同的排版。 正文文本使用
--text-body-size和--text-body-leading;标题级别 N 对 1–6 级使用--text-heading-N-size、--text-heading-N-weight和--text-heading-N-leading及标题字体族。加粗文本使用--font-weight-semibold。行内代码在所有界面上使用相同的 chip 尺寸、字体族和内边距。 - FR3 — 相同的块间距。 块之间按每个密度对应的一张间距表分隔。默认密度:标题 1–3 前
--spacing-6、后--spacing-3;标题 4–6 前--spacing-4、后--spacing-2;段落和列表两侧均为--spacing-3;围栏代码、块引用和表格为--spacing-4;主题分隔线为--spacing-6。紧凑密度使用同一张表的紧凑列。第一个块的前缘外边距和最后一个块的后缘外边距为零。 - FR4 — 相同的行长。 散文块在所有界面上限制在相同的内容宽度内,默认为
680px,而宽块(围栏代码、表格)跨越可用宽度。作者设置了列宽的 RichText 表格会在RichTextEditor和RichTextView中保持这些列宽(spec:AST-106/DEC-3)。 - FR5 — 相同的结构。 段落的软换行合并为一行流动文本;硬换行则断开。块引用的各行延续为同一段落。有序和无序列表按 CommonMark 缩进嵌套,每个项目显示一个标记,标记样式对应其深度(DEC-6)。无序列表在每个嵌套层级保留相同的主题化内缩。在每个列表内,方向相同的同级项目共享同一条 inline-start 行;与同级项目方向相反的项目从对侧边缘开始,如 FR6 所要求。嵌套在这些项目下方的列表以项目自身的行作为锚点;编号列表的内缩遵循 FR11。任务列表项、围栏代码、表格和主题分隔线以相应结构呈现,绝不以其字面源码呈现。围栏代码在每个界面上对长行换行;代码行永不横向滚动或裁剪(DEC-9)。
- FR6 — 方向跟随承载它的文本。 散文块——段落、标题、引用或列表项——在每个界面上(
Markdown、RichTextEditor和RichTextView)按自身文本的方向排版,且在任何嵌套深度都如此。文本中没有强方向字符的块采用外层国际化提供者的方向,这涵盖空块、数字、标点和图像。
包含多个块的散文块——引用或包含多个段落的列表项——其方向取自其下全部文本中的第一个强方向字符,内部的每个块也以同样方式取自身方向。
容器不是散文,无论容纳什么内容都采用父级的方向:顶层采用提供者的方向,嵌套时采用其包装项的方向。列表以此方向排列标记和内缩,表格以此方向读列,围栏代码块以此方向框住各行,每一行再从该行的第一个强字符取自身方向。
表格单元格是容器,随表格排序,而单元格文本在每个界面上按自身方向阅读。界面将该文本包在块中时由块承载方向,未包时由单元格承载,因此同一单元格在三种界面上阅读方式相同。
方向决定块的对齐方式、逻辑内缩以及光标的移动方向。若界面从提供者获取这些信息,而块文本以相反方向排布,则会把从右到左段落的光标放在错误的边缘,并使其与箭头键方向相反地移动。
- FR7 — 相同的语义。 加粗、斜体、删除线、行内代码和链接在每个界面上暴露相同的元素语义。链接的目标绝不包含其标题;标题作为链接的 title 暴露。文本中的命名和数字字符引用(如
©和©)在每个界面上渲染为它们所指称的字符;在行内代码和围栏代码内部保持字面形式。每个界面都使用Markdown导出的那一个解码器(DEC-5)来解码它们。 - FR8 — 相同的代码块框架。 围栏代码块在阅读和编辑模式下以相同高度显示相同的框架——其头部,或没有头部时的角部簇,语言标签和复制操作按
component:CodeBlockFR3 和 FR11 所规定的位置放置——因此切换不会移动代码。在编辑模式下,框架(头部或角部簇)位于可编辑文本之外:它不是文档的一部分,不能被编辑。 - FR9 — 原地阅读与编辑。 编辑模式可以添加光标、选区、占位符、焦点环、字段边框与内缩,以及工具栏。这些共同使整个文档偏移一个常量:在该偏移之后,每个块的顶部和高度与阅读模式的差异在 2 px 以内,且每个段落保持其行数。工具栏要么叠加在内容上,要么占据阅读模式同样保留的空间,因此偏移在编辑过程中不会改变。
- FR10 — 滚动位置在切换后保持。 在阅读与编辑之间切换前位于视图顶部的块,在切换后仍位于视图顶部,在 FR9 偏移范围内。
- FR11 — 编号列表内缩在列表内共享。 编号列表 MAY 将其标记空间从普通的主题化列表内缩加宽,以容纳该列表最宽的渲染计数器。方向相同的同级项目从同一条 inline-start 行开始其文本;单个计数器 MUST NOT 使其项目文本或嵌套其下的列表移位。计数器保持完整地在一行上,不裁剪、不截断、不与项目文本重叠。同一深度的不同列表在最宽计数器不同时 MAY 有不同的内缩;每个嵌套列表从父项文本起始处解析自身的内缩。此许可既不改变源码嵌套,也不改变 DEC-6 的编号和标记样式。它也不免除渲染器对等要求:对于相同的列表、主题、密度和可用行长,
Markdown与 RichText 界面保持匹配的文本起始和嵌套内缩,并且 FR9 的阅读/编辑几何和重排要求仍然成立。
平台支持¶
- 受支持的功能/引擎基线:仓库的浏览器支持矩阵。
- 不支持的行为:某个表面尚无法将构造渲染为结构时,该构造会以其字面源文本形式渲染;它永远不会被丢弃。
- 浏览器证据:共享一致性测试夹具在手机和桌面宽度、浅色和深色、从左到右和从右到左,以及一份长文档在中间位置从阅读模式切换为编辑模式时的真实浏览器块几何。
当前状态影响¶
Markdown 已为其自身输出渲染 FR2–FR4,以及除其相对边缘条款之外的 FR5;但 FR7 涉及链接标题和 FR7 涉及字符引用的情形除外。RichTextEditor 和 RichTextView 在其渲染的构造上受 FR2–FR11 约束;它们的默认编辑器主题遵循 FR2 和 FR3。实现缺口:Markdown 和 RichText 按提供者的方向布局每个块(FR6,以及 FR5 的相对边缘条款);editorTheme.ts 中 RichText 的 direction: inherit 覆盖是该缺口的一部分。围栏代码行在两个表面上都采用容器的方向,因此两者都尚未满足 FR6 的逐行规则。component:CodeBlock 保持代码块方向不变(FR9),并将行内排序交给平台文本引擎,因此消除这一缺口将同时改变该记录和这些表面。
@astryxdesign/core/Markdown/parser 和 @astryxdesign/core/Markdown 导出 decodeMarkdownCharacterReferences,即 RichText 表面所导入的 DEC-5 解码器。Markdown 在每个深度绘制圆点和十进制标记,RichText 将第二个无序列表级别绘制为圆点;两者都采用 DEC-6 标记循环。RichText 采用 DEC-8:其包入口停止导出 sharedEditorTheme、URL_MATCHER、EMAIL_MATCHER 和 Transformer;RichTextEditorToolbar 新增 BaseProps 和 ref,并将 linkOpensInNewTab 重命名为 hasNewTabLinks;其 Lexical 对等依赖范围升级到 Lexical 0.52 小版本。
Markdown 渲染围栏代码时不换行、横向滚动,并采用 FR5 的换行规则;RichText 已经对围栏代码换行。原地切换的产品通过将字段的 inset 和边框设置在阅读表面之外,使编辑器文本与阅读表面一样宽,如 RichTextEditor 文档所示;独立编辑器则保持其表单宽度。Markdown 通过 component:CodeBlock,以及 RichText 表面,都会在未声明语言的围栏代码之上浮动“复制”按钮;两者都采用 component:CodeBlock FR11 所放置的 FR8 角落控件组。
RichText 代码块使用 component:CodeBlock 的分词器着色,并且 RichTextEditor 和 RichTextView 采用与 Markdown 相同的 codeLanguages 列表(component:Markdown FR30),该列表是 component:CodeBlock 的语言模块(FR13)列表;与 Markdown 一样,它们用匹配到的值的 name(按原样显示的标识符,component:CodeBlock FR13)来标注围栏代码,因此阅读和编辑对相同的语言进行着色和标注,但以下情况除外:围栏的第一个词包含超出字母、数字和下划线范围的字符,例如 c++、c#、objective-c、rust,ignore 或 diff-ts:Markdown 按首词字符读取围栏(component:Markdown FR29),而 RichText 保留整个首词。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR2–FR4 | Markdown 和 RichText 上一致性测试夹具的真实浏览器计算样式和块几何 |
390px 和 1440px;浅色和深色;默认密度 | 恢复硬编码的标题尺寸或使用不同的块边距会使块移动超过 2px 并失败 |
| FR5 | 一致性测试夹具的真实浏览器结构和行数 | 2 空格和 3 空格缩进的嵌套列表;软换行;块引用延续 | 将嵌套列表展平,或将软换行变成换行,则失败 |
| FR6 | 每个块的真实浏览器计算方向、对齐方式和光标移动 | 从右到左的提供者搭配从左到右的文本,以及相反情况;混合文档;仅包含数字、标点或图像的块;条目双向阅读的嵌套列表;一个引用和一个列表项,其包含的段落以不同方向阅读;一个单元格双向阅读的表格 | 如果段落块或表格单元格的计算方向与其自身文本不一致,或中性块不跟随提供者,或列表、表格或围栏从其内容获取方向,则失败 |
| FR7 | 行内标记、链接和字符引用在每个界面上的语义 DOM | 带标题链接、裸链接、加粗、强调、删除线;文本和代码中的 &、©、© |
目标地址内部出现标题、用样式化 span 代替语义元素,或文本中含有未解码的引用,均失败 |
| FR7, DEC-5 | 通过 Markdown 渲染和 RichText 导入的共享一致性用例 |
命名、十进制和十六进制引用;未知名称;缺少分号;无效码点 | 出现第二个引用表,或解码器改变未知名称或未终止引用,均失败 |
| FR5, DEC-9 | 真实浏览器中的行盒,以及长行代码夹具在阅读和编辑两种界面上的水平溢出 | 390px 和 1440px;浅色和深色;从左到右和从右到左 | 代码块的滚动宽度超过其客户端宽度,或长行在一种模式下比另一种模式更高,均失败 |
| FR5, DEC-6 | 真实浏览器中两种界面上每个层级的标记样式 | 嵌套深度 0–8 层且类型混合的无序和有序列表;在 alpha 和 roman 深度下起始值为 0、−1、26、27、3999 和 4000;从右到左;浅色和深色 | 某一层级绘制了另一层级的标记,或一种界面与另一种界面不同,均失败 |
| FR5, FR11 | 真实浏览器中 Markdown 和 RichText 上的计数器行盒、同级文本起始位置和嵌套列表缩进 |
同一深度下的短计数器和宽计数器列表;十进制 9–10 和 99–100;alpha z–aa;roman vi–viii;相邻父列表的子列表具有不同的最宽计数器;手机/桌面;LTR/RTL;浅色/深色;阅读/编辑 | 计数器被拆分、裁剪或重叠,阅读方式相同的条目之间发生文本位移,嵌套列表锚点偏离其所属条目的文本起始行,或跨渲染器/阅读-编辑的缩进不匹配,均失败 |
| FR8 | 真实浏览器中两种模式下代码块头部的几何结构 | 带信息字符串的围栏代码;带语言的一行围栏;不带语言的长围栏 | 头部或角落控件组只出现在一种模式中,任一模式下出现覆盖代码的控件,或行在模式之间换行方式不同,均失败 |
| FR9–FR10 | 真实浏览器中一致性夹具和长文档的阅读/编辑切换 | 顶部为短文档;向下滚动一半处为长文档 | 逐块位移超出常量偏移,或锚点块离开视图顶部,均失败 |
决策日志¶
DEC-1 — Parity 是一个共享契约,而非 Markdown 的副本¶
参考: spec:AST-061/DEC-1
决策者: cixzhang,2026-10-06
读者会在同一文档的阅读和编辑界面之间切换,因此文档在两种界面上必须具有相同的外观和含义。该契约由 CommonMark 语义加上共享 token 组成,因为读者的预期正来源于这些。当 Markdown 是偏离这些的一方时,Markdown 需要改变。
已拒绝:将当前 Markdown 输出作为参照,因为这会将其缺陷复制到每个编辑器界面。
DEC-2 — 编辑辅助使文档偏移但绝不重排¶
参考: spec:AST-061/DEC-2
决策者: cixzhang, 2026-10-06
编辑器需要光标、工具栏和字段边框,因此编辑模式不可能与阅读模式逐像素相同。一个恒定的偏移量能保持读者的位置:每一行都保持在相对于其他行的原位置,滚动锚点停留在视图顶部。2 px 用于吸收不同渲染器之间的亚像素舍入;它不允许出现不同的间距值。
DEC-3 — 字符引用渲染为解码后的字符¶
参考: spec:AST-061/DEC-3
决策者: cixzhang, 2026-10-06
读者在一个界面看到 ©,在另一个界面看到 ©,那他看到的就是两个文档。CommonMark 将字符引用渲染为它们所表示的字符,因此两个界面都如此渲染;代码则完全显示输入时的内容。
DEC-4 — 阅读与编辑共用代码块头部¶
参考: spec:AST-061/DEC-4
决策者: cixzhang, 2026-10-06
语言标签在两种模式下都告诉读者代码所用的语言;如果头部只出现在其中一种模式,切换时就会使每一行代码移动。头部是文档周围的边框,而非文档内容本身,因此编辑永远不会触及它。
DEC-5 — 字符引用使用同一个解码器¶
参考: spec:AST-061/DEC-5
决策者: cixzhang, 2026-10-06
decodeMarkdownCharacterReferences(text) 从可在服务端安全使用的 @astryxdesign/core/Markdown/parser 子路径以及 @astryxdesign/core/Markdown 导出。它返回 text,其中每个有效的具名或数字字符引用都被替换为其所表示的字符;指向 NUL、代理项或超过 U+10FFFF 的码点的数字引用,按 CommonMark 的规定替换为 U+FFFD;未知名称、缺少分号的引用,以及其他所有文本,都保持原样。
它作用于纯文本,对 Markdown 一无所知:由每个调用方决定在哪里使用它,因此反斜杠转义和代码都保持字面原样。它也是 Markdown 自身渲染所使用的解码器:同一套实现、同一个私有于 Markdown 的具名引用表,因此各界面不会产生偏差。这是本记录在导入机制和等效内部实现方面的非目标中的唯一狭窄例外;其他所有内部实现仍保持自由,并且不导出任何通用 HTML 实体工具。
DEC-6 — 列表标记按深度循环¶
参考: spec:AST-061/DEC-6
决策者: cixzhang, 2026-10-06
列表的深度是包围它的列表数量,无论项目符号列表还是编号列表;顶层列表深度为 0。项目符号列表在其深度模 3 为 0、1 或 2 时,分别绘制实心圆点(disc)、空心圆(circle)或方块(square)标记;编号列表则按同样的方式将数字写成十进制(decimal)、小写字母(lower-alpha)或小写罗马数字(lower-roman)。该循环无限重复,因此每一层都与相邻层不同,读者在每个界面上都能辨别深度。编号保留列表的起始值,并统计相同的项目;变化的只是每个数字的书写方式。字母超过 z 后继续为 aa、ab,依此类推。超出其样式范围的数字——在 lower-alpha 或 lower-roman 下的零或负数(起始值为 0 或更低时会产生),或 lower-roman 下超过 3999 的数字——按 CSS 计数器样式的回退行为以十进制书写;起始值和项目保持原样。任务列表项显示复选框而不是标记。标记只是呈现:列表保持其列表语义,源代码不变。
DEC-7 — RichText 是一个表单字段编辑器,其值为 Lexical 编辑器状态¶
参考: spec:AST-061/DEC-7
决策者: cixzhang, 2026-10-14
RichTextEditor 是一个公开的表单字段编辑器:一个带标签的字段,用户可以在此写入格式化文本。它的值是序列化后的 Lexical EditorState JSON:defaultValue 接收该值,onChange 报告能够序列化为该值的编辑器状态,RichTextView 渲染该值。Markdown 是导入和导出格式,而不是值本身:markdownToEditorStateJSON 和 editorStateJSONToMarkdown 在两者之间转换,spec:AST-062 规定该转换返回的内容。RichText 不是文档宿主:协作、持久化和文档托管仍属于产品,产品通过编辑器周边或 plugins 来提供这些能力。RichText 提供 spec:AST-106 所允许的、可选的文档功能,每一项都通过 plugins 作为插件提供;当全部未启用时,它就是本决策所描述的表单字段。本记录仍然是 RichText 与 Markdown 共享的唯一视觉契约。
DEC-8 — RichText 的公开接口即 Lexical 的接口,并保持精简¶
参考: spec:AST-061/DEC-8
决策者: cixzhang, 2026-10-14
RichText 构建在 Lexical 之上,并且明确如此:nodes 和 transformers 接受 Lexical 类型,plugins 接受 Lexical React 插件,onChange(editorState, editor) 以及编辑器 ref 的 getEditorState() 返回 Lexical 类型,因此调用方可以直接用 Lexical 扩展编辑器。
该包只支持一个 Lexical 次版本,并在其 Lexical 对等依赖范围中声明;spec:AST-017 对该次版本的变更进行分类。该包只导出调用方构建所需的内容:生成的编辑器主题类、自动链接正则表达式,以及 Lexical Transformer 类型的再导出,都是内部实现;Transformer 来自 @lexical/markdown。
RichTextEditorToolbar 接受 BaseProps 和一个 ref,并将它们传递给其渲染的核心 Toolbar,后者按放置自身属性的方式放置它们:ref 和样式放在根元素上,其他基础 props 放在其 role="toolbar" 元素上。它用于在新标签页中打开链接的选项是 hasNewTabLinks。RichTextEditorAutoLinkPlugin 不渲染自身的元素,因此它不接受任何 BaseProps。
已否决:在 Lexical 的类型之上再提供 Astryx 文档、节点和插件类型,因为这会重复 Lexical 的扩展模型,而调用方毫无收益。
DEC-9 — 围栏代码换行¶
参考: spec:AST-061/DEC-9
决策者: cixzhang, 2026-10-14
在窄屏上,读者无需横向滚动就能看到完整的代码行;长行在阅读模式和编辑模式下占用相同高度,因此切换不会导致其下方的代码块移动(FR9)。换行只是呈现方式:代码文本、行号以及复制操作返回的内容都不变。 已否决:两个界面都横向滚动,因为在横向滚动区域内编辑会隐藏光标所在的上下文。
未决问题¶
- 无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx