选择器选项旁的次要操作系统规范¶
{
"scope": "global",
"triggers": {
"public-api": ["FR1", "FR2", "FR9", "DEC-1", "DEC-4", "DEC-5"],
"accessibility": ["AR1", "AR2", "AR3", "AR4", "DEC-2", "DEC-3"],
"behavior": ["FR3", "FR4", "FR5", "FR6", "FR7", "FR8"]
}
}
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个选项将其次要控件作为一个节点携带:action?: ReactNode,一个键、一个类型,同时适用于弹出面板渲染所依据的两种选项词汇表——SelectorOptionData 和 SearchableItem(FR1、DEC-1、DEC-4)。调用方渲染该控件;宿主将其放置在一个网格单元格中,不对其进行其他任何操作。 |
| 行为 | 如果弹出面板的选项都不携带操作,它就是当前的列表框。一旦任何已声明的选项带有一个操作,该弹出面板就是一个网格:每个选项是一行,包含两个单元格——选项及其操作(FR2、FR3、DEC-2、DEC-3)。上/下方向键移动行;行内末尾方向键到达操作;Enter 激活它;指针和触摸直接按下它(FR4、FR5)。激活操作绝不会改变选择(FR4)。该操作始终可见(FR8)。 |
| 最终用户影响 | 一个正在选择标签的人也可以在同一面板中用鼠标、手指、键盘或屏幕阅读器对其进行编辑,并且按下“编辑”绝不会顺带切换该标签。目前,产品能放置该控件的唯一位置也会触发选项选择,并且对辅助技术无效。 |
| 构建者影响 | 选项对象上的一个可选键,持有调用方自己的控件——一个 IconButton、一个 Button、一个菜单触发器,或任何具有可访问名称的东西。没有新类型、没有渲染 prop、没有针对没有该项的行的守卫代码。对于没有声明任何操作的调用方,没有任何变化。 |
| 兼容性/就绪性 | 纯新增。每个当前选择器都像之前一样渲染;仅当调用方声明了操作时才存在网格(DEC-5)。权威状态:draft,approved_by 为 null。没有未决的所有者问题。 |
| 审查检查 | 拒绝以下情况:渲染在 role="option" 内的控件;位于 listbox 与控件之间的 role="none" 或 role="group" 包装器;检查、克隆或包装 action 节点的宿主;宿主拥有的用于操作的类型或组件;数组类型的 action;角色跟随过滤视图而非已声明选项的弹出面板;任何单元格数量不是两的行;仅可通过指针访问的操作;在弹出面板内添加的 Tab 停留点;悬停或滑动才显示的操作。 |
| 治理规则 | spec:AST-002 FR1, FR4, FR15, FR16, DEC-1, DEC-6; architecture:public-component-api INV1, INV2, INV3, INV9; architecture:interaction-modality INV4, INV7; spec:AST-056 AR1 用于空状态的播报;component:DropdownMenu 用于本记录复用的项数据词汇表。 |
此表是审查概览;下面的正文具有权威性。
意图¶
一个选择器的组合框会打开一个选项弹出面板。有时,那个打开的 面板中的某个选项在其首要操作旁边带有一个次要动词:一个可以编辑的已保存标签、一个可以 重命名的已保存搜索、一个可以移除的近期值。用户需要按下那个 控件而不顺带选择该选项,并且屏幕阅读器用户需要 知道它存在并能到达它。
Astryx 的选择器无法承载它。每个选项槽位都渲染在
选项的点击目标内部,因此放置在那里的控件会同时触发并切换,
而 role="listbox" 只允许 option 和 group 子元素,所以
该控件无论落在哪里都无效。构建者要么放弃那个动词,要么重新构建
列表。
本记录提供一个答案:一个选项将其操作作为一个节点携带,由 调用方渲染;而任何包含此类选项的弹出面板都是一个网格,其 行将选项与其操作配对。 该操作位于弹出面板内部选项的旁边; 这里没有任何内容触及收起状态的触发器,其 自身控件(清除、箭头、状态)保持现有契约。组合框契约得以保留,键盘路径无需第二 个界面即可存在,并且没有一个调用方会为没有该操作的行编写守卫代码。
所有权边界¶
拥有
- 选项的次级控件作为调用方渲染的一个节点承载在选项上,以及弹出面板所渲染的每一种选项词汇表中该键的名称和类型。
- 包含带操作选项的弹出面板是一个网格,其行的形态,以及弹出面板何时切换。
- 指针、手指、键盘和辅助技术如何到达操作,并且到达操作绝不会改变当前选择。
- 该布局所保持的无障碍底线:有效的树、已命名的控件、单个 Tab 焦点位、无仅悬停路径。
- 哪些组件采纳此规则,以及渲染该词汇表但不采纳的宿主如何表现。
为什么现有记录无法承接它
spec:AST-057拥有一种触摸手势,用于加速宿主已展示的动词。其 FR9 和 DEC-4 通过自身文本保持Item不变,并将option行排除在其reveal模型之外。本记录是选择控件中始终可见的控件——即 AST-057 假定存在但未定义的表层。component:Selector是current,component:MultiSelector是draft;SelectorOptionData是两者共享的一个类型,其上的某个键不属于任何单独一方(architecture:knowledge-contractsINV2)。component:MultiSelector草稿中关于逐行操作的主张(其 FR9 / DEC-2)被撤回,以本记录为准。component:BaseTypeahead、component:Typeahead和component:Tokenizer是draft,并从第二种词汇表SearchableItem渲染。一条规则绑定两个词汇表并跨越五个组件,这是系统事实,而非组件事实。spec:AST-056是current,拥有类型化查询状态的词汇表。它管辖相同的面板,并在本文中被引用——空状态的宣告(AR1)和创建行(DEC-3)共享该面板——但次级控件不是搜索状态,current记录不能承载未获批准的主张(architecture:knowledge-contractsINV1、INV14)。architecture:public-component-api持有共享的命名语法,并通过deciding_specs链接其裁定;新的跨组件裁定应放在它所链接的某个规范中。family:input-fields拥有字段外观。BaseTypeahead不是其成员,面板也不是外观装饰。
非目标¶
- 单元格内多个控件之间的移动。 单元格只容纳一个节点(FR1、DEC-3),因此不需要在其中遍历焦点的规则。拥有多个动词的调用方会在该节点中放入菜单触发器;它打开的弹出面板拥有自己的键盘模型。如果后续记录允许该单元格内有多个控件,本仓库自身的树遍历焦点先例就是起点。
- 悬停揭示、滑动揭示或触摸手势的对应形态。 操作在静止状态下、在每种输入方式上都可见。行上的触摸手势属于
spec:AST-057。 CommandPalette。 它的行是复合子节点(CommandPaletteItem),其内部将SearchableItem转换为SelectorOptionData时只携带value和label,因此两个声明位置都不会触及它渲染出的行。采纳它属于spec:AST-002下的独立准入事项。ComplexSelector。 其内容是调用方拥有的标记,没有 listbox 角色;那里的调用方已经渲染带控件的行。- 操作单元格的主题目标。 是否允许存在由各组件的主题记录决定。
- 折叠触发器上的控件。 清除按钮、chevron、状态图标或调用方在关闭控件周围组合的任何其他内容都不是选项操作,也不在本记录管辖范围内。
- 操作的处理程序语义。 Edit 做什么——打开对话框、就地修改——由调用方决定。面板不会因为触发了操作而关闭或重新过滤;处理程序可以这样做。一行在其操作触发后是否离开,属于滑动问题,留在
spec:AST-057中;选择器选项不会因为有人按下 Edit 而消失。 - 满足本契约的等效内部实现仍然有效。内部模块、文件、函数名、算法、数据结构、存储布局、清单、日志、锁、事务协议以及 CI 作业/工作流拓扑属于架构或实现层面,除非调用方或互操作系统有意将该确切机制作为公共协议依赖。
仓库中的证据¶
在本记录的基准提交处,从 packages/core/src 读取。
| 位置 | 所显示的内容 |
|---|---|
Selector/types.ts — SelectorOptionData {value, label?, description?, disabled?, icon?};MultiSelector/types.ts 重新导出它 |
一种选项词汇表,两个公共组件。CommandPalette 导入它只是为了构建其 combobox 的扁平索引;它渲染出的行并不读取它。 |
Typeahead/types.ts — SearchableItem {id, label, element?, auxiliaryData?} |
第二种词汇表。由 Typeahead 和 Tokenizer 组合而成的 BaseTypeahead 渲染;也是 ChatComposerInput 触发器菜单(它渲染自己的 listbox)的条目类型。element? 表明条目已经从来源携带了渲染时的内容。 |
Selector.tsx, MultiSelector.tsx, BaseTypeahead.tsx — role="listbox" 宿主、role="option" 行、aria-activedescendant |
三个 listbox,一个 combobox 模式。每个 option 都是既作为点击目标、又作为暴露出来的行的单个元素,因此任何可交互内容若不作为 option 内容的子级,就无法放在其旁边。 |
Selector.tsx 和 MultiSelector.tsx — 分隔线是 aria-hidden,空状态是 role="presentation",分区标题以 aria-hidden 形式放在 role="group" 内 |
三种变通方案,每个都有注释“role="listbox" 只允许 option/group 子级”。grid 的规则不同:它允许行和行组,并且隐藏的子级像之前一样被排除——因此分隔线和空状态继续有效,而分区包装器必须改变 role(FR7)。 |
BaseTypeahead.tsx — 空状态是 role="option" aria-disabled="true" |
第四种、且不同的变通方案:“没有匹配项”消息本身就是一个禁用的 option。在 grid 中该元素是无效子级,而 spec:AST-056 AR1 已经要求公告携带已渲染的内容(FR7)。 |
Selector.tsx — aria-haspopup 是 'listbox',对于 bottom sheet 则是 'dialog';BaseTypeahead.tsx 省略了它(combobox 默认值是 listbox) |
弹出层的 role 已经按呈现方式告知。grid 弹出层同样需要告知 'grid'(FR2)。 |
MultiSelector.tsx — 全选行是通过同一个行渲染器渲染的哨兵 option;对于未匹配到任何内容的查询,创建行是一个 option |
系统生成的行已经存在,并将继续存在。它们与其他行一样,具有空的 action 单元格(FR3)。 |
hooks/useGridFocus.ts — columns: number,固定;行和列按 DOM 顺序对每个单元格计算;Calendar 使用它 |
该仓库的 grid 模型按固定列数垂直移动。每行始终是两个单元格,这种形态让该模型无需计数遍历即可移动(DEC-3)。 |
Selector.tsx — 从搜索输入框按 Tab 会到达 popover 内的清除控件,“保持弹出层打开” |
这是当前选择器面板内唯一的顺序焦点停留点,而且是组件自身的。Actions 不会增加任何停留点(FR5, AR3)。 |
SideNav/SideNavItem.tsx — actions?: ReactNode;Item.endContent 文档:“徽章、元数据、时间戳或操作按钮” |
行已经将控件作为调用方渲染的节点接收,行只负责放置。这里的 action 就是这一约定,用单数是因为该单元格只容纳一个(DEC-1, DEC-3)。 |
公共 API 与概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 负责人 | 稳定性 |
|---|---|---|---|---|---|
SelectorOptionData.action |
ReactNode \| undefined |
在 Selector 和 MultiSelector 中,option 的次要控件:由调用方渲染并命名的一个节点;宿主负责放置它。缺失与 null 含义相同:都没有。 |
无 | spec:AST-058 |
提议 |
SearchableItem.action |
ReactNode \| undefined |
typeahead 系列条目上具有相同键和相同类型的字段,经由 BaseTypeahead 到达 Typeahead 和 Tokenizer。 |
无 | spec:AST-058 |
提议 |
| 面板的 role | listbox → grid |
在某个声明的 option 带有 action 之前是 listbox;此后,只要组件保持挂载,就是 grid(FR2, DEC-5)。通过 aria-haspopup 告知。 |
listbox | spec:AST-058 |
提议 |
| 一行 | 恰好包含两个 gridcell 的 row |
先是选项本身——它今天渲染的所有内容——然后是它的操作。系统铸造的行具有空的操作单元格。 | — | spec:AST-058 |
提议中 |
| 触达操作 | 指针、触摸、inline-end 方向键 + Enter、通过 aria-activedescendant 的屏幕阅读器 |
支持每一种输入方式;仅靠悬停、滑动或 Tab 永远不行。 | — | spec:AST-058 |
提议中 |
操作单元格是每个采用者选项解剖结构中命名的一个部分:一个渲染后的内容槽位,由调用方用组件填充(architecture:public-component-api INV18)。
非公开:行和单元格的标记、活动后代(active descendant)的跟踪方式、操作列的尺寸计算方式,以及哪个 hook 遍历网格。
需求¶
行为契约¶
| ID | 不变量 | 依据 | 验证状态 |
|---|---|---|---|
| FR1 | 选项将其次要控件作为 action?: ReactNode,且只有一个节点。该键在 SelectorOptionData 和 SearchableItem 上具有相同的名称和相同的类型。调用方渲染该控件,并拥有其名称、处理函数、禁用状态和外观;有多个动词的调用方渲染一个菜单触发器,其弹出层负责其余部分。宿主按照 FR3 所述的位置渲染该节点,并且 MUST NOT 为了做出任何决定而检查、克隆或包装它;检查它是否存在(FR2)不属于检查。不存在宿主拥有的操作类型或组件。 |
DEC-1, DEC-3, DEC-4; SideNavItem.actions, Item.endContent; architecture:public-component-api INV2, INV3 |
提议中;main 上暂无证据 |
| FR2 | 弹出层在某个渲染之前是 listbox;在该渲染中,任何已声明的选项——无论处于分组的哪一层深度,且在查询过滤它之前——带有不是 null 或 undefined 的 action;从该渲染起它就是 grid,并在组件挂载期间保持为 grid。拥有弹出层的控件通过 aria-haspopup 宣告当前生效的角色(grid;BottomSheet 保持 dialog)。如果弹出层的角色跟随过滤后的视图变化,或又切换回去,则属于缺陷。 |
DEC-2, DEC-5; spec:AST-002 FR8, FR15 |
提议中 |
| FR3 | 在 grid 中,每个选项是一个 role="row",携带选项的 id、aria-selected 和 aria-disabled,并且每行恰好有两个 gridcell 子元素:第一个容纳选项今天渲染的所有内容——选中标记或复选框、图标、标签、描述、renderOption 输出——第二个容纳其 action 节点,当未声明操作时为空。组件铸造的行(全选行、创建行)是具有相同形状且操作单元格为空的行。任何行都不能只有一个或三个单元格。 |
DEC-2, DEC-3; useGridFocus fixed columns |
提议中 |
| FR4 | 激活操作只会运行调用方自己的处理函数,不会再有其他行为:选择状态不改变,高亮行不会因此改变,面板既不关闭也不重新过滤。按下选项单元格时,选择或切换行为与今天完全一致。选项的 disabled 仅控制其选择;操作是否禁用是调用方控件自身的状态,宿主不读取它。 |
spec:AST-002 FR16, DEC-6 |
提议中 |
| FR5 | Up 和 Down 键照旧在行之间移动高亮,并落在 option 单元格上;行内结束方向(inline-end)的箭头键将高亮从 option 单元格移到该行的 action 单元格,行内开始方向(inline-start)的箭头键将其移回,因此这些按键在 RTL 下跟随视觉方向。在 option 单元格上按 Enter 或 Space 照旧选择;在 action 单元格上按 Enter 或 Space 则激活那里的控件。输入文字以跳转、Home、End、PageUp、PageDown、Escape 和 Tab 均保持当前含义。没有任何操作控件位于顺序 Tab 导航顺序中。 | APG 带 grid 弹出层的 combobox;useGridFocus 的 RTL 处理;component:Selector 按键 |
已提议 |
| FR6 | 位于持有焦点的元素(触发器、搜索输入框或 BottomSheet 面板)上的 aria-activedescendant,在高亮位于 option 单元格时引用该行,在高亮位于 action 单元格时引用该操作的控件。它绝不会引用用户无法操作的元素。 |
AR3;当前在三个宿主中的 aria-activedescendant 接线 |
已提议 |
| FR7 | 在 grid 中,一个分区是一个由其标题命名的 rowgroup,其标题与现在一样保持隐藏。分隔线和“无匹配项”消息不进入无障碍树,Selector 和 MultiSelector 已经如此处理;BaseTypeahead 的消息目前是一个 option,在每种模式下都变为呈现性角色,并按 spec:AST-056 中 AR1 的要求进行播报。popover 与 BottomSheet 渲染相同的树。 |
ARIA grid 所需的 owned 元素;spec:AST-056 AR1 |
已提议;BaseTypeahead 的消息目前存在偏差 |
| FR8 | 在每种输入方式和每种指针类型下,操作在静止状态都是可见的。宿主将调用方的控件放入 action 单元格,并采用该单元格的大小和对齐方式,且不在其上方绘制任何自己的内容。悬停、聚焦或滑动都不会揭示额外内容。 | architecture:interaction-modality INV4;spec:AST-057 DEC-5 |
已提议;需要真实 Chromium 证据 |
| FR9 | Selector、MultiSelector、Typeahead 和 Tokenizer 采用此契约;后两者通过 BaseTypeahead 渲染的同一个面板实现。如果某个宿主在它拥有的 listbox 中渲染任一选项词汇表,且尚未采用此契约,则 MUST NOT 在 option 内部渲染操作;在采用之前,它渲染不带该操作的 option,并在开发模式下当某个 item 带有操作时发出警告。 |
DEC-4;spec:AST-002 FR15(绝不静默渲染损坏状态) |
已提议 |
可访问性契约¶
- AR1 — 无障碍树在两种模式下都有效。 listbox 只暴露
option和group子节点,与现在一样。grid 只暴露row和rowgroup子节点,row 的每个暴露子节点都是gridcell,且面板中任何位置都不再保留option或listbox角色。绝不使用role="none"或role="presentation"包装器让控件出现在 option 旁边;在有操作和无操作时,required-children 和 required-parent 检查均通过。 - AR2 — 名称保持独立。 option 单元格的内容就是该行的可访问名称;调用方的控件携带自己的名称,且不会被并入该行的名称。没有可访问名称的控件是调用方的缺陷,宿主应给出开发警告。
MultiSelector中目前拥有自己名称的行(部分选中的全选行)会将该名称保留在行上。 - AR3 — 每种交互方式都能触达操作。 鼠标可以点击它,手指可以触摸它,键盘可以用行内结束方向的箭头键到达它并用 Enter 触发它,屏幕阅读器通过
aria-activedescendant和控件的名称获知它。没有任何路径依赖悬停、手势或离开 combobox 的焦点。 - AR4 — 选择语义不变。
aria-selected从 option 移到 row,且含义不变;aria-multiselectable仍然位于宿主上;用户切换 option 时听到的选择播报不会因为现在由 grid 承载而改变。
平台支持¶
- 支持的功能/引擎底线:所有受支持的渲染器和浏览器;所使用的角色为 ARIA 1.2,按键处理为已内置的 combobox 模式。
- 不支持的行为:无。无法保持 AR1 的主机不会部分采用;它会继续保留其 listbox 和 FR9 的警告。
- 浏览器证据:FR1–FR7、FR9 和 AR1–AR4 是在 jsdom 中可证明的树、角色和事件声明,required-children 和 required-parent 规则会由无障碍引擎对照渲染后的 DOM 进行检查。FR8 以及操作列与其各行的对齐属于绘制声明,需要真实 Chromium 证据,包括 RTL。
当前状态影响¶
SelectorOptionData和SearchableItem新增action?: ReactNode。不会导出新的类型或组件。属于增量变更:对于未声明任何相关内容的调用方,不会有已发布的 prop、默认值或行为变化。扩展了SearchableItem且已声明了名为action的其他类型成员的调用方,在升级时会遇到类型冲突;采用变更会在其兼容性说明中指明这一点。component:Selector(current)在采用落地时,将新增该 key 和 grid 模式作为本地概念,并引用此记录;component:MultiSelector、component:BaseTypeahead、component:Typeahead和component:Tokenizer(draft)引用它而非复制它。component:MultiSelector的 FR9 / DEC-2 被撤回,转而采用此处的 FR3 和 AR1。- 当弹出层为 grid 时,针对未匹配任何内容的查询所创建的行是 FR3 下的系统生成行;其自身契约是
spec:AST-056DEC-3,此处不加以更改。 architecture:public-component-api在此记录成为current时,会在其deciding_specs中新增spec:AST-058;不变量不变。architecture:interaction-modality被读取而非更改;AR3 应用其 INV4 和 INV7。spec:AST-057被读取而非更改。其滑动操作是声明的对象,而此记录中的滑动操作是节点,依据 DEC-1 中陈述的一项原则:绘制控件的组件需要对象;仅放置控件的组件则接收节点。contributing:api-conventions新增一句话:组件渲染的控件应声明为数据;组件仅放置的控件应是行自身数据上的节点,而绝不是宿主上的 render prop。- 五个采用者的消费者文档各新增该 key 及一个示例。
- 此记录自身合并时不会产生已发布的公共 API 变更。当此记录处于
draft状态时,其review-applicability:v1块不路由任何内容(architecture:knowledge-contractsINV20)。
验证¶
| 契约 | 验证 | 代表性状态 | 突变或失败预期 |
|---|---|---|---|
| FR1, FR9 | 每个采用者的 prop 表面和渲染套件;导出表面清单 | 两个词汇表上的 action;一个 IconButton 节点;一个普通 Button 节点;一个菜单触发器节点;一个非采用宿主接收到带有 action 的项 |
宿主自有的操作类型或组件、数组类型的 key、对节点进行检查/克隆/包装的宿主,或在 option 内渲染该控件的非采用宿主,均失败。 |
| FR2, DEC-5 | 跨重新渲染的每个采用者角色套件 | 无 key;action: null;section 内带操作的一个 option;将该 option 过滤掉的查询;在后续渲染中移除该操作 |
一个未声明操作的 grid、一个带操作的 listbox、跟随过滤后视图的角色、切换回 listbox,或过期的 aria-haspopup,均失败。 |
| FR3, AR1 | 树断言以及两种模式下的 required-children 和 required-parent 检查 | 普通 options;sections;分隔线;空状态;全选;创建行;一个无操作的行旁边是一个带操作的行 | 包含两个以上单元格的行、grid 内的 option、grid 内的 group,或携带控件的 none/presentation 包装器,均失败。 |
| FR4 | 每个采用者的交互套件 | 点击该操作;点击 option 单元格;禁用的操作;带启用操作的禁用 option;单选和多选 | 可归因于该操作的选择变化、高亮变化、面板关闭或重新过滤,或被 option 的 disabled 压制的操作,均失败。 |
| FR5, FR6, AR3 | 带 aria-activedescendant 断言的每个采用者键盘套件;通过 direction provider 的 RTL |
向下到某行;inline-end 到其操作;Enter;inline-start 返回;Escape;Tab;输入以跳转;在 RTL 中相同;bottom-sheet 呈现 | 面板内的连续 Tab 停顿点、箭头无法到达的操作、在操作单元格上按 Enter 选择 option,或在惰性元素上的活动后代,均失败。 |
| FR7 | 每个采用者的树和 live-region 套件 | 带标题和无标题的 sections;搜索时的分隔线;各宿主中的空状态 | grid 中的 group、作为子节点暴露的分隔线或消息,或 BaseTypeahead 消息仍作为 option 暴露,均失败。 |
| FR8 | Real-Chromium 证据:静止、悬停、聚焦及 RTL 状态下 | 仅图标的控件;文本控件;带/不带操作的行;粗指针和细指针 | 操作在静止时缺失、悬停才显示、与所在行未对齐,或被宿主重绘,均失败。 |
| AR2, AR4 | 可访问名称与选中状态断言 | 带命名控件的行;带未命名控件的行;部分选中的全选行;多选模式下的切换选择 | 行由其控件的标签命名、未命名控件缺少警告、全选行丢失其名称,或选择公告发生改变,均失败。 |
已知验证缺口:上述测试套件均不存在于 main;没有任何组件实现该契约;仓库的可访问性模式契约覆盖 listbox 而非 grid。此记录为 draft,不约束评审,且未指明任何实现。
决策日志¶
在所有者整体批准之前,approved_by 为 null,记录为 draft。
DEC-1 — 操作是选项上的一个节点,因为宿主仅放置它¶
Reference: spec:AST-058/DEC-1
Decider: cixzhang, <pending>
选项上的 action?: ReactNode,由调用方渲染。
options={[
{
value: 'eng',
label: 'Engineering',
action: <IconButton icon={<PencilIcon />} label="Edit Engineering" onClick={edit} />,
},
{value: 'design', label: 'Design'},
]}
选项是信息所在之处:哪些行带控件是关乎该选项的事实,因此宿主在渲染任何内容之前检查 action != null,并在不调用任何内容的情况下决定自身结构(DEC-2);没有操作的行则不需要调用方提供任何代码。
这一原则与 spec:AST-057 共享,后者采纳了相反的一面:组件需要渲染某物时需要对象;组件仅放置某物时节点即可。 滑动面板由组件绘制和动画化,需要标签、变体以及行是否在手势开始前离开,因此它被声明。选择器行的操作是调用方渲染的控件——其名称、处理函数、禁用状态和外观已存在于调用方自己的按钮上——宿主将其放入网格单元格,不做其他任何处理。宿主无需预先知道任何信息,因此没有需要声明的类型,没有随系统发布的控件,系统发布内容与调用方自带内容之间也没有分档。
键是单数形式,因为单元格容纳一个节点(DEC-3)。一个永远只能容纳一个元素的数组将宣传一种并不存在的能力;调用方传入两个就会在运行时触达上限。这一上限不带来任何成本:需要多个动作的调用方会在该节点中渲染一个菜单触发器,而它打开的弹层拥有自己的键盘模型,因此单元格仍只容纳一个可聚焦控件。
使用隔离构建器对四种候选结构进行形态测试,在给定行为且不提供属性名的情况下,每次召回探测都得到声明的 {label, icon, onClick} 数组,并在未提示的情况下拒绝了 render prop。这衡量了构建者的期望;而节点才是组件所需,因为组件本身不渲染该控件的任何部分。选项上的一个键是双方达成共识之处。报告由所有者保管,位于仓库之外。
已拒绝:宿主上的 render prop——宿主无法区分“任何地方都没有操作”和“对每一行都返回 null 的函数”,除非为每一行调用它,因此宿主无法知道自身结构,最终只能由调用方来防护它。已拒绝:声明的 OptionAction 对象——它会让宿主渲染一个没有理由拥有的控件,并随之引入一套 variant 词汇表。已拒绝:actions: ReactNode[]——即使将来规定了单元格内的移动,键也无需改变;spec:AST-056 的 DEC-2 恰恰拒绝了这种推测性的泛化,而 spec:AST-017 建立的弃用周期使将来若真有此需求,从 action 改为 actions 的成本很低。
DEC-2 — 一旦选项携带操作,宿主即为 grid¶
Reference: spec:AST-058/DEC-2
Decider: cixzhang, <pending>
选项旁边的控件不能作为 listbox 的子元素:role="listbox" 只允许 option 和 group。combobox 模式允许弹层为 listbox、tree、grid 或 dialog,因此 grid 保留了触发器与搜索输入框已经满足的契约——aria-haspopup="grid"、aria-controls、aria-activedescendant——并免费为键盘提供了路径:上箭头和下箭头照常移动行,内联末端箭头到达操作。没有第二个表面,没有隐藏面板,没有 Tab 停靠点。
已拒绝:在选项及其控件周围使用 role="none" 包装器——none 会将其子元素重新归属到最近的暴露祖先下,因此控件会直接落在 listbox 内部,并违反同样的 required-children 规则;MultiSelector 自身源码在提到其分隔符和空状态时两次引用的正是该规则。已拒绝:在 listbox 外部使用绝对定位的控件列,每个控件位于其所在行测量出的偏移位置——这方案有效,但它用结构修复换来了一个需与 resize、reflow 和虚拟化挂载对抗的位置同步循环。
DEC-3 —— 每行两个固定单元格¶
参考: spec:AST-058/DEC-3
决策者: cixzhang, <pending>
每行都有两个单元格:先是选项,然后是它的操作。没有操作的行,第二个单元格为空。
网格按固定列数遍历——仓库自身的 grid hook 恰好按 columns 个单元格垂直移动,并按照 DOM 顺序统计每一行——因此参差不齐的行会破坏垂直移动。始终固定为两个单元格意味着无需计数扫描、无需逐行几何计算,也无需区分普通选项、全选行和新建行。
网格遍历到单元格这一层,从不进入单元格内部,因此调用方放在第二个单元格里的节点不会改变上述任何行为——并且由于每个单元格只容纳一个节点(DEC-1),内部也不存在需要规定的移动方式。
已否决:每个控件一个单元格——行宽随数据变化,垂直移动会落入错误的列。
DEC-4 —— 一个键、一种类型、两种选项词表;typeahead 系列通过其单一面板采纳¶
参考: spec:AST-058/DEC-4
决策者: cixzhang, <pending>
仓库从两种选项类型渲染选择器面板。SelectorOptionData 由 Selector 和 MultiSelector 共用。SearchableItem 是 typeahead 系列的条目:BaseTypeahead 渲染它,Typeahead 和 Tokenizer 组合 BaseTypeahead,查询结果即面板所展示的内容。键位于前者身上即可触达两个组件;typeahead 系列只有在自身条目携带该键时才具备此能力。
因此,相同的键、相同的名称、相同的类型,在两个组件上都要声明。一个概念在拥有它的各个组件中保持同一名称——spec:AST-056 的 FR1 规则针对的是状态,这里则应用于声明。
SearchableItem 已经从数据源携带了一个渲染节点(element?),因此数据源为其条目附加操作节点是符合其特性的;createStaticSource 会原样传递它们。BaseTypeahead 是唯一的渲染器,因此采纳一次即可覆盖 Typeahead 和 Tokenizer。
在自有的 listbox 中渲染 SearchableItem 的宿主——例如 ChatComposerInput 的触发菜单——在采纳之前受 FR9 约束。CommandPalette 不是采纳者:它的行是复合子元素,其内部的 SelectorOptionData 转换会丢弃除 value 和 label 之外的所有字段,因此两个声明都不会抵达其渲染行(非目标)。
已否决:为 typeahead 系列提供宿主级函数 getAction(item)——这正是 DEC-1 排除的同一检测问题,而现在落在唯一一个行内容异步到达的系列上。
DEC-5 —— 网格是有条件的:检测读取声明的选项并锁定¶
参考: spec:AST-058/DEC-5
决策者: cixzhang, <pending>
宿主根据其被赋予的选项来决定自身角色,且发生在任何查询过滤之前:只要任一选项(无论位于分区的哪一层)的 action 不是 null 或 undefined。键缺失与值为 null 是同一种状态——调用方若对每个选项都写 action: canEdit ? <Edit/> : null,大多数行会得到 null,这绝不能构成网格。检查的是“是否存在”;宿主永远不会读取该节点。
一旦宿主成为网格,在挂载期间就始终保持网格。options 稳定的 Selector 根本不会切换;在加载状态之后才拿到 options 的 Selector 只切换一次,且发生在任何人读取面板之前。typeahead 的行是查询结果,因此按结果集变化的角色会随用户输入而改变;锁定机制将其限制为每个挂载实例只切换一次,且永不回退。触发器的 aria-haspopup 随之保持一致。
已否决:所有选择器一律永久使用网格——当前所有用户都会在单列列表中听到“网格”,且水平方向键无处可达。已否决:角色跟随每次渲染的过滤后视图——一个随调用方过滤而改变角色的选择器,会比两种固定模式都更糟糕。
待解决问题¶
无。一个单元格可以容纳多少个控件由类型决定:一个节点(DEC-1、DEC-3)。单元格内部移动不在本记录的范围内。
内容边界¶
产生本记录的研究——形状测试的设计、提示词和评分——是一份报告而非契约,存放在本记录之外,由负责人持有。
本记录不重复任何采纳者的结构剖析、prop 表、主题化目标或消费者示例;不重复 spec:AST-002 中的准入论证;不重复 spec:AST-017 中的弃用与发布机制;不重复 architecture:public-component-api 中的共享命名语法;不重复 architecture:interaction-modality 中的模态不变量;不重复 spec:AST-056 中的搜索状态词表;不重复 spec:AST-057 中的滑动手势;也不重复 component:DropdownMenu 中的菜单项数据契约。本记录会链接到它们各自的规范所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx