DialogHeader 模块契约¶
意图¶
DialogHeader 展示对话框的标题区域及其可选的关闭控制。该记录拥有稳定的 header-row、start-content、title-block、end-content 和 close-icon 结构、它们的公共主题目标,以及应用于现有 end-content 槽位的固定补偿。
兼容性与迁移¶
- 发布默认值保留:
yes - 兼容性类别:两个新增主题目标和一个新增 prop;被省略的布局、绘制、交互、无障碍和主题保持不变
- 迁移决策:无
消费者迁移说明应放入消费者文档和发布说明中。
所有权边界¶
拥有
- 用于排列标题内容和控件的标题行。
- 用于可选前置内容的 start-content 包装器。
- 用于组合标题和可选副标题的标题块。
- 现有的 end-content 包装器,用于将可选尾部内容与关闭操作组合在一起。
- 由 medium 关闭操作的透明 inset 推导出的固定 end-slot 补偿。
- 为可选关闭操作渲染的关闭图标。
dialog-header、dialog-header-start-content、dialog-header-title-block、dialog-header-end-content和dialog-header-close-icon目标。
不拥有 / 非目标
- 对话框模态性、关闭策略或焦点生命周期 — 由
component:Dialog及其关联的系统记录拥有。 - 此模块之外的通用的 Button 或 Icon 呈现 — 由那些组件拥有。
- 列表式继承的容器内边距补偿、调用方提供的 margin 值,或通用对齐原语。
公共 API 与概念¶
本契约保留三个现有主题表面,新增两个内容槽位目标,并新增一个针对槽位的补偿覆盖项。
| 概念 | 封闭值或状态 | 含义 | 默认值 | 所有者 | 稳定性 |
|---|---|---|---|---|---|
| 标题行目标 | 存在 | 设置用于排列标题内容和控件的行的样式 | 现有行的视觉样式 | module:Dialog/DialogHeader |
稳定 |
| start-content 目标 | 当 start content 渲染时存在 | 设置可选前置内容包装器的样式 | 现有 start-content 布局 | module:Dialog/DialogHeader |
稳定 |
| 标题块目标 | 存在 | 设置标题/副标题分组元素的样式 | 现有标题堆叠视觉样式 | module:Dialog/DialogHeader |
稳定 |
| end-content 目标 | 当 end content 或关闭操作渲染时存在 | 设置将尾部内容与关闭操作组合在一起的包装器的样式 | 现有 end-content 布局 | module:Dialog/DialogHeader |
稳定 |
| 关闭图标目标 | 当关闭操作渲染时存在 | 设置关闭字形本身的样式 | 现有 medium Icon 视觉样式 | module:Dialog/DialogHeader |
稳定 |
endContentEdgeCompensation |
inline、block、all |
选择现有 end-content 包装器的哪些轴接收其固定补偿 | 省略;保留自动的关闭操作补偿 | module:Dialog/DialogHeader |
稳定 |
对于这个针对槽位的 prop,inline 表示槽位的逻辑内联结束边缘,block 表示两个块向边缘,all 将二者结合。
行为契约¶
| ID | 不变项 | 依据 | 审查状态 |
|---|---|---|---|
| FR1 | 标题行 MUST 在其应用行布局和间距的元素上携带 dialog-header。 |
当前实现与所有者决策 | 已定案 |
| FR2 | 标题块 MUST 在其应用标题/副标题布局和间距的元素上携带 dialog-header-title-block。 |
当前实现与所有者决策 | 已定案 |
| FR3 | 渲染出的关闭 Icon MUST 在其应用图标呈现的字形元素上携带 dialog-header-close-icon。 |
当前实现与所有者决策 | 已定案 |
| FR4 | 省略 onOpenChange MUST 继续省略关闭操作及其可选的 close-icon 结构。 |
已发布行为 | 已定案 |
| FR5 | 现有的结束包装器 MUST 继续将可选的 endContent 与可选的关闭操作组合在一起;此变更 MUST NOT 添加另一个包装器。 |
当前实现 | 已定 |
| FR6 | 当省略 endContentEdgeCompensation 时,无论是否存在 endContent,渲染关闭操作 MUST 保留已释放的固定负块与逻辑行内末端内边距。在没有关闭操作的情况下,不应用任何自动补偿。 |
已发布行为与负责人决策 | 已定 |
| FR7 | 显式的 inline MUST 仅应用逻辑行内末端补偿;block MUST 仅应用于两个块边缘;all MUST 同时应用两者。显式值会覆盖自动的关闭操作选择。 |
module:Dialog/DialogHeader/DEC-2 |
已定 |
| FR8 | 补偿 MUST 使用逻辑行内属性,保留标题、插槽和关闭操作的语义与命中目标,并且不暴露任何由调用方控制的边距值。 | architecture:container-padding;负责人决策 |
已定 |
| FR9 | 只要可选起始内容渲染,前导内容包装器 MUST 携带 dialog-header-start-content。 |
module:Dialog/DialogHeader/DEC-3 |
已定 |
| FR10 | 只要可选结束内容或关闭操作渲染,现有的尾部内容包装器 MUST 携带 dialog-header-end-content。 |
module:Dialog/DialogHeader/DEC-3 |
已定 |
转换与优先级顺序¶
- 如果存在
endContentEdgeCompensation,其闭合值会选择被补偿的轴向。 - 否则,渲染的关闭操作会选择
all;省略关闭操作则不选择任何补偿。 - 本模块在常规主题 CSS 通过共享主题管线解析之前,将每个主题 target 应用于其所属元素。
性能与资源¶
- 新增的闭合值分支与类选择不会引入任何监听器、观察器、定时器、测量或异步资源。
无障碍契约¶
- 补偿与主题 target MUST NOT 改变标题的角色、焦点行为、对话框命名、关闭按钮的可访问名称与操作,或任何插槽子项的命中目标。
设计关系¶
| 结构或状态 | 设计要求 | 呈现责任方 | 模块契约 |
|---|---|---|---|
| 标题行 | 负责标题内容与控件之间的排布和间距。 | 本模块 | FR1 |
| 起始内容 | 负责可选起始内容的前导包装器。 | 本模块 | FR9 |
| 标题块 | 负责标题/副标题的分组与间距。 | 本模块 | FR2 |
| 结束内容 | 负责现有的尾部包装器,其中包含可选结束内容与关闭操作,包括其固定的、面向插槽的补偿。 | 本模块 | FR4–FR8, FR10 |
| 关闭图标 | 负责 Button 所属操作内部关闭字形的视觉盒。 | 本模块与 Icon 渲染 | FR3, FR4 |
主题结构¶
{
"Header row": {"target": "dialog-header"},
"Start content": {"target": "dialog-header-start-content"},
"Title block": {"target": "dialog-header-title-block"},
"End content": {"target": "dialog-header-end-content"},
"Close icon": {"target": "dialog-header-close-icon"}
}
父级与系统关系¶
component:Dialog拥有模态行为与聚合的 Dialog 契约。component:Layout拥有本模块所属的五个内部部分之外的组合式 LayoutHeader 区域。component:Button拥有关闭操作的控制行为、命中目标与外部呈现。component:Icon渲染字形;本模块保证关闭图标的 DialogHeader 特定视觉契约拥有一个独立 target。architecture:component-theming-surface拥有 target 限定、结构映射,以及每个 target 必须位于其绘制器上的要求。architecture:container-padding定义了保留内边距(retained-inset)的边缘补偿意图,并将这种面向插槽的投影与 List 风格的继承内边距自补偿及全出血(full bleed)区分开来。
验证映射¶
| 契约 | 验证方式 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3、FR9–FR10 | 目标测试、目标清单、生成的探针主题及源代码检查 | 仅标题、标题/副标题、起始内容、结束内容、关闭操作 | 目标缺失、未记录、重复,或从其所属绘制者处移开。 |
| FR4–FR5 | 现有内容与关闭按钮测试 | 仅结束内容;仅关闭操作;两者皆有 | 关闭操作或插槽内容消失、重新排序,或新增另一层包装。 |
| FR6–FR7 | 针对结束插槽类选择的断言 | 仅关闭操作;仅结束内容;两者皆有;显式的 inline、block 和 all |
省略 prop 会改变已发布的几何尺寸,或显式值选择了错误的轴向。 |
| FR8 | 源代码检查、RTL 持续集成、交互测试,以及聚焦的真实浏览器几何测量 | LTR 与 RTL;自定义结束控件;关闭操作 | 物理外边距、调用方控制的数值或点击目标变化进入实现。 |
| 主题解剖映射 | scripts/check-knowledge.mjs |
所有五个模块解剖条目及目标 | 解剖结构、文档、运行时目标与模块映射发生漂移。 |
| RTL 关系 | RTL 审计中精选的 D2 目标(apps/storybook/rtl-audit/targets.json),作用于 Dialog / Default(对话框已打开) |
标题块与关闭控件;LTR 与 RTL | 标题若不在关闭控件的行内起始位置,则无法通过 D2。 |
决策日志¶
DEC-1 — Header targets follow stable anatomy and visual ownership¶
参考: module:Dialog/DialogHeader/DEC-1
决策者: cixzhang,2026-09-14
每个公开目标都代表文档化的解剖结构,并应用于拥有相应视觉表现的元素。头部行、标题块和关闭图标满足该准入规则,被批准为追加性目标。
DEC-2 — End-content compensation is slot-targeted and explicit¶
参考: module:Dialog/DialogHeader/DEC-2
决策者: cixzhang,2026-09-22
DialogHeader 在渲染关闭操作时保留其已发布的自动补偿。endContentEdgeCompensation 针对现有的结束内容插槽,并选择 inline、block 或 all,而不暴露外边距数值。这是保留内缩边缘补偿意图的插槽定向投影;它不会使 DialogHeader 成为 List 风格的继承内边距消费者。
DEC-3 — Content-slot wrappers are approved target destinations¶
参考: module:Dialog/DialogHeader/DEC-3
决策者: cixzhang,2026-09-23
startContent 和 endContent 的现有包装被批准为稳定的可见解剖结构。其目标位置为 dialog-header-start-content 和 dialog-header-end-content;实现不得添加任何包装,且必须保留默认布局、绘制、交互、可访问性和公开 props。尽管该插槽还包含可选的关闭操作,结束内容的命名仍遵循公开 prop。
开放问题¶
endContentEdgeCompensation的inline、block和all轴值如何映射到endContentEdge的处理值(architecture:container-padding),以及旧 prop 何时进入其兼容窗口?目前该 prop 仍按发布时的状态保持支持。
内容边界¶
本记录不重复消费者签名/示例、父级 Dialog 行为、实现步骤或共享主题规则。它链接到这些内容的规范所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx