清除值系统规范¶
意图¶
清除 Selector 会将其返回到起点,而由调用方指定该起点是什么。起始点为“Everyone”的筛选器会清除为“Everyone”,而不是空白字段。代表该起点的行在搜索缩小范围时仍保留在列表中,因此用户始终可以从列表本身回到起点。
成员¶
本规则仅适用于 Selector。其值类型为 string,其清除选项(FR4)是 value 为 clearValue 的选项,相等性为字符串相等。family:input-fields 的其他每个成员,包括 Typeahead、Tokenizer、MultiSelector 和 ComplexSelector,都保持普通的布尔值 hasClear,且没有 clearValue。
非目标¶
- 与清除分离的重置概念。只有一个清除职责、一个对应 prop,
hasClear的clearValue指明其落点。 - 默认值或非受控模式。
Selector是受控组件,没有defaultValue。 - 搜索匹配与查询规范化。
spec:AST-056FR4 负责匹配的基线。 hasClear的对象形式不能用于除Selector之外的任何输入:Typeahead、Tokenizer、MultiSelector、ComplexSelector、PowerSearch以及文本、数字、日期、时间和文件输入。- 满足此契约的等效内部实现仍然有效。
- 内部模块、文件、函数名、算法、数据结构、存储布局、清单、日志、锁、事务协议以及 CI 作业/工作流拓扑属于架构或实现范畴,除非调用方或互操作系统有意图地将该确切机制作为公开协议依赖。若是这种情况,需说明谁依赖它,以及为什么等效实现无法满足该契约。
公开契约¶
<Selector
label="Owner"
hasClear={{clearValue: 'all'}}
hasSearch
value={owner} // string, never null
onChange={setOwner} // (value: string) => void
options={[
{value: 'all', label: 'Everyone', icon: UsersIcon},
{type: 'divider'},
...owners,
]}
/>
要求¶
- FR1 —
hasClear={{clearValue}}是清除的落点。Selector的hasClear接受boolean | {clearValue: string}。true的行为与当前一致:清除报告null。对象形式开启清除,并让所有清除路径通过onChange和changeAction报告clearValue:触发器的清除按钮、触发器上的 Delete 和 Backspace,以及选择清除选项(FR4)。false和缺省保持其当前含义。 - FR2 — 类型跟随对象形式,现有调用方不变。 使用
hasClear={{clearValue}}时,value、onChange和changeAction接受string且不含null。当hasClear为true、false或缺省时,类型保持与发布时完全一致,包括hasClear下的null。 - FR3 — 在清除值处没有可清除的内容。 当值等于
clearValue时,触发器的清除按钮被隐藏,正如当前值为空时它被隐藏一样。触发器像显示任何值一样显示该值:该选项的标签和图标,并且不显示placeholder。 - FR4 — 清除选项保留在列表中。
value等于clearValue的选项即为清除选项。搜索永远不会隐藏它,包括在没有任何匹配的查询中,此时空搜索消息在其之后渲染。它不是结果:结果计数播报和空搜索状态只计算匹配项。当查询处于活动状态时,默认高亮落在第一个匹配项上,绝不会落在清除选项上,因此 Enter 不会意外选中它;方向键可以到达它。它保留调用方在顶层条目中的位置。如果clearValue不匹配任何选项,则不会固定任何内容,并在开发环境中发出警告。 - FR5 — 选择清除选项就是选择一个值。 它使用选项行的结构、尺寸、按压模型、触摸目标、主题目标和呈现方式,并且触发器收起状态下的键入查找会匹配其标签。选择它会关闭浮层并将焦点返回到触发器(
component:SelectorFR1)。清除按钮的焦点返回行为与当前一致。 - FR6 — 禁用、只读、必填和表单保持其原有含义。 当
Selector被禁用或只读时,清除仍然不可用(component:SelectorFR6)。空的clearValue会像今天空值一样无法通过isRequired验证;非空clearValue则不会。使用htmlName时,清除后提交的值为clearValue。
无障碍契约¶
- AR1 — 名称和状态。 清除选项的无障碍名称是其标签,并且当值等于
clearValue时,其选中状态会被暴露。清除按钮的无障碍名称和工具提示保持不变(family:input-fieldsFR11)。 - AR2 — 焦点。 同 FR5:选择清除选项会将焦点返回到触发器,清除按钮保留其现有的焦点返回行为。
- AR3 — 播报。 清除操作不会额外播报:触发器会读出新值,就像任何其他选择一样。
- AR4 — 动效。 这里不会新增任何动效。每个浮层自身的动效和减少动效行为照常适用。
平台支持¶
- 支持的功能/引擎下限:所有受支持的浏览器和渲染器。这里没有任何内容依赖于能力检测。
- 不支持的行为:无。
- 浏览器证据:针对 FR2 的类型测试;针对名称、选中状态、焦点和播报的 DOM 与无障碍树断言;针对弹出层和 BottomSheet 中按压模型的真实 Chromium 交互。
现状影响¶
family:input-fields在其采用表中仅针对Selector列出hasClear的{clearValue}形式,并引用此记录。其他每个成员的hasClear仍为布尔值。component:Selector明确清除选项以及 FR3 的清除按钮规则。Selector的.doc.mjs记录hasClear的对象形式及其类型收窄。Selector保留一条内部清除路径;其当前内部名称不约束公共 prop。
验证¶
| 契约 | 验证 | 代表性状态 | 突变或失败预期 |
|---|---|---|---|
| FR1 | Selector 回调和 Action 套件 |
清除按钮、Delete/Backspace、清除选项;hasClear true 和 {clearValue} |
在对象形式下,任何清除路径返回的不是 clearValue,或在 true 下返回的不是 null |
| FR2 | Selector 类型测试 |
无 hasClear;true;{clearValue} |
对象形式接受 null,或任何已发布的签名在未使用对象形式时发生变化 |
| FR3 | Trigger 渲染套件 | 值等于 clearValue;不同;为空 |
在值为 clearValue 时显示清除按钮,或触发器在该值下显示 placeholder |
| FR4 | 带 live-region 断言的搜索套件 | 无查询;有匹配;无匹配;在搜索输入框中按 Enter;一个没有选项的 clearValue |
该行在查询下被过滤、计数、默认高亮,或被 Enter 选中 |
| FR5 | popover 和 bottom sheet 中的交互套件;真实 Chromium | 指针、触摸、键盘;键入查找 | 该行偏离选项行行为,或焦点落在别处 |
| FR6 | 禁用、只读、必填和表单套件 | 禁用;只读;clearValue 为空和非空时的必填;htmlName |
清除按钮可触达、必填校验有误,或提交的值不同 |
| AR1–AR4 | 无障碍树、焦点和公告断言 | Selector 处于和离开 clearValue |
名称或状态缺失,焦点移到别处,或触发额外的公告 |
已知验证缺口:这些套件均不存在于 main 上。
决策日志¶
DEC-1 — 返回即清除,清除到调用者在 hasClear 上命名的值¶
参考: spec:AST-109/DEC-1
决策者: cixzhang, 2026-10-28
清除已经意味着“回到起点”;hasClear 的对象形式让调用者指定起点在哪里,因此一个职责只保留一个 prop(architecture:public-component-api INV21)。该对象是现有开关上的普通配置,不是解剖设置(INV18),它不增加视觉布尔(INV20),并且在运行时零成本(INV19)。
已拒绝:单独的 reset 值或行,因为它与清除的职责重合。
已拒绝:单独的 clearValue prop,因为两个 prop 会分担同一个职责。
DEC-2 — 清除选项就是持有清除值的选项¶
参考: spec:AST-109/DEC-2
决策者: 待定
该选项已经携带清除值的标签和图标,因此它就是留在列表中的那一行。不存在新的条目类型或 label prop。
已拒绝:在 options 中增加一个专门的清除条目,因为它在持有该值的选项之外第二次命名了清除状态。
DEC-3 — 类型仅随对象形式收窄¶
参考: spec:AST-109/DEC-3
决策者: cixzhang, 2026-10-28
当 hasClear={{clearValue}} 时,Selector 从不报告 null,因此其类型会如此声明。对于任何其他 hasClear 值,一切不变,因此对象形式是附加式的。
DEC-4 — 清除值仅属于 Selector¶
参考: spec:AST-109/DEC-4
决策者: cixzhang, 2026-10-29
hasClear 的对象形式和清除选项属于 Selector,其筛选器从诸如“Everyone”的真实值开始。Typeahead、Tokenizer 以及所有其他输入保留普通布尔 hasClear。PowerSearch 不是选择器。
已拒绝:在整个 selector 家族中推广对象形式,因为只有 Selector 需要让清除落在一个真实值上。
未决问题¶
- OQ1 —
hasClear的对象形式是否扩展到MultiSelector或ComplexSelector?(human-api)在裁定之前,两者都保留普通布尔hasClear。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx