RichTextEditorToolbar 组件契约¶
{
"paths": [
"packages/richtext/src/internal/ToolbarLinkPopover.tsx",
"packages/richtext/src/linkForm.tsx"
]
}
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 除 spec:AST-061 之外无其他;本记录拥有链接控件的交互。 |
| 行为 | 编辑器中的 Link 按钮或 Cmd/Ctrl+K 会打开一个附加在 Link 按钮上的非模态弹出层,其中包含一个 URL 字段以及 Apply、Remove(在链接内时)和 Cancel。 |
| 最终用户影响 | 用户可以在不遮挡所链接文本的模态对话框的情况下添加或编辑链接,并保持位置:当弹出层关闭时,焦点和选区返回编辑器。 |
| 构建器影响 | 无。promptForUrl 仍然会替换内置弹出层。 |
| 兼容性/就绪状态 | 链接 UI 是非模态弹出层,而非模态对话框;无 prop 变更。 |
| 审查检查 | 拒绝模态链接界面、关闭后使焦点或选区停留在编辑器之外的弹出层、为表单按钮新增的 richtext:* 图标键,以及脱离其按钮的弹出层。 |
| 治理规则 | spec:AST-061;spec:AST-087 FR11;architecture:icon-resolution-and-component-slots INV10。 |
此表是审查投影;以下正文具有权威性。
意图¶
RichTextEditorToolbar 是 RichTextEditor 的格式工具栏。本记录拥有其链接控件:用户如何从工具栏中添加、编辑和移除链接。工具栏的其余部分遵循 spec:AST-061。
消费者语法和示例属于 RichTextEditor.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
no— 链接控件打开的是弹出层而非对话框。 - 兼容性类别:交互变更,无 prop、默认值或 API 变更。
- 受控/非受控行为:不变。
- 迁移决策:DEC-1。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 链接弹出层:何时打开、其位置、其表单,以及关闭时焦点和选区的去向。
不拥有 / 非目标 {#does-not-own--non-goals}
- 工具栏的 props — 由
spec:AST-061拥有。 - 链接 URL 清理 — 由
@astryxdesign/richtext中的sanitizeUrl拥有。 - 在文本选区处的锚定 — Core Popover 仅锚定到按钮。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 链接弹出层 | closed、adding、editing | 链接表单是否显示,以及是针对新链接还是当前选区所在的链接。 | 可编辑且带有 Link 按钮的编辑器 | closed | component:RichTextEditorToolbar |
稳定 | 被拒绝的 URL 会让表单保持打开并显示错误。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 工具栏的链接控件会打开一个锚定在 Link 按钮上的非模态弹出层,而不是对话框;该弹出层包含 URL 字段和 Apply/Cancel,并且在 Enter、Escape 或 Cancel 时焦点和选区返回编辑器中的链接处。选区位于链接内时,弹出层还包含 Remove。 | 所有者决策,2026 年 11 月 6 日(Cindy)(DEC-1) |
| FR2 | 弹出层在工具栏上方打开,仅当上方没有空间时才翻转到下方,以免遮挡编辑器的前几行。 | 设计决策(Ernest,设计负责人)(DD1) |
| FR3 | 编辑器中的 Cmd/Ctrl+K 会打开同一个弹出层。它首先让 Link 按钮在页面中以及工具栏行内进入视图,以便弹出层在其旁边打开。 | 当前行为 |
| FR4 | Apply 和 Cancel 绘制共享的 check 和 close 图标,因此主题可通过 icons 重新设置它们的样式。Remove 绘制固定的组件图形。表单不会添加 richtext:* 图标键。 |
spec:AST-087 FR11;architecture:icon-resolution-and-component-slots INV10 |
| FR5 | 弹出层宽度最多为 320 px,且不会超过视口两侧的留白,因此在手机宽度下,字段及其按钮仍能在一行内显示于屏幕中。 | 当前行为 |
| FR6 | URL 字段初始为空,并带有 example.com 占位符;它会要求触摸屏调出 URL 键盘,不进行拼写检查,并在弹出层打开时获得焦点。无法被链接的 URL 会在字段下方显示错误,并将焦点保持在该字段上。 |
当前行为 |
无障碍契约¶
- AR1 — Link 按钮为其弹出层命名。 它带有
aria-haspopup="dialog"和aria-expanded,并控制该弹出层;弹出层是一个带标签的非模态对话框(“插入链接”或“编辑链接”),位于工具栏的漫游 Tab 停靠点之外,因此 Tab 键可以在表单中移动。
设计关系¶
设计决策¶
| ID | 决策 | 意图或理由 | 适用范围 | 允许的变体 |
|---|---|---|---|---|
| DD1 | 链接弹出层在工具栏上方打开。 | 被链接的文字通常位于编辑器的前几行,正好在工具栏下方。 | Link 弹出层 | 当上方没有空间时翻转到下方。 |
家族与系统关系¶
spec:AST-061拥有工具栏的 props;本记录拥有链接控件的交互。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | RichTextEditorToolbarLink.test.tsx 中的弹出层、Enter、Escape、Cancel、编辑和 Remove 用例;RichTextEditorToolbar.a11y.chromium.spec.ts |
添加、编辑、被拒绝的 URL | 出现模态表面,或焦点/选区离开编辑器,则视为失败。 | — |
| FR3 | RichTextEditorToolbarLink.test.tsx 中的 Cmd/Ctrl+K 用例 |
按钮在视图中、按钮已滚出视图 | 未将按钮滚入视图即打开弹出层,则视为失败。 | — |
| FR4 | RichTextEditorToolbarLink.test.tsx 中的共享图标用例 |
默认图标、已注册的 check/close |
新增 richtext:* 键,或 Apply 和 Cancel 忽略共享图标,则视为失败。 |
— |
| FR6 | RichTextEditorToolbarLink.test.tsx 中的字段与被拒绝 URL 用例 |
为空、被拒绝 | 缺少原生提示,或 URL 被拒绝时焦点离开字段,则视为失败。 | — |
| FR2, FR5 | 证据缺口:没有自动化测试断言位置或宽度;桌面端和 390 px 宽度的真实浏览器截图为其提供支持。 | 桌面端、手机宽度 | — | — |
决策日志¶
DEC-1 — 链接控件在其 Link 按钮上打开弹出层¶
参考: component:RichTextEditorToolbar/DEC-1
决策者: cixzhang,2026-11-06
添加链接的用户可以在视图中看到其正在链接的文字:链接表单是一个附加在 Link 按钮上的小型非模态弹出层,而不是模态对话框。
已否决的方案:在精细指针设备上使用弹出层,在手机上使用对话框或 bottom sheet。
未决问题¶
无。
内容边界¶
本文件不会重复使用方的 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则;它会链接到这些内容的所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx