跳转至

可聚焦的禁用控件系统规格

意图

键盘和屏幕阅读器用户始终能够到达被禁用的控件。他们可以找到它,听到它已被禁用,并在存在原因时读到原因。当他们所处的控件变为禁用时,他们永远不会丢失当前位置。

构建者继续使用 isDisabled。Astryx 组件将其转化为可聚焦但不可操作的控件。任何组件都不渲染原生 disabled 属性。

非目标

  • 在复合组件(listbox、menu、grid、tablist、roving group)内,箭头键访问哪些项目。由复合组件自身的记录决定。
  • 只读。spec:AST-011 将只读与禁用区分开。
  • 禁用态绘制、tokens 和主题状态。它们继续由当前所有者负责。
  • 调用方在 Astryx 插槽内渲染的元素。调用方负责它们的属性。
  • 满足此契约的等效内部实现仍然有效。

需求

  • FR1 — 禁用控件保持可聚焦。 组件 MUST NOT 在其渲染的任何元素上放置原生 disabled 属性。禁用控件暴露 aria-disabled="true",并保持启用时已有的焦点顺序:Tab 停留点仍是 Tab 停留点,带 tabIndex={-1} 的元素仍然不在 Tab 顺序中。
  • FR2 — 禁用阻止一切变更。 禁用控件 MUST NOT 更改其值、激活、导航、打开浮层、调用回调或 Action。这涵盖指针、触摸、Enter、Space、键入、粘贴、放置、拖拽、滚轮、递增和选择路径。
  • FR3 — 禁用值不参与提交。 禁用字段不向表单提交提供任何值,也不会通过约束验证阻止提交。这与原生 disabled 表单行为一致。
  • FR4 — 变为禁用时保持焦点。 在持有焦点时变为禁用的控件继续持有焦点。组件 MAY 改为在变更之前将焦点移动到其自身记录中指定的、位于同一组件内的目标。当组件移除一个已聚焦控件时,该组件的记录会指定目标。
  • FR5 — 禁用状态会被播报。 禁用状态与可访问名称、任何描述或禁用原因一起,在可聚焦元素本身上暴露给辅助技术。当聚焦的控件变为禁用时,该元素上会暴露这一变更;是否被语音读出遵循 spec:AST-009。
  • FR6 — 禁用状态在视觉上保持惰性。 禁用绘制应用于禁用状态。处于忙碌但未禁用的控件保持其 pending 处理(family:buttons FR4),即使它也暴露了 aria-disabled。悬停、按压和拖拽的视觉示意 MUST NOT 出现。在键盘模态下仍会显示焦点指示器(architecture:interaction-modality INV1、INV5)。
  • FR7 — 组禁用遵循同一规则。 由组或表单级默认设置禁用的成员遵循 FR1–FR6。

平台支持

  • 支持的特性/引擎下限:包所支持的浏览器。
  • 不支持的行为:无。该规则使用标准 ARIA 和事件处理。
  • 浏览器证据:键盘焦点顺序和阻止激活需要真实浏览器检查;FR5 需要无障碍树证据。语音输出仅当声明依赖于它时才遵循 spec:AST-009。

当前状态影响

  • family:buttons FR3 从“MAY 使用可聚焦的 aria-disabled”改为“遵循 spec:AST-085”。Button 在忙碌和 tooltip 场景中已经如此。
  • family:input-fields FR4 对每个成员都得到满足。“足够可聚焦”变成“可聚焦”。
  • component:DateRangeInput AR3 及其禁用预设状态,以及 component:Tokenizer 的禁用状态和验证,遵循本记录而不是原生 disabled。它们中断言原生 disabled 的测试待符合性更新。
  • component:Slider AR1:没有 message 的禁用 thumb 获得 Tab 停留点;其禁用 thumb 的测试待符合性更新。
  • component:Selector:带有原因的禁用触发器与所有禁用触发器一样,保持其 Tab 停留点。
  • 那些将禁用控件描述为原生禁用、不可聚焦、不在 Tab 顺序中、会丢失焦点、或吞掉外部 Tooltip 所需事件的使用方文档,将随一致性工作一起变更。本记录的 affects_consumer_docs 列表逐一列出它们。
  • BaseTypeahead 的公共 isFocusableDisabled 不再有剩余作用:每个禁用输入都可聚焦(FR1),并且禁用时 Enter 无法选择(FR2)。在 spec:AST-002 下的公共 API 变更将其移除之前,它仍被接受。
  • useIndicatorFocusRing:其 isDisabled 输入会抑制键盘焦点环。在 FR6 下,已聚焦的禁用控件仍会显示它。
  • family:buttons 和 component:Tokenizer 中断言原生 disabled 的测试待符合性更新。
  • 针对 ClickableCard、BaseTypeahead、CheckboxInput、ChatComposer 和 CommentPin 的草稿记录将原生 disabled 描述为观察到的行为;它们将随一致性工作一起变更。
  • spec:AST-011 DEC-1 的被拒绝行不再说禁用值会离开 Tab 顺序。
  • spec:AST-011 FR5 仍然成立:禁用状态的焦点、提交和绘制仍然优先于只读。
  • 当前渲染原生 disabled 的组件切换到 FR1 形态。文本字段使用只读加变更守卫,正如 TextInput 在带禁用原因时所做的。带有表单值的字段将其从提交中排除(FR3)。
  • Pagination、Calendar、Lightbox 和触屏日期选择器不再在各自边界处将焦点丢到页面主体上(FR4)。
  • 使用 :disabled 选择禁用控件、使用 toBeDisabled() 查询它们、或依赖 Tab 跳过禁用控件的使用方会看到变化。发布说明会指明这一点。

验证

契约 验证 代表性状态 变更或失败预期
FR1 每个组件的禁用场景的共享测试 按钮、文本字段、复选框、开关、选择器、滑块、组禁用 任何渲染出的 disabled 属性,或 Tab 顺序的改变,均失败
FR2 针对每个组件的键盘、指针、粘贴和拖放测试 组件支持的每种变更路径 值变更、激活、导航或回调未发生,则失败
FR3 读取 FormData 的表单提交测试 禁用的文本、复选框、选择器、必填且禁用的字段 提交了禁用的值,或提交被阻止,则失败
FR4 真实浏览器中的焦点转换检查 Pagination 最后一页、Calendar 最大月份、Lightbox 最后一项、组关闭 焦点落在文档 body 上,则失败
FR5 无障碍树检查 带与不带禁用原因的已聚焦禁用控件 缺少禁用状态、名称或原因,则失败
FR6 真实浏览器中的计算样式检查 禁用控件处于静止、悬停、按下、键盘焦点状态 悬停或按下时的绘制,或缺少焦点指示器,均失败

决策日志

DEC-1 — 禁用控件可聚焦;不使用原生 disabled

参考: spec:AST-085/DEC-1 决策者: cixzhang, 2026-10-21

原生 disabled 会将控件从焦点中移除。键盘用户将无法找到它,无法获知它为何不可用,并且当他们所处的控件变为禁用时会失去当前位置。为每个禁用控件提供一种可聚焦的形态,可消除全部三类失败,同时组件保留相同的 isDisabled API。

已否决:当控件变为禁用时,将焦点移动到组件自行选择的回退目标——每个组件都需要各自的目标位置,而且焦点仍然会跳跃。

未决问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx