跳转至

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 已定

转换与优先级顺序

  1. 如果存在 endContentEdgeCompensation,其闭合值会选择被补偿的轴向。
  2. 否则,渲染的关闭操作会选择 all;省略关闭操作则不选择任何补偿。
  3. 本模块在常规主题 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