跳转至

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:SegmentedControl FR5 下发生截断的带标签 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)。 带标签的 sm segment 若发生截断,可收缩到 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