跳转至

Banner 组件契约

意图

Banner 在页面或区块顶部展示一条持久状态消息。 本契约记录了当前绘制的表面,并将 Banner 框架作为可单独定位的表面。status 和 content 目标保持不变。

兼容性与迁移

  • 已发布默认值保留:no — Banner 不再从视觉状态派生 live-region 角色
  • 兼容性类别:针对 live-region 变更的破坏性无障碍语义修正 (DEP-0007),其视觉输出、DOM 结构、props、主题目标和交互行为均保持不变。FR9 是一项视觉变更:Info 状态表面填充 --color-info-muted,内置内容采用 on-muted 角色;props、DOM 结构和主题目标保持不变
  • 受控/非受控行为:保持不变
  • 迁移决策:在过渡处理函数中使用 useAnnounce 宣布异步结果,并将 role="alert" 保留给紧急消息——Banner 会将其放在消息元素上 (FR8)。在已挂载的 live 容器内,适用 spec:AST-086 FR4。

消费者迁移说明应写在消费者文档和发布说明中。

DEP-0007 — 弃用从 status 派生的 live-region 角色

字段 值
id DEP-0007
cleanup CLN-0015
package @astryxdesign/core
表面 Banner 的默认 ARIA 角色:当调用方未传 role 时,根据 status 派生——warning 和 error 为 role="alert",info 和 success 为 role="status"
旧契约 视觉 status 选择 Banner 根元素的 live-region 角色
替代方案 宣布异步结果的调用方在产生该结果的过渡中调用 useAnnounce。紧急消息传入 role="alert",Banner 会将其放在消息元素上 (FR8)。在已挂载的 live 容器内,则适用 spec:AST-086 FR4。
直接权威 component:Banner。负责人:cixzhang、imdreamrunner
警告 消费者文档和发布说明需指明 DEP-0007、用于其他消息的 useAnnounce,以及用于紧急消息的 role="alert"。无运行时警告(spec:AST-017 FR29)
迁移 非机械性:宣布异步结果的调用方在产生该结果的过渡中调用 useAnnounce;有紧急消息的调用方传入 role="alert"。在已挂载的 live 容器内,则适用 spec:AST-086 FR4。
codemod 无:Banner 是否需要以及何时需要公告,取决于渲染它的过渡,而这只有调用方知道;在所有地方添加已发布的 role 会恢复本次清理所移除的耦合。
下游 受维护的文档指导:异步结果使用 useAnnounce,role="alert" 仅用于紧急消息。在已挂载的 live 容器内,则适用 spec:AST-086 FR4。
过渡 无先前过渡
状态 proposed
未决决策 使 status 仅作为视觉属性的 Banner FR 和 DEC 条目
目标计划 CLN-0015,在下一个次要版本中执行

CLN-0015 — Banner 默认不渲染实时区域角色

Field Value
id CLN-0015
lifecycle DEP-0007
delta 除非调用方传入 role,否则 Banner 不渲染 role 和 aria-live。视觉状态样式、图标、主题目标和显式 role 转发保持不变
rollback 从最终补丁基线恢复 status 到 role 的映射
state pending — 在声明的次要版本中落地,并附带其 [breaking] Changeset

所有权边界

拥有

  • 当前状态表面,作为 Banner 的主要绘制表面。
  • 其下方的可选内容表面。
  • Banner 框架,它组合两个表面,并承载当前整个 banner 的 elevation 和 elevated-card 轮廓。
  • 状态表面上,Banner 编写的标题、描述、图标、折叠和关闭内容的语义前景上下文。内置控件仅在其 Button 元素上接收该上下文,因此它们的 tooltip 仍是一个普通 Button 表面。

不拥有 / 非目标

  • Button 几何、交互层、tooltip 绘制或消费者提供的 endContent — 委托给 component:Button。包含两个或更多操作的操作行遵循 family:action-groups。
  • 不新增主题属性、prop、变体或 DOM 元素。

公共概念

Banner 框架是一个稳定的公共主题概念。其目标是 banner-frame,并反映现有的 container 和 elevation 轴。现有的 banner 目标仍保留在状态表面上,并继续反映 container 和 status。

消费者 props、默认值和用法仍记录在 Banner.doc.mjs 中。prop 词汇或扩展性规则均无变化。

行为与布局契约

以下需求描述当前实现及其附加的框架目标契约。

ID 不变量 依据 契约状态
FR1 当前渲染将 banner 放置在彩色状态表面上,该表面是 Banner 的主要绘制表面,并反映 container 和 status。 当前源码、公共文档和测试 当前行为
FR2 Banner 框架接收公共 ref、role、受支持的 DOM props、xstyle、className 和 style;它还会绘制所选定的 boxShadow。例外情况是 role="alert" 以及与其一起传入的 aria-* 属性,这些会落在消息元素上(FR8)。 当前源码和测试 当前行为
FR3 浮起的 card 框架也会绘制整个 Banner 的圆角。section 框架保持直角。非浮起的框架不会收到框架圆角样式。 当前源码和 elevation 测试 当前行为
FR4 卡片形状由各表面所有者分别负责:状态表面负责所有没有可见内容的角,或负责有可见内容时的顶部角;内容表面负责底部角。 当前源码 当前行为
FR5 主题在 banner 上编写的 borderRadius 目前只会在状态表面上写入私有变量 --_banner-radius。CSS 继承不会将该值向上传递给框架,也不会横向传递给内容表面,因此两者都保留其回退圆角。 当前编译器输出和 CSS 继承 当前可达性缺口
FR6 Banner 框架暴露 banner-frame,并反映 container 和 elevation。现有的 banner 目标仍保留在状态表面上,而不会移动到最外层的 DOM 元素。 所有者决策;当前源码和测试 当前行为
FR7 banner-frame 是叠加性的。现有的 banner、banner-icon、banner-description 和 banner-content 目标及其当前轴向保持不变。 当前目标清单;兼容性策略 当前行为
FR8 status 仅控制视觉含义,并且 MUST NOT 派生 role、aria-live 或任何通告。当 Banner 的消息是紧急的(用户必须立即处理的错误或时间紧迫的失败)时,该 Banner 可以携带 role="alert",由调用方传入。Banner 将该角色以及随之传入的 aria-* 属性放置在它的消息元素上,该元素只包含标题和描述,绝不放置于框架、末端区域或内容区域上。所有其他 Banner 通告都通过产生该通告的转换中的 useAnnounce 进行,其紧急程度由 spec:AST-086 FR5 设定。带有 role="alert" 的 Banner 不再通过 useAnnounce 进行通告(spec:AST-086 FR1)。角色落在何处不会改变任何视觉:不会为其改变任何元素、样式或布局。在已挂载的 live 容器内,适用 spec:AST-086 FR4,且 Banner 不携带 live 角色。 无障碍检查清单 §Announcements;负责人决定 当前行为
FR9 状态表面使用匹配的 --color-<status>-muted 角色填充(Info 使用 --color-info-muted),并使用匹配的 --color-on-<status>-muted 角色绘制其内置的标题、描述、图标、折叠和关闭内容。Banner 将这一语义化前景上下文提供给每个内置的 Button 元素,而不改变 Button 所拥有的几何或交互层;同级 tooltip 保持 Button 的普通主题颜色。使用者提供的 endContent 保持不变。 状态角色架构;Banner 和 Button 源码/测试 当前行为

允许的变化

  • AV1 — 内容存在性。 在现有 collapsible 契约下,内容表面可以不存在、折叠、展开或始终可见。
  • AV2 — 目标范围。 主题对整个 Banner 的轮廓和高度使用 banner-frame,对主要状态表面使用 banner,对其拥有的部分使用现有的子目标。

代表性状态

状态 必需的当前行为 允许的变化
扁平卡片,无可见内容 状态表面是完整的圆角绘制表面;框架阴影为 none,且不应用框架圆角样式。 状态、文本、控件和主题绘制
抬升卡片,有可见内容 框架绘制整个阴影和圆角;状态表面绘制顶部圆角;内容表面绘制底部圆角。 抬升层级和内容
抬升区域 框架绘制整个阴影而不带卡片圆角;状态表面和内容表面保持直角。 抬升层级和内容
banner 上的自定义圆角 状态表面接收私有圆角值;框架和内容表面保持其回退圆角。 编写的圆角值

转换与优先级顺序

  • ORD1 — 表面解析。 解析 container、elevation 和可见内容;将整个横幅的 elevation 以及任何 elevated-card 圆角应用到 Banner 框架;然后渲染目标状态表面和可选的目标内容表面。
  • ORD2 — 当前圆角路由。 主题编译将编写在 banner 上的 borderRadius 写入状态表面的私有圆角变量。该值不会继承到祖先框架或同级内容表面。使用者不会直接编写私有变量。

性能与资源

本契约不会引入新的测量、观察器、监听器、渲染过程或运行时工作,除了 family:action-groups FR5 为两个或更多操作的操作行提供的按下追踪。

无障碍契约

status 通过颜色和图标传达视觉类别;它不选择公告的紧急程度。紧急 Banner 的消息元素带有 role="alert";其文本是标题和描述,在 DOM 中以空格分隔。控件、其工具提示、endContent 和内容区域位于其外部。其他 Banner 消息通过 useAnnounce 进行公告,Banner 不为它们渲染 live role。useAnnounce 将内容写入先前挂载的 live region;在已挂载的 live 容器内,该容器负责传递它们(spec:AST-086 FR4)。任何其他与其 Banner 一同挂载的 Banner 消息都不是可靠的公告。

关闭时的焦点交接、披露控件和可访问的控件名称保持不变。

专用的 alert-state 绑定仅对通过标准 DOM 表面明确请求 role="alert" 的 Banner 渲染进行测试。它检查共享 status-message 契约的 DOM、无障碍树和焦点保持结果,但不声称辅助技术具体会公告什么。公告的措辞和时机仍由 AST-009 负责。该绑定会报告整个区域的原子性,但不会因其而失败,因为该期望是建议性的。每个状态都通过所有必需的期望:在普通、可关闭、折叠、展开、始终可见、调用者操作和描述状态下,alert 区域仅包含标题和描述。

设计关系

解剖结构或状态 设计需求 表示权威 层级角色 组件契约
Banner 框架 将状态表面和可选内容表面分组,并承载它们共享的轮廓和 elevation。 当前来源和公开文档 支持性 FR2、FR3、FR4
状态表面 充当 Banner 的主要绘制表面,承载状态填充、消息和控件。 当前来源和公开文档 突出 FR1
内容表面 在状态表面下方承载可选的支持性细节。 当前来源和公开文档 支持性 FR4、FR7
操作/关闭控件 内置控件内容在 Button 元素上接收状态表面的 on-muted 前景色;交互层和工具提示仍归 Button 所有。使用者提供的 endContent 保持不变。 Banner 状态上下文加上 component:Button 支持性 FR7、FR9

Banner 框架是稳定的解剖结构,并拥有附加的 banner-frame 目标。状态表面仍然是 Banner 的主要绘制表面,并保留不加限定的 banner 目标。

主题化解剖

{
  "Banner frame": {"target": "banner-frame"},
  "Status surface": {"target": "banner"},
  "Icon": {"target": "banner-icon"},
  "Title": {"inherits": "banner"},
  "Description": {"target": "banner-description"},
  "Action button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Dismiss button": {
    "delegatesTo": {"owner": "component:Button", "target": "button"}
  },
  "Content surface": {"target": "banner-content"}
}

此映射记录了运行时可达性。banner 属于主要的状态表面,而不是最外层的 DOM 元素,而 banner-frame 属于拥有整个横幅 elevation 和轮廓的可见框架。对 Button 的委托保留了每个内置控件的解剖结构和交互所有权。Banner 仅在 Button 元素上提供状态表面的前景上下文,并且不会重新设置使用者提供的 endContent 子元素的样式。

家族与系统关系

  • architecture:component-theming-surface 负责目标限定、解剖映射,以及公共目标必须位于稳定绘制部分上的要求。
  • architecture:public-component-api 管理 DEC-1 所允许的附加目标的兼容性。
  • architecture:theme-compilation 负责私有派生变量路由,该路由当前在其各绘制表面之间传递 Banner 圆角。

验证映射

合约 验证 代表性状态 变更或失败预期 审计章节
FR1, FR7 Banner.test.tsx 和 themingTargets.test.ts 状态表面、内容表面、当前目标轴 移动、移除或更改现有目标会破坏当前的断言。 audit:Banner/theming
FR2, FR3, FR4 Banner.test.tsx 以及当前源码检查 平面/抬升卡片与抬升的 section Frame、状态表面、内容表面、阴影或圆角的所有权与记录状态相比发生变化。 audit:Banner/surfaces
FR5 编译器输出以及浏览器/计算样式证据 有内容和没有内容的卡片;抬升卡片 banner.borderRadius 意外地影响到 frame/content,或者文档声称当前路径已经这样做。 audit:Banner/radius
FR6, FR7 实现 PR 目标、编译器、探针和组件测试 无、低、中、高 elevation 下的 card/section banner-frame 缺失、使用其他名称、缺少某个轴,或移动了现有的 banner 目标。 audit:Banner/theming
FR8 Banner.test.tsx、消费者文档、无障碍检查清单 A6 默认的 info/success/warning/error;消息元素上显式的 alert 角色 某个视觉状态创建了 live region,显式 alert 角色被丢弃或落在消息元素之外,或者文档让构建者通过有条件地挂载 Banner 来进行播报。 audit:Banner/a11y
FR8 alert 状态 Alert.a11y.test.tsx 和 Alert.a11y.chromium.spec.ts 显式的紧急错误;可关闭、折叠、打开、始终可见、调用方操作和描述变体 在消息更新时,角色、assertive 通道或焦点保留出现回退;alert 区域包含除标题和描述之外的任何内容;或者 frame 承载了该角色或其 aria-* 属性。原子性会被报告,但不会被强制。 audit:Banner/a11y
FR9 Banner.test.tsx 以及 Button tooltip 和自定义末尾内容断言 四种状态;内置折叠/关闭;tooltip;消费者操作 内置内容失去对应的 on-muted 角色,tooltip 被重新绘制,Button 交互所有权发生变化,或者消费者内容被修改。 audit:Banner/theming
Theming anatomy 映射 scripts/check-knowledge.mjs 八个 anatomy 条目和五个当前目标 缺失、多余、带前缀、过期或未认领的当前映射都会校验失败。 audit:Banner/theming

决策日志

DEC-1 — Banner frame 拥有独立的公共主题所有权

Reference: component:Banner/DEC-1

Decider: cixzhang, 2026-09-07

Banner frame 是稳定可见的 anatomy,在 Status 表面和可选的 Content 表面上拥有整个 banner 的 elevation 以及抬升卡片的轮廓。它接收新增的 banner-frame 目标,带有 container 和 elevation 选择器轴。现有的 banner 目标保留在主要 Status 表面上。

frame 用于命名公共视觉角色。root 被否决,因为它描述的是 DOM 位置,并会暗示该目标必须保留在最外层元素上。

DEC-2 — 视觉状态不推断播报紧迫性

Reference: component:Banner/DEC-2

Decider: cixzhang, 2026-09-24

紧迫性由调用方决定,通过 role="alert" 标记;Banner 将该 alert 限定在消息上,这样辅助技术只会听到作者编写的内容。其他所有消息都使用标准 announce 模块,因此每条消息由同一个所有者进行播报。

已否决:在整个 frame 上使用 live 角色,因为这会暴露控件和 tooltip 文本。

已否决:根据 warning 或 error 来推导警报紧急程度。严重性与紧急程度相互独立,首次绘制时出现的静态错误并非应中断屏幕阅读器输出的事件。

未决问题

无。

内容边界

此文件不重复提供消费者属性表或示例、实现步骤或系统主题规则。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx