要求异步屏幕具有独占的挂起、成功、错误和空状态,禁止无限旋转的加载指示器,完成时进行通告,并在请求失败时保留用户输入。
包状态: 参考上下文已准备好供人工审核。合约和测试场景已完成,但不保证采用的实现已通过它们。
决策
异步屏幕恰好处于挂起、成功、错误或空状态之一。挂起状态有时间限制:超过 timeout_ms 后,屏幕必须进入带重试的错误状态,绝不允许无限旋转的加载指示器。成功状态在后台重新验证期间可以显示过期数据,带有明显的过期标记且不叠加阻塞性加载指示器。用户发起的加载完成时通告一次。类型化过滤器和草稿必须在错误时保留。状态转换定义在 state-table.yaml 中。
范围
- 获取或变更数据后渲染结果区域的屏幕。
- 超时、过期-重新验证、空与错误、通告。
- 在失败重载时保留进行中的输入。
- 焦点:该区域不会抢占焦点,除非正在提交表单。
不包含内容
- 字段级验证代码和首个无效焦点。
- 破坏性确认文案。
- 流式令牌取消。
合约
- 结果区域暴露一个独占的
status,取值为{pending, success, error, empty}。 - 挂起状态超过
timeout_ms且无成功负载时,变为带有request_timeout的错误状态,并启用重试控件。 - 仅当请求成功且结果集为空时,状态为空;5xx 或网络失败为错误。
- 过期-重新验证保持
status: success且stale: true,且不得用阻塞性加载指示器覆盖区域。 - 用户发起的请求达到成功或错误时,在礼貌的实时区域通告一次;重新验证的周期性请求不通告。
- 用户输入的过滤器和草稿字符串在错误时保留;仅通过显式重置控件清除。
实现
将状态建模为状态机,而非重叠的布尔值。超时后取消请求,防止延迟响应将错误状态切换为成功而无需重试。重新验证时保持之前的成功视图。实时区域只挂载一次。
失败处理
重试时切换到挂起状态,禁用重复重试直至稳定或超时。失败的重新验证不得变为空状态。如果过期时间超过 max_stale_ms,显示错误而非当前视图。
验证
单元测试状态表中的独占状态。捕获超时、空与错误区分、过期覆盖、通告次数和输入保留。测量加载指示器持续时间与 timeout_ms 的关系。执行封装的场景。
本包中的可执行示例为夹具和验收合约。从集合根目录运行 python tools/validate.py 检查包结构和元数据;然后在目标仓库中实现并执行场景。
采用假设
example.yaml中的名称和数值为采用配置文件,不是通用默认值。- 采用团队必须将参与者、数据类别、错误词汇和所有权映射到其系统。