跳转至

RichText 文档功能系统规范

意图

人们在使用 RichTextEditor 写作时,可以完成他们对写作界面所期望的文档操作:调整表格列宽、从键入的菜单中提及某人或插入块、就地修改链接、将链接显示为卡片、添加图片、编写公式、折叠长章节、格式化选区或在手机上格式化,以及移动块。产品通过将其插件传递给现有的 plugins prop 来启用这些功能中的每一项。当所有功能都未启用时,RichTextEditor 就是 spec:AST-061/DEC-7 所描述的表单字段。某项功能添加的内容在 RichTextView 中读取效果一致,并且只要 Markdown 能够表达,在核心 Markdown 中也一致。

非目标

  • 协作、持久化和文档托管。它们由产品负责(spec:AST-061/DEC-7)。
  • 功能背后的服务:提及可以指向谁、键入的菜单搜索什么、图片的字节存储在哪里、公式如何绘制。
  • 每个功能插件的具体选项、事件和视觉表现。本记录或所属组件规范中的决定会在该功能发布前确定下来。
  • Markdown 方言及其转换,由 spec:AST-062 负责。
  • 满足本契约的等效内部实现仍然有效。

需求

  • FR1 — 默认关闭。 某项功能在调用方传入其插件之前保持关闭。当所有功能都关闭时,RichTextEditor 和 RichTextView 在行为、存储和渲染方面与 spec:AST-061 和 spec:AST-062 所描述的一致。
  • FR2 — 值保持为编辑器状态。 功能添加的内容是调用方已经存储的序列化 Lexical 编辑器状态的一部分(spec:AST-061/DEC-7)。它持有的是产品在绘制内容时会解析的引用,例如提及指向的人或图片保存的位置,而绝不是产品需要查询的数据副本,例如人名或图片的字节(DEC-2)。
  • FR3 — 读者状态不进入值。 属于某位读者自己的状态,例如他们折叠的章节或最近选择的菜单项,仅对该读者保留。它永远不会进入编辑器值、其 Markdown 导出或其他读者的视图。
  • FR4 — 每项功能都说明其 Markdown 形式。 对于每个添加内容的功能,editorStateJSONToMarkdown 会写出最接近的 Markdown 形式,下表说明该形式丢弃了什么。未使用任何功能的文档导出与 spec:AST-062 的描述完全一致。
  • FR5 — 阅读时显示编辑时所显示的内容。 RichTextView 以只读编辑器的绘制方式绘制某项功能的内容,核心 Markdown 按照 spec:AST-061/FR1 绘制该内容的 Markdown 形式。
  • FR6 — 编辑界面不会重排文档。 功能在编辑时显示的菜单、弹出框、手柄或工具栏覆盖在文档之上,或占据阅读模式同样会预留的空间,因此启用该功能时 spec:AST-061/FR9 和 spec:AST-061/FR10 仍然成立。
  • FR7 — 键盘与辅助技术。 功能通过指针提供的每个操作也都有键盘路径,并且其状态对辅助技术可见。键入的菜单保持焦点在编辑器中,并遵循 WAI-ARIA combobox 模式;调整表格列宽有对应的键盘操作;折叠控件是一个暴露 aria-expanded 的按钮。
  • FR8 — 产品提供服务。 搜索、人员查找、上传和公式绘制由调用方以功能插件选项中的函数或渲染器形式提供。RichText 负责编辑交互及其无障碍性,并且自身不发起任何网络请求。
  • FR9 — 统一的屏幕键盘模型。 对手机屏幕键盘作出响应的功能会按照 spec:AST-099 的描述测量并避开它。
  • FR10 — 每项功能都是一个插件。 下表中的每项功能都作为一个 Lexical 插件提供,并附带它添加的任何 Lexical 节点;调用方通过 RichTextEditor 和 RichTextView 现有的 plugins 和 nodes props 传入这些插件(spec:AST-061/DEC-8)。两个组件都不会因任何功能而新增 prop(DEC-1)。

已纳入的功能:

功能 用户做什么 值保留什么 Markdown 形式
表格调整大小 拖动列或行边框,或使用键盘上的表格大小命令 列宽和行的最小高度 表格本身,不含其尺寸(DEC-3)
键入菜单 键入 @、/ 或 :,并从调用方来源中选择人员、块或表情符号 所选内容插入的内容 所插入内容自身的形式
链接弹出框 打开、编辑或移除光标处的链接;Cmd/Ctrl-点击可打开链接(DEC-4) 链接 链接
图片 粘贴、拖放或选择由调用方上传的图片,并在文本中移动它 来源、替代文本和尺寸 ![alt](src),不含尺寸
数学公式 键入行内或显示公式 公式源 核心 Markdown 的选择启用数学语法
可折叠标题 在阅读或编辑时折叠标题下的章节 无(FR3) 无
手机键盘工具栏 通过停靠在屏幕键盘上方的工具栏进行格式化 无 无
链接卡片 以卡片形式展示带有产品预览的链接,并可像处理链接一样对其进行编辑或移除(DEC-1) URL 纯链接
选区格式栏 在选区旁边显示的格式栏中格式化选中文本(DEC-1) 无 无新的 Markdown 形式
块移动 通过拖动块的句柄或使用键盘命令来移动块(DEC-1) 新的块顺序 重新排序后的内容

链接卡片、选区格式栏和块移动还包含以下内容:

  • 链接卡片。产品提供 URL 的预览(FR8),但值永远不会保留该预览(DEC-2)。当产品提供预览时,RichTextView 显示卡片,否则显示纯链接(FR5)。卡片可像链接一样通过键盘到达并操作,其预览文本也对辅助技术公开(FR7)。
  • 选区格式栏。格式栏上的每个控件都可以从选区通过键盘访问,并为辅助技术命名(FR7)。它不添加任何内容,因此 RichTextView 对此不显示任何内容。
  • 块移动。键盘命令进入 spec:AST-103 的重新排序模式,用于当前光标所在的块(其 FR4a start),因此重新排序模式是唯一无需拖拽的路径,并且每次移动都会向辅助技术播报(FR7)。句柄、键盘命令、播报和放置规则均遵循 spec:AST-103 可重新排序集合的规定。RichTextView 按移动后的顺序显示这些块(FR5)。

平台支持

  • 支持的功能/引擎基线:仓库的浏览器支持矩阵。
  • 不支持的行为:当浏览器缺少某项行为特性所需的功能时,该行为特性不可用,编辑器在缺少该特性时仍能正常工作。
  • 浏览器证据:对每项行为特性进行真实浏览器键盘和指针操作测试,以及在手机和桌面宽度下使用每项行为特性进行 spec:AST-061 阅读和编辑几何测试。

当前状态影响

  • spec:AST-061/DEC-7 指定本记录为 RichText 可选文档行为特性的所有者。
  • 当所有行为特性关闭时,现有行为保持不变(FR1)。
  • 每个行为特性插件发布时,RichTextEditor 和 RichTextView 的消费者文档会增加相应的用法说明;其属性表格不变(FR10)。

验证

契约 验证 代表性状态 变更或失败预期
FR1 spec:AST-061 的等价性测试夹具和 spec:AST-062 的测试语料库,全部关闭 默认编辑器和视图 默认开启的行为特性失败
FR2、FR3 每项行为特性的序列化状态测试 一条提及、一张图片、一个折叠的章节 存储的名称、图片字节或折叠状态失败
FR4 每项行为特性的导出测试 行为特性表格中的每一行 导出时丢失超出表格所规定内容的情况失败
FR5 每项行为特性的等价性测试夹具行 浅色和深色、从左到右和从右到左 以不同方式绘制内容的视图失败
FR6 在行为特性界面打开的情况下进行阅读和编辑几何测试 手机和桌面宽度 回流后的块失败
FR7 纯键盘操作测试和辅助功能树断言 打开的菜单、一次调整大小、一次折叠 只能通过指针访问的操作失败
FR8 使用调用方服务替换为假实现进行测试 慢速、失败和空的来源 RichText 发起的网络请求失败
FR9 在显示键盘栏的情况下进行 spec:AST-099 验证状态测试 屏幕键盘打开、调整大小和关闭 第二次键盘测量失败
DEC-1 rows 针对每个新增功能:导出测试、查看对等行,以及带有可访问性树断言的纯键盘运行 带预览和不带预览的链接卡片、选区上的格式栏、通过键盘和拖拽移动的块 存储的预览、键盘无法到达的栏控件,或仅拖拽的块移动失败
FR10 两个组件的详尽 props 列表测试,以及每个功能仅通过 plugins 和 nodes 挂载它的测试 每个功能开启,一次一个,也同时开启 为某个功能新增组件 prop 失败

决策日志

DEC-1 — 每个文档功能都是一个插件

Reference: spec:AST-106/DEC-1 决策者: cixzhang,2026-11-11

负责人选择:采用 AST-106,每个功能都作为一个插件。作者期望写作界面具备这些功能,而需要其中某个功能的产品,若没有该功能,就会构建自己的编辑器,并重新获得 RichText 已经提供的对等性和可访问性。每个功能的编辑交互都是通用的,而其数据和服务仍保留在产品侧,因此每个功能都属于 RichText。每个功能都作为插件,通过现有的 plugins 和 nodes props 提供,因此 RichText 的公共表面保持为 Lexical 的,并且保持精简(spec:AST-061/DEC-8);产品只采用它传入的那些功能。负责人所回答的问题还提到了链接卡片、选区格式栏和块移动,因此同样的选择也将它们作为插件功能,与其余功能一同接纳。

已拒绝:独立文档编辑器包,因为两个编辑器各自都要承担对等性契约。已拒绝:每个功能一个 prop,这会使 props 表增加约七个条目。已拒绝:一个分组配置 prop,这会在 plugins 旁边增加一个嵌套形状来完成同样的工作。

DEC-2 — 值保存的是引用,而非查找出来的数据

Reference: spec:AST-106/DEC-2 决策者: ernestt,2026-10-26

提及(mention)保存它所提到的对象,图片保存其存放位置;产品在每次绘制时解析它们。每个阅读者看到的都是当前数据,文档也永远不会携带其阅读者可能看不到的数据。

已拒绝:存储显示快照,因为它会过期,并且可能向看不到其来源的阅读者暴露数据。

DEC-3 — 表格尺寸存在于值中,而 Markdown 会丢弃它们

Reference: spec:AST-106/DEC-3 决策者: ernestt,2026-10-26

作者设置的宽度和高度是其创建的文档的一部分,因此编辑器的值会保留它们,编辑器和 RichTextView 会绘制它们。Markdown 表格无法容纳尺寸,因此导出时会写出不带尺寸的表格,核心 Markdown 会像布局任何表格一样对其布局。未设置尺寸的表格在每个界面上都按照 spec:AST-061/FR4 所述进行布局。

Reference: spec:AST-106/DEC-4 决策者: cixzhang,2026-11-11

当光标位于链接中时,链接弹出框会打开,无论光标是点击放入的,还是键盘移动过去的。Cmd/Ctrl-点击会在新标签页中打开链接。悬停链接不会打开任何内容,因此在书写过程中指针经过文本时,不会出现弹出窗口。

已拒绝:除了光标之外,还在悬停时打开。已拒绝:Cmd/Ctrl-点击仅放置光标。

未解决的问题

  • 无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx