跳转至

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