跳转至

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