只读选择输入¶
意图¶
用户应当能够查看并提交一个因策略或权限而无法更改的已选值。Selector 和 MultiSelector 应当以只读而非禁用形式暴露该状态,而不是提供一个无法更改值的菜单。
非目标¶
- 在本变更中为每个 input-family 成员添加只读行为。
- 不改变 disabled、disabled-reason、loading、validation 或 option-source 状态。
- 不添加只读说明文本或 tooltip API。
- 不改变已选值渲染、选项渲染或表单序列化。
需求¶
- FR1 — 只读保留值。 使用
isReadOnly时,当前值 MUST 保持全不透明度可见、可按常规 Tab 顺序聚焦,并包含在表单提交中。它 MUST NOT 调用onChange或changeAction。 - FR2 — 只读不暴露选择面。 指针、键盘、typeahead、搜索和
isDefaultOpenMUST NOT 在只读状态下打开或渲染 Popover 或 BottomSheet 选择面。 - FR3 — 不存在编辑性可操作提示。 清除操作和展开指示符在只读状态下 MUST NOT 渲染。状态和 busy 呈现保持独立,因为它们描述的是被保留的值,而非可用的编辑操作。
- FR4 — 无障碍与行为一致。 可聚焦的只读值 MUST 保留
combobox语义,暴露aria-readonly="true"和aria-expanded="false",并保留其无障碍名称和渲染值。当不存在选择面时,它 MUST NOT 暴露aria-controls或aria-activedescendant。combobox 角色的隐式 listbox 弹层描述该控件的选择能力;aria-readonly传达当前无法更改该值。当受支持的无障碍树未在触发器的宿主元素上映射该 ARIA 属性时,本地化的无障碍描述 MUST 额外声明只读状态。启用搜索的和非搜索的 selector 使用相同的只读 combobox 语义,因为两者在此状态下都不暴露搜索或选择面。 - FR5 — 禁用优先。 当
isDisabled和isReadOnly同时为 true 时,禁用的焦点、交互、外观、无障碍和表单提交行为优先。 - IR1 — 公共 API 遵循输入组件约定。 Selector 和 MultiSelector MUST 使用既有的可选
isReadOnly布尔值,并在其根目标上暴露现有的readonly主题状态。 - IR2 — 只读不是禁用的绘制样式。 实现 MUST NOT 为只读状态复用禁用的不透明度或禁用表单行为。它们 MAY 移除会错误暗示可编辑性的悬停、按下和指针提示。
平台支持¶
- 支持的特性/引擎底线:Astryx Core 所支持的每一种浏览器与辅助技术组合。
- WCAG 基线:WCAG 2.2 SC 4.1.2 要求控件的名称、角色、值和状态可通过编程方式确定。保留的
combobox角色、渲染值和aria-readonly="true"状态在不改变控件程序化标识的前提下满足该约定。 - ARIA 约定:WAI-ARIA 1.2 支持在
combobox上使用aria-readonly,并将只读定义为用户可以读取但不能设置的值。combobox 具有隐式的aria-haspopup="listbox";即使只读交互从不打开选择面,该能力元数据仍然有效。 - 浏览器证据:DOM 检查 MUST 暴露
aria-readonly="true",且不得暴露任何不存在的受控表面。Chromium 无障碍检查 MUST 暴露一个可聚焦、已折叠的 combobox,并具有正确的名称和渲染值;其隐式弹层仍为listbox,并且其无障碍描述 MUST 声明本地化的只读状态,因为 Chromium 不会在按钮宿主上映射aria-readonly。指针和键盘探针 MUST 确认没有选择面打开,也没有值发生变化。
当前状态影响¶
- TextInput、TextArea、NumberInput、CheckboxInput 和 CheckboxList 已将
isReadOnly确立为可见、可聚焦、不可编辑值的 input-family 名称。 - Selector 和 MultiSelector 目前仅暴露禁用状态。它们的触发器可以打开选择面,清除操作可以改变值,并且它们的表单载体仅在被禁用时移除。
- 调用方负责判断所选值是否被策略或权限锁定;组件无法从值、选项、加载状态或布局中推导出这一区别。因此,该 prop 满足
spec:AST-002的公共 prop 准入要求。 - 实现应在同一个 pull request 中更新这两个组件的契约、使用方文档、针对性测试和主题状态元数据。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1, FR5 | 焦点、回调和表单参与测试 | 只读;禁用;两者同时;单个和多个值 | 只读值发生改变、离开 Tab 顺序、未能提交、变暗,或者覆盖禁用行为 |
| FR2, FR3 | 指针/键盘/typeahead 与 DOM 可操作提示测试 | popover、bottom sheet、adaptive、search、clear、default-open | 只读触发器打开或渲染了选择面、清除了值,或显示了展开指示符 |
| FR4 | DOM 与真实浏览器无障碍检查 | 搜索与非搜索触发器;独立使用与 InputGroup | 值改变了角色、丢失其名称/值/只读状态、显示为展开,或指向不存在的受控表面 |
| IR1, IR2 | 主题状态与渲染样式测试 | input 与 ghost 变体 | 根元素省略 data-readonly、获得禁用不透明度,或保留交互式悬停/按下提示 |
决策日志¶
DEC-1 — 选择输入沿用既有的只读契约¶
参考: spec:AST-011/DEC-1
决策者: cixzhang, 2026-08-31
当调用方拥有一个必须保持可见并随表单提交、但不能被更改的值时,Selector 和 MultiSelector 接受 isReadOnly。只读控件保持可聚焦,保留其 combobox 身份,将其渲染内容作为值暴露,并发布 aria-readonly="true",同时选择与编辑的交互提示均不存在。
保留的角色遵循 WCAG 2.2 SC 4.1.2 中关于稳定的程序化名称、角色、值和状态的契约,以及 WAI-ARIA 1.2 对 combobox 上 aria-readonly 的明确支持。MUI Select
和 React Aria ComboBox
使用了相同的形态:只读 combobox 仍然可被识别为 combobox,但指针和键盘打开操作均被阻止。隐式的 listbox 弹出层描述的是该控件的选择能力;它并不承诺每个状态都能打开它。
已拒绝的做法:将此状态映射为 isDisabled,因为禁用值会被淡化并从表单提交中排除。
未解决的问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx