跳转至

清除值系统规范

{
  "paths": ["packages/core/src/Selector/**"]
}

意图

清除 Selector 会将其返回到起点,而由调用方指定该起点是什么。起始点为“Everyone”的筛选器会清除为“Everyone”,而不是空白字段。代表该起点的行在搜索缩小范围时仍保留在列表中,因此用户始终可以从列表本身回到起点。

成员

本规则仅适用于 Selector。其值类型为 string,其清除选项(FR4)是 value 为 clearValue 的选项,相等性为字符串相等。family:input-fields 的其他每个成员,包括 Typeahead、Tokenizer、MultiSelector 和 ComplexSelector,都保持普通的布尔值 hasClear,且没有 clearValue。

非目标

  • 与清除分离的重置概念。只有一个清除职责、一个对应 prop,hasClear 的 clearValue 指明其落点。
  • 默认值或非受控模式。Selector 是受控组件,没有 defaultValue。
  • 搜索匹配与查询规范化。spec:AST-056 FR4 负责匹配的基线。
  • 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:Selector FR1)。清除按钮的焦点返回行为与当前一致。
  • FR6 — 禁用、只读、必填和表单保持其原有含义。 当 Selector 被禁用或只读时,清除仍然不可用(component:Selector FR6)。空的 clearValue 会像今天空值一样无法通过 isRequired 验证;非空 clearValue 则不会。使用 htmlName 时,清除后提交的值为 clearValue。

无障碍契约

  • AR1 — 名称和状态。 清除选项的无障碍名称是其标签,并且当值等于 clearValue 时,其选中状态会被暴露。清除按钮的无障碍名称和工具提示保持不变(family:input-fields FR11)。
  • 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