跳转至

共享选择器触发器层级系统规范

意图

构建者可以在工具栏或导航区域中,将 Selector、MultiSelector 或 ComplexSelector 放在控件旁边,而不会让一个选择器看起来像表单字段,另一个却采用不同的层级。Selector 在其当前组件契约中定义了 input、secondary 和 ghost 触发器词汇。MultiSelector 和 ComplexSelector 采用相同的值和角色,因此这三种内置选择器触发器在保持各自的值和弹层行为的同时,传达同一种调用方选择。

所有权边界

component:Selector 拥有 Selector 的封闭触发器值,以及 DD1 中关于其 secondary 触发器与相邻 secondary Button 之间的持久关系。本文档负责 MultiSelector 和 ComplexSelector 对该词汇的采用,以及跨组件要求:三者必须暴露相同的值名称、默认值和静止角色。它们各自的组件记录保留每个选择器的选择、弹层和结构契约。

已发布的 Button 组件拥有自己的变体映射和 secondary 处理;本文档不定义 Button 行为。它要求每个内置选择器的 secondary 触发器在活动主题中与该处理方式相匹配。family:input-fields 拥有由 FR5 和 FR6 提出的布局、状态和 InputGroup 规则,但不会把这一视觉轴添加到每个 input-family 成员上。通用控件层级、确切的主题 token 选择和组件几何结构仍不在本文档范围内。

非目标

  • 将触发器变体添加到另一个 input-family 成员。
  • 替换或削弱 component:Selector/DD1。
  • 更改选择、搜索、弹层、焦点、键盘、表单或无障行为。
  • 要求三种选择器组件之间,或选择器与 Button 之间具有相同的几何结构或逐状态像素。
  • 规定超出 FR2 中默认静止角色之外的确切主题 token。
  • 为调用方渲染的触发器设置样式。通过 renderTrigger 提供的控件在 spec:AST-055 下仍归调用方所有。
  • 满足本契约的等效内部实现仍然有效。

公共概念

概念 封闭值 含义 默认值 所有者 稳定性
内置触发器变体 input、secondary 和 ghost 选择表单字段、secondary Button 或透明低强调触发器外观 input Selector 语义:component:Selector;采用:AST-079 secondary 为新增;其余保持不变

需求

  • FR1 — 每个选择器触发器暴露相同的封闭词汇。 Selector 保留由其组件契约拥有的当前 input、secondary 和 ghost 值。MultiSelector 和 ComplexSelector MUST 接受内置触发器 variant 的相同三个值。每个公共类型、渲染后的 data-variant 反射、variant 视觉属性轴的消费方主题声明,以及暴露此轴的消费方文档 MUST 使用这些相同的名称。其他值会被公共类型拒绝。
  • FR2 — 静止角色是共享的。 静止时,input 呈现不透明、带边框的表单字段表面;secondary 匹配活动主题的 secondary Button;ghost 呈现透明、低强调的触发器。对于所有三个选择器上的 secondary,其静止边框(宽度、样式和颜色)、填充和文字颜色 MUST 与同一主题中 secondary Button 的对应值匹配,并与 component:Selector/DD1 保持一致;在默认主题下,这是一个无边框、中性填充、中等强调的触发器。三种处理 MUST 在静止时保持可区分。component:Selector/DD1 额外拥有 Selector 与相邻 secondary Button 在各状态下的对齐关系。MultiSelector 和 ComplexSelector 可以复用它们现有的共享非 input hover、active、focus-visible、disabled 和 read-only 处理;本文档不要求它们的状态像素与 Selector 或 Button 完全相同。主题可以在保持静止角色的前提下选择具体的 token。Button 组件保留对自身 secondary 处理的所有权。
  • FR3 — 触发器外观不会改变选择器行为。 更改 variant MUST NOT 更改所选值、选项或子项词汇、弹层呈现模式(popover、bottom-sheet 或 adaptive)或浮层语义、键盘模型、焦点归属、表单参与、无障碍名称、角色或值语义。视觉对齐可以跟随所选触发器表面。
  • FR4 — 采用是兼容的。 input 仍然是三个组件的默认值。现有 input 和 ghost 调用方保持其已发布行为。MultiSelector 或 ComplexSelector 的调用方显式选用 secondary;现有调用点无需迁移。Selector 的兼容性仍由其当前组件契约负责。
  • FR5 — 家族宽度和状态规则仍然适用。 在 family:input-fields FR1 下,独立的 Selector 可以跟随其显示内容,而 MultiSelector 和 ComplexSelector MUST 在值变化时保持其可用的内联尺寸。在 family FR8 下,非 input(secondary 或 ghost)触发器上请求的 attached 状态会解析为 detached;状态边框和阴影仍仅限于符合条件的 input 触发器。
  • FR6 — InputGroup 保持连接表面。 Selector 和 MultiSelector 可以在 InputGroup 内使用 secondary。触发器可以保持其中性局部填充,但 MUST 采用组解析后的高度、连接边缘圆角和焦点堆叠,并且 MUST NOT 绘制独立的外边框、阴影或状态处理。在 family:input-fields FR3 下,InputGroup 仍然是连接的外部几何结构的负责人。ComplexSelector 不支持 InputGroup。

平台支持

  • 支持的功能/引擎基线:这三个组件已经支持的所有浏览器和渲染器;该词汇表不引入任何平台特性。
  • 不支持的行为:无。改变精确绘制效果的主题仍会保留 FR2 的静态层级和 FR3 的行为。
  • 浏览器证据:真实浏览器中 secondary Buttons 旁边的静态像素,以及 MultiSelector 和 ComplexSelector 在值变化前后的内联尺寸测量。源码检查覆盖共享的非输入状态分支。FR2 通过渲染对比得到证明:在默认主题以及所有对 secondary Button 进行样式设定的已发布主题中,将每个选择器的静态 secondary 触发器与 secondary Button 进行对比。要符合 FR6,需要对 secondary Selector 和 MultiSelector 进行专门的 DOM/样式测试和渲染后的组几何验证。

当前状态影响

  • 现有的 Selector 契约和 DD1 仍然是 Selector 各值及局部一致性决策的权威依据。
  • 草案中的 MultiSelector 和 ComplexSelector 组件记录引用 spec:AST-079/DEC-1 来说明同级采用,但并未使其不相关的声明成为当前有效内容。
  • MultiSelector 和 ComplexSelector 的使用者文档公开了这一共享的三值词汇表,并解释了何时选择每个值;Selector 保留其当前文档。
  • family:input-fields 继续负责内联尺寸、状态放置和 InputGroup 表面规则;本记录将这些规则投射到所采用的触发器值上,而不改变它们。
  • Button 组件保留其已发布的变体映射和渲染。
  • architecture:public-component-api 继续负责新增 API 的准入、默认值和兼容性。architecture:component-theming-surface 继续负责目标和视觉属性传播。

验证

契约 验证 代表性状态 变更或失败预期
FR1, FR4 公共类型、默认属性、data-variant、主题元数据和文档检查 所有三个组件;省略的值;每个显式值 组件省略某个值、更改其默认值、发布不同的值,或接受未类型化的值
FR2 secondary Button 旁边的静态浏览器像素,以及专门的 DOM/样式测试 每个变体处于静态;默认主题和所有对 secondary Button 进行样式设定的主题 secondary 的边框、填充或文本与主题的 secondary Button 不同,ghost 获得不透明填充,或角色坍缩
FR3 对变体特定分支的源码审查,外加现有的交互、表单、弹层、键盘、焦点和无障碍测试套件 popover、bottom sheet、自适应;在支持的情况下包括可编辑、禁用和只读 视觉变体改变选择或浮层语义、表单输出、焦点、命名、角色或值
FR5 专门的状态测试和浏览器宽度测量 每个变体上的附加请求;短/长的 MultiSelector 和 ComplexSelector 值 非输入状态被附加,仅输入状态的外观发生泄漏,或多值/富内容选择器改变可用内联尺寸
FR6 专门的 InputGroup DOM/样式测试,外加渲染后的组几何 secondary Selector 和 MultiSelector 作为第一个、中间和最后一个组子元素 触发器保留独立边缘/状态绘制,失去组高度/焦点堆叠,或连接表面分裂

决策日志

DEC-1 — MultiSelector 和 ComplexSelector 采用 Selector 的触发器层级

引用: spec:AST-079/DEC-1 决策者: cixzhang, 2026-10-14

Selector 当前的组件契约已经为调用方提供了三种触发器角色。在多值或富内容选择器上选择相同角色的调用方,不应看到不同的名称或收到不同的默认值。因此,MultiSelector 和 ComplexSelector 采用 Selector 的 input、secondary 和 ghost 词汇表,同时保留各自独立的交互模型和组件自有几何。它们的 secondary 与主题的 secondary Button 匹配,正如 Selector 在 DD1 下的行为一样,因此一个主题决策即可同时重新样式化所有 secondary 控件。

已拒绝的方案:使用同级组件专属的值名称或部分词汇表,这会让相同的调用方意图取决于选择模型;仅主题覆盖,这无法通过公共 API 表达调用方意图;一种独立于主题的 secondary Button 的固定无边框中性填充,这会在任何为 secondary Button 添加边框的主题下将一个工具栏拆分为两个层级;或者整体提升草案中的同级组件记录,这会批准不相关的声明。

开放问题

无。

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