跳转至

异步选项源状态

意图

使用 Selector 或 MultiSelector 的用户应能使用调用方提供的每一个选项,包括在字段值正在解析或保存期间。当没有选项可用时,控件应传达选项源是仍在 pending 还是已完成为空,而不是呈现一个静默的、看似可操作的选择器。

非目标

  • 重新定义 input 类组件的 isLoading;它仍然是值解析或保存状态。
  • 为初始选项源 pending 状态选择公共 API 的名称或形式。
  • 定义失败、重试、分页、缓存或过期响应排序。
  • 更改 Typeahead 组件自有的异步搜索生命周期。
  • 在本规范 pull request 中实现 Selector 或 MultiSelector 行为。

需求

  • FR1 — 提供的选项决定可用性。 提供给 Selector 或 MultiSelector 的规范化选项决定了哪些选项可以被渲染和选择。
  • FR2 — 输入加载不会抑制选项。 输入 isLoading MUST NOT 隐藏、禁用或以其他方式使已提供的选项不可用。当字段值忙碌时,搜索和键盘导航 MUST 基于同一组已提供的选项进行操作。
  • FR3 — 已提供选项为零意味着无可选状态。 当规范化后的已提供集合不包含任何可选项时,选择器 MUST NOT 提供暗示存在可选项的激活或导航。
  • FR4 — 初始 pending 是显式的。 初始选项源 pending 状态 MUST 被独立提供。它 MUST NOT 从零选项或输入 isLoading 推断得出。
  • FR5 — pending 不会产生虚假的空态或只读声明。 当已提供选项为零时,显式的初始 pending 仍然没有可选项,但它 MUST 被呈现并播报为加载中,而不是已完成空态或只读。当存在已提供选项时,pending 来源信号 MUST NOT 覆盖 FR1 或 FR2。
  • FR6 — 已完成空态是只读且显式的。 当已提供选项为零且没有显式初始 pending 状态时,选择器是只读的,且没有可选项。其可见状态和编程式状态 MUST 传达该完成状态,而无需用户激活不可用的弹出层。
  • FR7 — 加载中、只读和空态保持可区分。 视觉输出、无障碍语义、焦点行为和播报 MUST 在以下情况中保持一致:初始 pending、已完成空态,以及输入 isLoading 为 true 且存在已提供选项时。从初始 pending 到已完成空态的转换 MUST 播报一次新的结果,且不丢失控件的可访问名称或当前值。

平台支持

  • 支持的功能/引擎基线:与 Selector 和 MultiSelector 相同的浏览器和辅助技术支持。
  • 不支持的行为:输入 isLoading MUST NOT 被用作回退的选项源信号。
  • 浏览器证据:加载中、只读和已完成空态需要在真实浏览器中进行键盘和无障碍树验证;仅 DOM 断言不足够。屏幕阅读器观察是建议在 spec:AST-009 下进行的后续工作,而不是合并或发布要求。

当前状态影响

  • Selector 和 MultiSelector 目前已经在输入 isLoading 为 true 时保持非空的已提供选项可渲染、可通过键盘到达且可被选择。这满足 FR1 和 FR2;实现 MUST 保留这一点。
  • 输入 isLoading 目前会抑制空状态和无结果状态的呈现,以及搜索结果计数播报。源码注释和消费者 API 文本将该抑制描述为选项尚未到达,尽管该标志本身表示值解析或保存。
  • 两个组件都没有暴露显式的初始选项源 pending 状态。在零选项且没有输入加载的情况下,每个组件仍提供一个可操作的触发器,打开的是已完成空态内容,而不是只读的无选择状态。
  • family:input-fields/FR5 和 family:input-fields/DEC-2 已经记录输入 isLoading 的已批准含义。本规范收窄了由此产生的针对选择器的零选项、pending 和无障碍需求。
  • architecture:public-component-api 和 spec:AST-002 约束了尚未解决的公共 API,该 API 用于表示显式初始 pending 状态。
  • 实现针对的是 pending API、零选项只读行为和无障碍状态转换。它还会移除错误的选项未到达声明,同时保留已填充选项的可用性。所属组件的契约和消费者文档必须随后链接适用的 AST-001 决策;在该工作落地之前,component:Selector 仍然是已发布 Selector 行为的唯一事实来源。

验证

契约 验证 代表性状态 变更或失败预期
FR1, FR2 Selector 和 MultiSelector 交互测试 已填充选项且输入 isLoading;已搜索和未搜索;指针和键盘 某个已提供选项因字段值忙碌而消失、变得不可达或无法被选择
FR3, FR5, FR6 状态转换和激活测试 初始 pending 时零选项;从 pending 到已完成空态;无 pending 时零选项 控件提供了不存在的选择、在 pending 期间声称已完成空态、或在完成之后仍持续呈现加载中
FR7 真实浏览器中的键盘与无障碍树测试;建议后续进行屏幕阅读器测试 初始 pending、已完成空/只读、输入的 isLoading 期间保持已填充、已有选中值 可见状态与播报状态不一致;焦点丢失;名称/值消失;或状态过渡无声或被重复播报
Public API 在 OQ1 解决后进行类型层测试与消费者示例测试 省略/默认状态、显式初始 pending、动态完成 零选项或输入的 isLoading 静默替代了选项源的显式状态

决策日志

DEC-1 — 提供的选项在输入值加载期间保持可用

参考: spec:AST-001/DEC-1 决策者: cixzhang, 2026-08-31

Selector 和 MultiSelector 根据调用者提供的选项来确定选项的可用性。输入的 isLoading 描述的是值的解析或保存,并不会抑制这些选项。

已否决:将输入的 isLoading 视为独立提供的选项尚未到达的证据,因为这会使有效选项不可用,并将两个不相关的状态混为一谈。

DEC-2 — 零选项是无选择状态,而非待处理工作的证据

提供的选项为零意味着没有可选选项;一旦选项源不再显式 pending,选择器即为只读,并传达已完成为空。初始 pending 是一个独立的显式状态:它没有可选选项,但传达加载中,且 MUST NOT 从空数组推断得出。

已否决:用零选项这一单一观察结果同时表示“仍在加载”和“已完成且无选项”,因为用户和辅助技术无法区分等待中的控件与已结束的只读控件。

未决问题

  • OQ1 — 什么公共 API 表示 Selector 和 MultiSelector 的显式初始选项源 pending? (human-api) 该 API 必须区分 pending 与已完成空状态,且不得更改输入的 isLoading,也不得覆盖所提供选项的可用性。

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