SegmentedControlItem 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 无变更。SegmentedControlItem 接受 value、label、isLabelHidden、icon、isDisabled 以及基础 props,并且必须位于 SegmentedControl 内部。 |
| 行为 | 一个分段:<button role="radio"> 带 aria-checked。点击,或在聚焦的分段上按空格或回车,会选中它,除非它已被选中、已禁用,或调用方的 onClick 阻止了默认行为。 |
| 终端用户影响 | 用户会看到选中的分段凸起且加粗,并可通过一次点击选择另一项。仅图标的分段仍有名称。已禁用的选中分段保留 Tab 停靠点。 |
| 构建者影响 | 无。 |
| 兼容性/就绪状态 | 记录已发布的行为;无 API、默认值或 DOM 变更。调用方的 onClick 在禁用状态下仍会运行,调用方的 className 会被替换,分段保持固定高度,截断的 sm 分段宽度可小于 24 px;这些均列在“当前状态影响”之下。 |
| 审查检查 | 拒绝以下情况:没有名称的分段、选择已禁用分段的点击、在选中或禁用分段上的按下绘制,或丢失强制颜色模式选中状态。 |
| 治理规则 | component:SegmentedControl;WAI-ARIA 单选按钮模式;spec:AST-020 FR9、FR15、DEC-5;spec:AST-085 FR1、FR2;spec:AST-102 FR4;design:user-states DR1–DR3(按下覆盖层、禁用时不响应、选中分段例外);architecture:public-component-api INV5、INV6;WCAG 1.4.11。 |
此表是审查投影;以下正文为权威内容。
意图¶
SegmentedControlItem 是 SegmentedControl 中的一个选项。它负责该分段的单选语义、点击选择、命名、标签与图标渲染、项目禁用状态,以及分段的绘制。使用者用法见 SegmentedControlItem.doc.mjs。
兼容性与迁移¶
- 已发布的默认行为保留:
yes;标签可见、已启用 - 兼容性类别:记录已发布的行为;无公共 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:由父级的
value控制 - 迁移决策:无
使用者的迁移说明属于使用者文档和发布说明。
所有权边界¶
拥有
- 分段按钮、其单选角色、选中和禁用状态以及名称。
- 点击选择与
onClick组合。 - 标签与图标渲染、截断,以及按尺寸和状态的分段绘制。
不拥有 / 非目标
- Tab 停靠点、方向键导航、焦点跟随选择、组禁用状态以及主题解剖映射——由
component:SegmentedControl拥有。segmented-control-item目标在 SegmentedControl 的使用者文档中声明,并在其记录中映射。 - 图标美术资源——由调用方拥有。
- 在 SegmentedControl 之外使用——不支持。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 值 | string | 该分段选择的值。 | 始终。 | 必填 | component:SegmentedControlItem |
稳定 | TypeScript 会拒绝缺失的值。 |
| 标签 | string;可见或隐藏 | 可见文本,或仅图标分段的名称。 | 始终。 | 可见 | component:SegmentedControlItem |
稳定 | TypeScript 会拒绝缺失的标签。 |
| 禁用 | off、item、group | 阻止选择。 | 始终。 | off | component:SegmentedControlItem |
稳定 | 不适用。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| FR1 | 每个 segment 渲染一个 <button type="button" role="radio">;当它的 value 等于组值时,aria-checked 为 true,它还会提供 data-value,并且 segmented-control-item 目标反映 data-size、data-selected 和 data-disabled。转发的 prop 不能覆盖该 role。 |
WAI-ARIA 单选模式;当前源码和测试 |
| FR2 | 一次点击(包括聚焦的 segment 上通过 Space 或 Enter 触发的点击;即原生按钮激活;spec:AST-020 FR15)首先运行调用方的 onClick;除非它阻止了默认行为,否则一个已启用且未选中的 segment 会将其 value 传给组的 onChange。点击已选中的 segment 不会执行任何操作。调用方的 preventDefault() MUST 否决每一次按下。 |
spec:AST-020 FR15;当前测试 |
| FR3 | 该 segment 渲染其图标(按 segment 尺寸缩放),后跟其标签。当设置 isLabelHidden 时,标签不渲染并成为 aria-label,且 segment 不会收缩。当 segment 比可见标签更窄时,标签会以省略号截断。 |
当前测试 |
| FR4 | 由自身的 isDisabled 或由组禁用的 segment 会设置 aria-disabled,拒绝选中,显示禁用状态的文本颜色,并且不显示悬停或按下效果。已禁用但选中的 segment MUST 保留 Tab 停留点(spec:AST-085 FR1);对于没有匹配任何 segment 的值,component:SegmentedControl FR2 会放置停留点。实现缺口:在禁用的 segment 上,调用方的 onClick 仍会运行(spec:AST-085 FR2)。 |
spec:AST-085 FR1, FR2;当前测试 |
| FR5 | 选中的 segment 会绘制带有低阴影和半粗体主要文本的凸起表面;在强制颜色模式下,它使用 Highlight 绘制,并以 HighlightText 作为文本。未选中的启用 segment 绘制共享的悬停色调,并在 design:user-states DR1 和 DR2 下绘制按下叠加层;选中的 segment 在按下期间保持其凸起表面,且不显示按下叠加层(DR3);在触摸呈现下,该表面会抬起(component:SegmentedControl FR14)。 |
WCAG 1.4.11;design:user-states DR1–DR3;当前测试 |
| FR6 | 分段高度是尺寸对应的元素高度减去 4 CSS 像素所得的最小值(24、28 或 32);在 spec:AST-102 FR4 下,该最小值随设定的文本大小增长(实现差距:高度是固定的)。圆角与控制件同心;sm 使用辅助文本和更紧凑的内边距。键盘焦点绘制共享的焦点轮廓。 |
architecture:interaction-modality INV1;当前来源;spec:AST-102 FR4 |
| FR7 | 分段拥有 role、aria-checked、aria-disabled、aria-label(当标签隐藏时由标签设置)、tabIndex、type、data-value 和 data-size,并在相应的状态中写入 data-selected、data-disabled 和按压标记 data-astryx-pressable;调用方为组件自有属性提供的值会被替换,而调用方的 data-selected、data-disabled 或 data-astryx-pressable 则在不处于该状态的分段上透传。ref、其他 data-*、style、其他 ARIA 属性(如 aria-describedby)以及其他基础属性都会传递到按钮;xstyle 最后合成。调用方的 className MUST 与组件的类合成(architecture:public-component-api INV5、INV6)。实现差距:组件的合并类会替换调用方的 className。 |
architecture:public-component-api INV5、INV6;当前测试 |
允许的变化¶
- AV1 — 内容。 标签文本和图标在其类型范围内变化。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 未选中 | aria-checked="false";悬停和按压叠加层。 |
图标。 |
| 已选中 | aria-checked="true";凸起;加粗;强制颜色模式下高亮。 |
— |
| 仅图标 | 由 aria-label 命名;不收缩。 |
— |
| 禁用 | aria-disabled;无绘制反馈;不可选中。 |
单项或整组。 |
变换与优先级顺序¶
- ORD1 — 点击。 先执行调用方的
onClick,然后执行选择逻辑,除非事件被阻止、组件已禁用或已选中。
性能与资源¶
- PR1 — 有界资源。 自身没有状态、效果或监听器;按压反馈共享按压控制器的窗口和文档监听器。
无障碍契约¶
- AR1 — 单选语义。 每个分段都公开单选角色、选中状态、禁用状态和名称(FR1、FR3)。
- AR2 — 目标尺寸。 最小分段的高度为 24 CSS 像素。在
component:SegmentedControlFR5 下发生截断的带标签sm分段,其宽度可能缩小到 24 CSS 像素以下,未达到 WCAG 2.5.8(实现差距)。 - AR3 — 非颜色状态。 FR5。
设计关系¶
| 结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 分段 | 透明按钮;选中时表面凸起。 | 当前来源 | 突出 | FR1、FR5、FR6 |
| 标签 | 中等文本;选中时半粗;截断。 | 当前来源 | 突出 | FR3、FR5 |
| 图标 | 调用方的图形按分段尺寸调整。 | 当前来源 | 辅助 | FR3 |
这些部件的目标映射位于 component:SegmentedControl 的主题结构中。
家族与系统关系¶
component:SegmentedControl提供值、尺寸、布局和整组禁用状态,并负责键盘导航。spec:AST-085负责禁用状态的可聚焦性;FR4 记录了该差距。design:user-states负责按压处理。
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | SegmentedControl.test.tsx 的 aria-checked 与 data-testid 用例;RadioGroup.a11y.test.tsx 和 RadioGroup.a11y.chromium.spec.ts(位于 RadioList/__tests__)中的 segmented-option-* 状态 |
选中变化;data-testid | 过期的 aria-checked 会失败。证据缺口:没有测试向 segment 传入 role;role 覆盖用例只覆盖了 radiogroup。 |
audit:SegmentedControlItem/accessibility |
| FR2 | SegmentedControl.test.tsx 的点击与 onClick 组合用例;SegmentedControl.interaction.browser.spec.ts 中针对点击和拖拽的 click-commit 与否决用例 |
点击;点击已选中项;被阻止的点击 | 点击已选中项或被阻止的点击若触发选中则会失败。焦点已在组内时按下并越过否决而触发选中也会失败。 | audit:SegmentedControlItem/behavior |
| FR3 | SegmentedControl.test.tsx 的图标、仅图标和截断用例 |
图标与标签;仅图标;长标签 | 缺少名称,或图标发生截断,都会失败。 | audit:SegmentedControlItem/anatomy |
| FR4 | SegmentedControl.test.tsx 的禁用用例;RadioGroup.a11y.test.tsx 和 RadioGroup.a11y.chromium.spec.ts(位于 RadioList/__tests__)中的 segmented-option-disabled 与 segmented-option-group-disabled* 状态 |
单项禁用与整组禁用 | 被禁用的 segment 若触发选中则会失败。证据缺口:没有测试断言禁用态的文字颜色、无悬停绘制,或禁用状态下调用方的 onClick。segmented-option-group-disabled 状态声明了一个已选中、整组禁用但仍保留 Tab 停靠点的 segment。 |
audit:SegmentedControlItem/accessibility |
| FR5 | SegmentedControl.test.tsx 的 forced-colors 与按下状态用例;PressedState.a11y.chromium.spec.ts 的 segmented-control 用例 |
强制颜色下的选中;按下;禁用 | 丢失 forced-colors 状态,或在被禁用的 segment 上绘制按下效果,都会失败。证据缺口:没有测试断言凸起的选中表面或悬停色调。 | audit:SegmentedControlItem/visual |
| FR6, FR7 | 证据缺口:没有测试 segment 高度、文本增长、焦点轮廓、ref 或 xstyle 顺序 |
— | — | audit:SegmentedControlItem/layout |
| RTL 关系 | RTL 审计精选的 D2 目标(apps/storybook/rtl-audit/targets.json),对应 SegmentedControl / With icons |
segment 的图标与标签;LTR 与 RTL | 图标若不在其标签的行内起始位置,则无法通过 D2。 | audit:SegmentedControlItem/i18n-rtl |
当前状态影响¶
- 窄目标(AR2)。 带标签的
smsegment 若发生截断,可收缩到 24 CSS px 宽度以下,不满足 WCAG 2.5.8。 - 调用方 className(FR7)。 segment 上的调用方
className会被组件自身的类替换,违反architecture:public-component-api的 INV5 和 INV6。 - 禁用状态下调用方 onClick(FR4)。 被禁用的 segment 仍会执行调用方的
onClick,违反spec:AST-085的 FR2。 - 固定高度(FR6)。 segments 使用固定高度,而非随设置的文本大小增长,违反
spec:AST-102的 FR4。
决策日志¶
无组件本地决策。
未决问题¶
无。
内容边界¶
本文件不重复使用方属性表/示例、当前审计结果、实施步骤或家族/系统规则。它链接到这些内容的所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx