共享选择器触发器层级系统规范¶
意图¶
构建者可以在工具栏或导航区域中,将 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和ComplexSelectorMUST 接受内置触发器variant的相同三个值。每个公共类型、渲染后的data-variant反射、variant视觉属性轴的消费方主题声明,以及暴露此轴的消费方文档 MUST 使用这些相同的名称。其他值会被公共类型拒绝。 - FR2 — 静止角色是共享的。 静止时,
input呈现不透明、带边框的表单字段表面;secondary匹配活动主题的 secondaryButton;ghost呈现透明、低强调的触发器。对于所有三个选择器上的secondary,其静止边框(宽度、样式和颜色)、填充和文字颜色 MUST 与同一主题中 secondaryButton的对应值匹配,并与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 — 触发器外观不会改变选择器行为。 更改
variantMUST NOT 更改所选值、选项或子项词汇、弹层呈现模式(popover、bottom-sheet或adaptive)或浮层语义、键盘模型、焦点归属、表单参与、无障碍名称、角色或值语义。视觉对齐可以跟随所选触发器表面。 - FR4 — 采用是兼容的。
input仍然是三个组件的默认值。现有input和ghost调用方保持其已发布行为。MultiSelector或ComplexSelector的调用方显式选用secondary;现有调用点无需迁移。Selector 的兼容性仍由其当前组件契约负责。 - FR5 — 家族宽度和状态规则仍然适用。 在
family:input-fieldsFR1 下,独立的Selector可以跟随其显示内容,而MultiSelector和ComplexSelectorMUST 在值变化时保持其可用的内联尺寸。在 family FR8 下,非 input(secondary或ghost)触发器上请求的attached状态会解析为detached;状态边框和阴影仍仅限于符合条件的input触发器。 - FR6 — InputGroup 保持连接表面。
Selector和MultiSelector可以在 InputGroup 内使用secondary。触发器可以保持其中性局部填充,但 MUST 采用组解析后的高度、连接边缘圆角和焦点堆叠,并且 MUST NOT 绘制独立的外边框、阴影或状态处理。在family:input-fieldsFR3 下,InputGroup 仍然是连接的外部几何结构的负责人。ComplexSelector不支持 InputGroup。
平台支持¶
- 支持的功能/引擎基线:这三个组件已经支持的所有浏览器和渲染器;该词汇表不引入任何平台特性。
- 不支持的行为:无。改变精确绘制效果的主题仍会保留 FR2 的静态层级和 FR3 的行为。
- 浏览器证据:真实浏览器中 secondary Buttons 旁边的静态像素,以及 MultiSelector 和 ComplexSelector 在值变化前后的内联尺寸测量。源码检查覆盖共享的非输入状态分支。FR2 通过渲染对比得到证明:在默认主题以及所有对 secondary
Button进行样式设定的已发布主题中,将每个选择器的静态secondary触发器与 secondaryButton进行对比。要符合 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