SelectorOption 组件契约¶
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | SelectorOption 与 Selector 一同导出,接受 label(必填)、icon、description、layout(默认为 stacked,或 inline)、endContent、xstyle、className 和 style。 |
| 行为 | 渲染一个 Item 行,包含可选的图标、label、可选 description 和可选结束内容;该行自身的内边距和圆角被移除,以便宿主行对其进行布局。 |
| 最终用户影响 | 用户会看到自定义 Selector 选项和选中值与内置选项具有相同的行形状;较长的字符串标签会省略显示,而不会溢出窄弹出框。 |
| 构建者影响 | 构建者从 renderOption 或 renderValue 返回它,以在自主选择内容的同时保留 selector-option 目标和共享的行布局。 |
| 兼容性/就绪状态 | 记录已发布行为;无 API、默认值或 DOM 变更。缺失的 ref 和 DOM 属性列于“当前状态影响”下。 |
| 审查要点 | 应拒绝以下情况:丢失图标、描述或结束内容;在 InputGroup 外部忽略调用方的 layout,或作为 InputGroup 内 Selector trigger 值时仍保持 stacked;或丢失 selector-option 目标。 |
| 治理规则 | architecture:component-theming-surface;architecture:public-component-api INV5、INV8;组成行的 component:Item。 |
此表是审查概览;以下正文才具有权威性。
设计意图¶
让自定义 Selector 选项和值渲染与内置选项相同的行布局和主题目标,而不拥有选项语义或选择逻辑。
兼容性与迁移¶
- 已发布的默认值保留:是
- 兼容性类别:记录已发布行为;无公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:不适用;SelectorOption 不持有状态
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
职责边界¶
拥有
- 它通过
component:Item渲染的内容行:图标槽位、标签、描述、布局选择和结束内容。 - 该行上的
selector-option目标,以及移除该行自身的内边距、圆角和最小宽度。 - 当宿主固定行高度时,折叠为
inline。
不拥有 / 非目标
- 选项行的 role、name、选中和高亮状态以及选择逻辑——由
component:Selector拥有。 - 触发器围绕已渲染值的大小尺寸——由
component:Selector拥有。 - Item 的布局、密度和目标——由
component:Item拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向的可获得性 |
|---|---|---|---|
| layout | stacked、inline |
stacked 将描述放在单独一行;inline 将标签和描述保持在一行。 |
调用方选择,除非作为 InputGroup 内的 Selector trigger 值(此时为 inline)。 |
| icon | 缺失,存在 | 语义图标名称或图标组件会在标签前渲染为一个小号次要 Icon;其他 ReactNode 内容按原样渲染。 | 所有布局。 |
| 结束内容 | 缺失,存在 | 标签和描述之后的调用方内容。 | 所有布局。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | SelectorOption 渲染一个 component:Item 行:当存在时,icon 位于起始槽位(语义图标名称或图标组件作为小号次要 Icon,其他 ReactNode 内容按原样提供),还有 label、存在时的 description 和存在时的 endContent。Selector 的默认选项渲染器也通过 SelectorOption 绘制每个选项。 |
当前源码和测试 |
| FR2 | 该行使用调用方的 layout(默认为 stacked)。当宿主固定行高度(InputGroup 内的 Selector trigger)时,无论调用方传入什么,该行均为 inline。 |
当前源码和测试 |
| FR3 | 行承载 selector-option 目标。其自身的块级和内联内边距以及圆角半径均为零,最小宽度为零,因此长字符串标签在窄宿主内会省略显示(ReactNode 标签则换行)。调用方的 xstyle 在这些基础样式之后合并;className 和 style 会作用于该行。 |
architecture:component-theming-surface;当前源码 |
| FR4 | SelectorOption MUST 接受一个连接到其行的 ref,并将受支持的 DOM props 传递给它(architecture:public-component-api INV5、INV8)。实现差距:它既不接受 ref,也不接受其他 DOM props。 |
architecture:public-component-api INV5、INV8;当前源码 |
允许的变化¶
- AV1 — 内容。 标签、描述、图标和结尾内容均为调用方内容。
- AV2 — 主题绘制。 主题可以重新设置
selector-option目标的样式。
代表性状态¶
| 状态 | 必有不变量 | 允许的变化 |
|---|---|---|
| 选项,堆叠 | 描述位于标签下方。 | 内容。 |
| 选项,内联 | 标签和描述位于同一行。 | 内容。 |
| InputGroup 中的触发器值 | inline,无论调用方传入什么。 |
内容。 |
| 带有结尾内容 | 结尾内容位于标签和描述之后。 | 内容。 |
转换与优先级顺序¶
- ORD1 — 布局。 宿主固定的
inline→ 调用方layout→stacked。 - ORD2 — 样式。 基础行重置 → 调用方
xstyle→className和style。
性能与资源¶
- PR1 — 纯渲染。 SelectorOption 不拥有任何状态、副作用、监听器、观察器或定时器。
无障碍契约¶
- AR1 — 仅内容。 SelectorOption 不添加任何 role、名称或状态;这些由它所处的 Selector 选项行拥有。语义化名称或图标组件是装饰性的;其他 ReactNode 内容保留其调用方赋予的语义。
设计关系¶
| 解剖结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 行 | 像内置选项一样布置选项内容。 | 当前源码 | 支持 | FR1、FR3 |
| 图标 | 一眼识别选项。 | 当前源码 | 支持 | FR1 |
| 标签 | 为选项命名。 | 当前源码 | 突出 | FR1、FR3 |
| 描述 | 添加次要细节。 | 当前源码 | 支持 | FR1、FR2 |
| 结尾内容 | 在文本之后容纳调用方内容。 | 当前源码 | 支持 | FR1 |
Selector.spec.md 在其主题解剖结构中将 selector-option 目标映射为“SelectorOption 渲染的内容”,因此此记录不携带解剖结构-主题映射。
系列与系统关系¶
component:Selector拥有选项行、触发器以及其主题解剖结构中的selector-option映射。component:Item拥有 SelectorOption 组合所用的行布局。architecture:component-theming-surface拥有目标放置。architecture:public-component-api拥有样式组合。
验证映射¶
| 契约 | 验证 | 代表性状态 | 突变或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1 | Selector.test.tsx 中的 “renders custom option endContent” 和 “renders the selected option through renderValue” |
带结尾内容的选项;带图标和描述的值 | 丢失结尾内容、标签、描述或图标则失败。证据缺口:没有测试断言语义化图标名称或图标组件的小型次要呈现。 | audit:SelectorOption/anatomy |
| FR2 | Selector.test.tsx 中的 “follows the caller's SelectorOption layout, but folds inline in a group” |
独立触发器;位于 InputGroup 中的触发器 | InputGroup 中的堆叠行,或默认情况下独立的内联行,均失败。证据缺口:没有测试在 InputGroup 之外传入 layout="inline"。 |
audit:SelectorOption/layout |
| FR3 | Selector.test.tsx "让窄列表收缩某个选项,使其标签能够省略显示" |
窄列表中的默认选项 | 若缺少 selector-option 行,或最小宽度非零,则失败。证据缺口:没有测试断言 padding 和 radius 的重置,或行上的 xstyle、className 和 style。 |
audit:SelectorOption/theming |
| ORD1, ORD2, PR1, AR1 | ORD1 由 FR2 行覆盖。证据缺口:没有测试断言 ORD2、PR1 或装饰性图标 | — | — | audit:SelectorOption/behavior |
| FR4 | 证据缺口:没有测试,与 FR4 缺口一致 | — | — | audit:SelectorOption/api |
| RTL 关系 | RTL 审计整理的 D2 目标(apps/storybook/rtl-audit/targets.json),对应 Selector / With icons(弹出菜单已打开) |
打开选项中的图标和标签;LTR 与 RTL | 选项图标若不在其标签的行内起始位置,则 D2 失败。 | audit:SelectorOption/i18n-rtl |
当前状态影响¶
- 无 ref 或 DOM props(FR4)。 SelectorOption 既不接受
ref,也不接受其他 DOM props,这违反了architecture:public-component-api的 INV5 和 INV8。
决策日志¶
无组件级决策。
未决问题¶
无。
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx