DrawerHeader 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | DrawerHeader,包含 title、subtitle、onOpenChange、startContent、endContent、endContentEdgeCompensation(inline、block、all)和 hasDivider;五个 drawer-header 目标。 |
| 行为 | Drawer 的 Layout 头部行:可选开始内容、一个带可选副标题的 h2 标题、可选结束内容,并且仅在提供 onOpenChange 时显示关闭按钮。 |
| 终端用户影响 | 用户会看到抽屉的标题;当调用方提供 onOpenChange 时,还会看到一个带名称的关闭按钮;头部挂载时不会移动焦点。 |
| 构建者影响 | 无。 |
| 兼容性/就绪度 | 记录已发布行为;无公开变更。 |
| 审查检查项 | 拒绝在没有 onOpenChange 时渲染关闭按钮;拒绝为 Drawer 命名的头部或在挂载时移动焦点的头部;拒绝不是 h2 的标题。 |
| 治理规则 | component:Drawer(面板和命名);family:layout-regions;architecture:component-theming-surface。 |
此表是审查投影;正文以下文为准。
意图¶
DrawerHeader 是调用方在 Drawer 的 Layout 头部槽位中组合出的可选标题行。它拥有该行的各个部分、关闭按钮及其目标。消费者用法位于 DrawerHeader.doc.mjs 中。
兼容性与迁移¶
- 已发布的默认值保持不变:
yes - 兼容性类别:记录已发布行为;无公开变更
- 受控/非受控行为:关闭按钮调用调用方的
onOpenChange(false),且自身不持有状态 - 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 头部行、其槽位、标题语义、关闭按钮、结束内容边缘补偿,以及五个目标(FR1–FR5)。
不拥有 / 非目标
- Drawer 的名称、焦点入口和打开状态——由
component:Drawer拥有。 - 头部区域的内边距、分隔线默认值和在 Layout 中的位置——由
family:layout-regions通过LayoutHeader拥有。 - 关闭 Button——由
component:Button拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| End-content 边缘补偿 | inline、block、all、省略 |
结束槽的哪些边缘向外扩展,以使末尾控件与容器边缘对齐。 | 结束槽。 | 设置了 onOpenChange 时两个轴都进行补偿,否则不补偿。 |
component:DrawerHeader |
稳定 | TypeScript 拒绝其他值。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | DrawerHeader 渲染在 LayoutHeader 内部,LayoutHeader 接收 ref、hasDivider、xstyle、className、style 和其他 DOM 属性。其行承载 drawer-header,并按顺序显示开始内容、标题块和结束槽。 |
当前源码与测试 |
| FR2 | 标题渲染为 h2;可渲染的 subtitle(包括 0)在其下方渲染为次要的小号正文文本,空值则不渲染任何内容。开始槽和结束槽在其内容可渲染时渲染,包括 0。 |
当前源码与测试 |
| FR3 | 当存在 onOpenChange 时,结束槽末尾会有一个仅图标的幽灵 Button,其名称和工具提示由 @astryx.dialog.close 提供,且该 Button 调用 onOpenChange(false);没有 onOpenChange 时则不显示关闭按钮。 |
当前源码与测试 |
| FR4 | 结束槽根据 endContentEdgeCompensation,在块轴、内联结束边缘或两者上向外扩展 --spacing-2;未指定时,仅当存在关闭按钮时才同时应用于两个方向。 |
当前源码 |
| FR5 | 开始槽、标题块、结束槽和关闭图标分别承载 drawer-header-start-content、drawer-header-title-block、drawer-header-end-content 和 drawer-header-close-icon。 |
当前源码与测试 |
| FR6 | 挂载头部不会移动焦点,且头部不会为 Drawer 命名。 | 当前源代码与测试 |
允许的变体¶
- AV1 — 插槽。 开始、结束和副标题内容可有变化或缺失。
代表性状态¶
| 状态 | 必需的不变式 | 允许的变体 |
|---|---|---|
| 仅标题 | h2 标题;无关闭按钮。 | — |
带有 onOpenChange |
末尾的命名关闭按钮;边缘已补偿。 | 结束内容。 |
| 开始和结束插槽 | 顺序:开始、标题块、结束。 | 内容。 |
转换与优先级顺序¶
- ORD1 — 补偿。
endContentEdgeCompensation,然后是关闭按钮默认值(FR4)。
性能与资源¶
- 无资源规则。
无障碍契约¶
- AR1 — 标题。 标题是 h2。
- AR2 — 关闭名称。 FR3 的翻译名称与工具提示。
- AR3 — 焦点。 FR6。
设计关系¶
| 解剖结构或状态 | 设计需求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 头部行 | 开始、标题块、结束位于同一行。 | 当前源代码与公开文档 | 支撑 | FR1 |
| 开始内容 | 前导调用方内容。 | 当前源代码与公开文档 | 支撑 | FR2, FR5 |
| 标题块 | 标题与可选副标题。 | 当前源代码与公开文档 | 突出 | FR2, FR5 |
| 结束内容 | 末尾的调用方内容与关闭按钮。 | 当前源代码与公开文档 | 支撑 | FR3–FR5 |
| 关闭图标 | 按钮内的关闭字形。 | 当前源代码与公开文档 | 支撑 | FR3, FR5 |
主题化解剖结构¶
{
"Header row": {"target": "drawer-header"},
"Start content": {"target": "drawer-header-start-content"},
"Title block": {"target": "drawer-header-title-block"},
"End content": {"target": "drawer-header-end-content"},
"Close icon": {"target": "drawer-header-close-icon"}
}
家族与系统关系¶
component:Drawer在其 Layout 中承载头部,并拥有命名与焦点。family:layout-regions拥有头部所渲染到的区域。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR2, AR1 | DrawerHeader.test.tsx 标题与插槽测试 |
标题、副标题、0 值、空插槽 |
标题级别错误或内容缺失则失败。 | audit:DrawerHeader/anatomy |
| FR3, AR2 | DrawerHeader.test.tsx 关闭按钮测试 |
有和没有 onOpenChange |
没有回调的按钮或没有名称的按钮将失败。 | audit:DrawerHeader/accessibility |
| FR5 | DrawerHeader.test.tsx 主题目标测试 |
所有插槽 | 缺少目标则失败。 | audit:DrawerHeader/theming |
| FR6, AR3 | DrawerHeader.test.tsx 焦点测试 |
挂载 | 挂载时焦点被移动则失败。 | audit:DrawerHeader/accessibility |
| 主题化解剖结构映射 | scripts/check-knowledge.mjs |
消费方解剖结构与当前目标 | 缺失、多余或过时的映射将无法通过验证。 | audit:DrawerHeader/theming |
FR4 从源代码中读取;目前尚无专门测试对其进行校验。
从源代码读取,目前尚无专门测试:
- FR1:
ref、hasDivider、xstyle、className、style以及其他到达 LayoutHeader 的 DOM 属性。 - FR3:关闭按钮的工具提示。
- FR4:结束插槽的边缘补偿。
- FR6:头部不为 Drawer 命名。
决策日志¶
未记录任何组件本地决策。
待解决问题¶
endContentEdgeCompensation的inline、block和all轴值如何映射到endContentEdge处理值(architecture:container-padding),以及旧属性何时进入其兼容窗口?目前该属性仍保持发布时的受支持状态。
内容边界¶
本文件不重复消费方属性表、示例或 Drawer 行为。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx