CommandPaletteEmpty 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | CommandPaletteEmpty / CommandPaletteEmptyProps:必需的 children、BaseProps<HTMLDivElement> 和根 ref。 |
| 行为 | 一个普通容器将调用方内容作为辅助文本居中显示。CommandPalette 在无查询和无结果分支中渲染它;它不拥有任何角色、状态、通告或交互。 |
| 终端用户影响 | 进入命令面板死胡同的用户会读取该消息,并且任何调用方链接仍然是普通可访问内容,而不是一个选项。 |
| 构建者影响 | 无。 |
| 兼容性/就绪度 | 记录已发布行为;无公共变更。对于标记为从源码读取的声明,证据仍待补充。 |
| 审查项 | 拒绝组件自有的角色或活动区域、围绕调用方内容的选项语义、丢失的根输入、移出绘制根的目标,或内容溢出宿主内联轴的情况。 |
| 约束规则 | architecture:public-component-api/INV1,INV5–INV8;architecture:component-theming-surface/INV2–INV6;spec:AST-056/FR3、AR1 用于父组件的通告;WCAG 2.2 SC 1.4.3 和 1.4.10。 |
此表是审查投影;以下正文具有权威性。
意图¶
CommandPaletteEmpty 呈现当没有可选内容时在 CommandPalette 结果区域中显示的消息。它拥有空消息表面:其布局、辅助排版、次要文本颜色、根输入组合,以及 command-palette-empty 主题目标。CommandPalette 决定消息何时出现、默认显示什么内容,以及是否进行通告。
使用方语法和示例属于 CommandPaletteEmpty.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:不适用。
- 迁移决策:无。
使用方迁移说明属于使用方文档和发布说明。
所有权边界¶
拥有
- 一个根容器及其公共 ref、DOM/数据/ARIA、类、样式、事件和
xstyle组合。 - 居中布局、块级和内联内边距、辅助字号和行高、正文字体族,以及调用方内容的次要文本颜色。
- 在宿主的内联尺寸内换行调用方文本。
- 同一绘制根上的
command-palette-empty目标。
不拥有 / 非目标
- 空分支何时出现、内置目录消息,以及空搜索通告——由
component:CommandPalette拥有。 - 空状态下的结果表面语义,包括移除 listbox 语义——由
component:CommandPalette和component:CommandPaletteList拥有。 - 调用方内容中的含义、链接或控件——由产品调用点拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 空消息 | 调用方 ReactNode:文本或元素 |
当没有可选内容时人们阅读的辅助消息。 | 无查询和无结果的面板分支;独立组合 | 必需 | 组件 | 稳定 | 按给定内容渲染;React 决定不可渲染的值。 |
| 根表面 | ref;DOM/数据/ARIA;类/样式/xstyle/事件 | 扩展消息根节点。 | 每次渲染 | 省略 | 公共组件 API | 稳定 | 接受的输入组合;组件不添加角色。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 组件 MUST 将其 children 渲染在一个容器元素内,该容器在两条轴上都居中它们,并使用居中文本、辅助排版、正文字体族和次要文本颜色。 | 当前源代码、使用方文档和针对性测试 |
| FR2 | 当没有查询且没有结果时,CommandPalette MUST 以 emptyBootstrapText 渲染此组件;当查询无结果时,以 emptySearchText 渲染。 |
当前源代码和测试 |
| FR3 | 根元素 MUST 不携带组件拥有的角色、实时区域或焦点停靠点,因此调用方的链接和控件保持为普通内容。 | WAI-ARIA 1.2 listbox 自有子元素规则;当前源码与测试 |
| FR4 | 调用方文本 MUST 在宿主的内联尺寸内换行,包括单个不中断的 token,因此任何消息都不会在 320 CSS px 下强制内联滚动或裁剪。 | WCAG 2.2 SC 1.4.10;当前源码 |
| FR5 | 已绘制的根元素 MUST 携带 command-palette-empty 目标;组件样式在调用方 xstyle 之前应用。 |
architecture:component-theming-surface/INV2–INV6;源码与聚焦测试 |
| FR6 | 已接受的 ref、DOM/数据/ARIA、class、style、事件以及 xstyle MUST 到达根元素,或在根元素上组合。 |
architecture:public-component-api/INV5–INV8;聚焦测试 |
允许的变化¶
- AV1 — 主题绘制。 目标可以在不改变语义或布局归属的前提下,重新设置消息表面和文本的样式。
- AV2 — 调用方内容。 文本长度、翻译、内联元素和链接可以变化,而根元素始终保持一个普通容器。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 调色板无查询空状态 | 引导消息在结果区域中渲染;不暴露 listbox。 | 内置目录文本或调用方内容。 |
| 调色板无结果 | 搜索消息渲染;CommandPalette 公告渲染的文本。 | 内置目录文本或调用方富内容。 |
| 独立使用 | 相同根元素在调色板外部以调用方内容渲染。 | 宿主布局与调用方角色。 |
| 长文本或翻译文本 | 文本在宿主内换行;无内联溢出。 | 行数增加。 |
| RTL | 居中布局与文本保持方向中性;内联文本顺序镜像。 | 调用方内容方向。 |
| 窄视口 | 消息在 320 CSS px 宿主内换行。 | 行数增加。 |
转换与优先级顺序¶
- ORD1 — 根元素组合。 依次应用目标 class、组件样式,然后应用调用方
xstyle;追加调用方className;应用调用方style;将剩余的宿主 props 展开到根元素上。
性能与资源¶
- PR1 — 无生命周期。 CommandPaletteEmpty 不使用任何 hook、listener、observer、timer、request、state 或 Effect。
可访问性契约¶
- AR1 — 普通内容。 根元素按阅读顺序暴露调用方内容,且不添加任何角色;调用方链接保持其自身的角色和焦点行为。
- AR2 — 可读消息。 消息文本在所有支持的主题和模式下,相对其所渲染的表面满足 WCAG 2.2 SC 1.4.3 对比度最低要求。
设计关系¶
| 解剖结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 空消息 | 将死胡同消息作为结果区域中居中的辅助文本呈现。 | 当前源码 token | 辅助 | FR1, FR4, FR5 |
未记录任何组件本地的设计决策。聚合的 CommandPalette 解剖结构映射由 component:CommandPalette 拥有,并将 Empty 部分映射其中。
家族与系统关系¶
architecture:public-component-api拥有导出与根输入组合。architecture:component-theming-surface拥有目标放置。architecture:component-test-sufficiency拥有相称的、可观察的证据。spec:AST-056/FR3与AR1要求 CommandPalette 公告其渲染的空搜索消息;此组件提供渲染出的节点。component:CommandPalette与component:CommandPaletteList拥有父分支与空结果表面。spec:AST-029拥有审计证据清单,本记录的验证映射遵循该清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR5–FR6 | CommandPaletteEmpty.test.tsx;themingTargets.test.ts |
文本与元素子节点;根输入 | 丢失的输入、移动的目标或丢失的子节点会导致聚焦断言失败。 | audit:CommandPaletteEmpty/§2,§3,§4 |
| FR2, FR3, AR1 | CommandPalette.test.tsx; CommandPaletteList.test.tsx |
引导(bootstrap)、搜索、富内容、模态与内联 | 暴露 listbox、添加 role,或宣布与渲染消息不同的其他文本,均会使断言失败。 | audit:CommandPaletteEmpty/§1,§4 |
| FR4, AR2 | CommandPaletteEmptyAudit.a11y.chromium.spec.ts |
窄/宽视口;浅色与深色;强制颜色;富内容 | 在 320 CSS px 下出现水平溢出的用例无法通过审计清单测试。缺口:审计会记录消息对比度,但不对其进行门禁判断,因此对比度低于 4.5:1 不会导致失败。 | audit:CommandPaletteEmpty/accessibility |
| PR1 | 源码审查 | 每种状态 | 缺口:如果 CommandPaletteEmpty 添加了 hook、监听器或 Effect,没有任何自动化检查会使其失败。 | audit:CommandPaletteEmpty/behavior |
根据源码阅读,尚无聚焦测试:
- FR1:居中、支持的类型、正文字体以及次要文本颜色。
- AR2:每个主题和模式下的消息对比度。
- PR1:组件自身不拥有 hook、监听器或生命周期。
决策日志¶
未记录任何组件局部决策。
开放问题¶
无。
内容边界¶
本文件不重复消费方属性表格/示例、实现步骤或系统规则。它将链接到其所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx