跳转至

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