Item 组件契约¶
本记录规定了 Item 如何将其起始和结束内容与标签对齐。Item 的滑动操作由 spec:AST-057 规定,其链接与导航语义由 family:navigation-destinations 规定;在某个记录声明拥有之前,Item 的其他行为仍由其源代码、测试和 Item.doc.mjs 描述。
契约速览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | align?: 'center' \| 'start' \| 'first-line' 用于 Item、ListItem、RadioListItem 和 CheckboxListItem;默认值为 center。 |
| 行为 | first-line 会将每个起始和结束槽位以标签的第一行居中,适用于任意槽位高度;若槽位高于该行,文本会下移,而不是让槽位脱离该行。 |
| 最终用户影响 | 状态小圆点、单选按钮或年龄标记会与换行标签的第一行保持水平,而不会漂移到行的中间(center)或浮到行的上方(start)。 |
| 构建者影响 | 默认无影响。构建者可按行通过 align="first-line" 选择启用;主题作者可为 item 目标的 first-line 对齐设置样式。 |
| 兼容性/就绪度 | 增量式:在现有封闭轴上新增一个值,并对现有运行时透传进行类型化转发。省略 align 的行保持不变。 |
| 评审检查项 | 拒绝默认值被更改、center/start 几何行为被更改、JavaScript 测量、槽位被推出行外、出现第二个主题目标,或组合行丢弃该值的情况。 |
| 约束规则 | 以下 FR1–FR8;architecture:component-theming-surface/INV6;spec:AST-017/FR3。 |
此表是评审概览;以下正文具有权威性。
意图¶
Item 是列表、菜单、选择器和选项行背后的共享行。其标签可以换行,而起始和结束内容通常是单行大小的标记:状态圆点、单选按钮或复选框、图标、短时间戳。这些标记属于它们所标注的第一行文本。Item 拥有对齐逻辑,因为只有 Item 知道其标签第一行的位置;调用方若不复制 Item 的排版,就无法将槽位对齐到该位置。
兼容性与迁移¶
- 已发布的默认值保留:
yes;省略align时解析为center。 - 兼容性类别:增量式封闭轴值;在三个已在运行时将未知 props 转发给 Item 的组合行上新增类型化 prop。
- 受控/非受控行为:不适用。
- 迁移决策:
component:Item/DEC-1。
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
align轴:其值、默认值,以及起始和结束内容槽位中每个值的几何行为。- 在
item主题目标上反映解析后的对齐方式。 - 在
item主题目标上反映高亮、选中和禁用状态。 - 组合 Item 并暴露
align的行的转发规则。
不拥有 / 非目标
marker槽位的对齐——由渲染 marker 的一方拥有;ListItem 会将自己的 markers 与第一行对齐。label内部调用方内容的排版——由调用方拥有。- 主题级默认对齐——主题负责样式化值,而不负责选择组件的 prop 默认值(
architecture:component-theming-surface)。 - 槽位自身内容内部的对齐(例如头像堆叠)——由该内容拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 对齐 | center、start、first-line |
center:槽位以整个文本块为中心居中。start:槽位顶部与文本块顶部对齐。first-line:槽位以第一行的中心居中。 |
所有密度、布局、交互模式和方向;起始与结束槽位 | center |
component:Item |
稳定 | 其他值会被公共类型拒绝 |
行为与布局契约¶
| ID | 不变量 | 依据 | 草稿评审状态 |
| FR1 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| FR1 | Item MUST 接受 align,其取值恰好为 center、start 和 first-line,并且 MUST 将省略的值解析为 center。center 和 start 的几何形态 MUST NOT 改变。 | component:Item/DEC-1 | 已解决 |
| FR2 | 在 first-line 下,每个已渲染的 start-content 和 end-content 槽的块轴中心 MUST 与标签第一行框的块轴中心重合,对于每个槽块尺寸均成立。 | 所有者指示 | 已解决 |
| FR3 | 在 first-line 下,高于标签第一行的槽 MUST 保持在行的内容框内:标签和描述向下移动相应的差值,行随之增长以容纳。任何槽都不会被裁剪,也不会绘制到行的块内边距中。 | 所有者指示 | 已解决 |
| FR4 | 标签渲染为单行且没有描述的行,在 first-line 和 center 下 MUST 渲染得完全一致,对于每个槽块尺寸均成立。 | 由 FR2 和 FR3 推导得出 | 已解决 |
| FR5 | 第一个行框就是标签行,Item 以活动主题的正文字体大小和行高来设置其样式。改变这些令牌的主题会随之改变对齐方式。label 内设置了自身字体大小或行高的调用方内容不在 FR2 保证范围内。 | 共享排版来源 | 已定稿 |
| FR6 | first-line MUST 在所有密度、stacked 和 inline 布局、labelLines 截断,以及 plain、button、link、link-root、delegated 和 parent-role 行中成立。在从右到左的文本中,它 MUST 产生相同的块轴位置,插槽按逻辑顺序镜像,且不进行 DOM 重新排序。 | architecture:internationalization | 已定稿 |
| FR7 | item 主题目标 MUST 将其解析后的对齐方式体现为现有的 align 选择器轴(包括 first-line),并且 Item 的公开主题元数据 MUST 列出该值。该对齐轴不添加任何新目标或主题级默认值。 | architecture:component-theming-surface/INV6; component:Item/DEC-2 | 已定稿 |
| FR8 | ListItem、RadioListItem 和 CheckboxListItem MUST 公开 align,使用 Item 的值和默认值,并将其原样转发到它们渲染的 Item 行。组合行 MUST NOT 丢弃、重新映射或收窄该值。 | 所有者指示 | 已定稿 |
| FR9 | 交互式行(onClick 行、href 行或带 interactiveRef 的委托行)仅在会激活它的按压上显示触摸按下绘制:手指按在行表面或其自身操作(其不可见按钮或链接,或它委托到的控件)上会绘制该行,而手指按在行内另一个交互元素上则不会绘制。在具有父级提供的 role 的行中,或在根元素是链接的行中,按在嵌套控件上会激活该行,因此它会绘制。在拥有控件盒子的行上(如 CheckboxList 或 RadioList 行),鼠标或触控笔从另一个交互元素开始的按压同样不会显示触摸按下绘制。这种鼠标按压会保留该行的 :active 绘制。 | 所有者指示,2026-11-03:对于不会激活容器的按压,容器上不显示按下状态;所有者决定,2026-11-11:在拥有控件盒子的行上,鼠标和触控笔同样如此。 | 已定稿 |
| FR10 | item 主题目标 MUST 将高亮、选中或禁用的行分别反映为 data-highlighted、data-selected 和 data-disabled;每个属性仅在其状态持续期间存在,并使用 CommandPaletteItem 所用的名称。组合 Item 的行会反映其传递给 Item 的状态。 | architecture:component-theming-surface/INV6;已发布的源码和针对性测试,未经负责人评审 | 已定稿;未经负责人评审 |
允许的变体¶
- AV1 — 插槽内容。 可以出现任意插槽内容和尺寸;FR2 对每个插槽独立成立,因此不同高度的起始插槽和结束插槽都各自居中于第一行。
- AV2 — 主题排版。 正文字号和行高可随主题变化;第一行的行框随之变化(FR5)。
- AV3 — 行高。 在
first-line下,当某个插槽高于第一行且存在描述或第二标签行时,行可能比在center下的同一行更高(FR3)。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 换行标签,起始处 6px 圆点,结束处短文本 | 两个插槽的中心都位于第一行的中心。 | 密度、主题排版、方向。 |
| 单行标签,无描述,任意插槽 | 与 center 相同。 |
插槽尺寸。 |
| 标签和描述,起始处 40px 头像 | 头像中心位于第一行的中心;文本下移;行变高。 | 头像尺寸。 |
| 带换行标签的单选或复选框行 | 控件居中于第一行。 | 控件尺寸由 Field 尺寸决定。 |
| 从右到左 | 块轴位置相同;插槽按逻辑顺序镜像。 | 书写方向。 |
省略 align |
与现在的 center 相同。 |
无。 |
转换与优先级顺序¶
- ORD1 — 解析。 组合行上的显式
align原样转发给 Item;Item 将省略的值解析为center;解析后的值同时驱动几何和item目标的选择器轴,因此两者永远不会不一致。
性能与资源¶
- PR1 — 仅 CSS 几何。 每个对齐值都 MUST 在 CSS 中实现:不得使用测量、观察器、监听器、状态、Effect 或额外的渲染过程。
无障碍契约¶
- AR1 — 仅呈现。 对齐 MUST NOT 改变行或其插槽的 DOM 顺序、角色、无障碍名称或描述、焦点目标、Tab 顺序或命中目标。
- AR2 — 不暴露文本。 任何实现
first-line的结构 MUST 不向无障碍树贡献任何文本。
设计关系¶
| 结构或状态 | 设计需求 | 呈现权 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 起始和结束内容 | 为其旁边的标签的第一行提供标注。 | 所有者指示 | 支持性 | FR2–FR4 |
| 标签第一行 | 插槽对齐所参照的基准线。 | Item 排版 | 突出 | FR5 |
家族与系统关系¶
spec:AST-057负责 Item 的滑动操作及其面板;对齐不会改变它们,因为面板位于行的流之外。family:navigation-destinations负责 Item 的链接和导航语义;对齐不会改变它们。architecture:component-theming-surface负责视觉轴如何到达主题目标;本记录向 Item 现有的align轴添加一个值。architecture:public-component-api负责 prop 准入;FR8 为现有的运行时透传提供类型,而不是增加一个并行的概念。architecture:internationalization负责逻辑方向行为;FR6 应用它。spec:AST-017/FR3将此归类为非破坏性功能:它增加一个值和带类型的 prop,没有收窄任何行为,且从不设置align的调用方不会看到任何变化。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR7 | Item.test.tsx 对齐与主题反射测试套件;公共类型测试 |
未设置、center、start、first-line |
更改默认值、缺少 data-align="first-line" 或类型被放宽都会导致失败。 |
audit:Item/api |
| FR2–FR6 | 基于真实 Chromium 的几何断言,覆盖 Item 对齐 stories | 带圆点和年龄的换行标签;头像;密度;RTL;主题 | 槽位中心偏离首行中心超过 0.5px,或槽位被裁剪,则失败。 | audit:Item/layout |
| FR8 | List.test.tsx、RadioList.test.tsx、CheckboxList.test.tsx 的透传用例 |
每个组合行使用 align="first-line" |
行的 Item 根节点缺少 data-align="first-line" 则失败。 |
audit:Item/api |
| FR9 | nestedTouchPress.adopters.test.tsx;Item.nestedPress.test.tsx;CheckboxList.test.tsx、RadioList.test.tsx 和 useClickableContainer.test.tsx 中的嵌套控件用例 |
手指按在委派控件上;手指按在行内另一个控件上;鼠标和触控笔按在 CheckboxList 或 RadioList 行中的另一个控件上 | 如果一行因按下另一个控件而呈现按下状态,或因按下其委派控件而未呈现按下状态,则失败。 | audit:Item/behavior |
| FR10 | Item.test.tsx 的“在 item 主题目标上反映 highlighted、selected 和 disabled”用例 |
普通、仅 highlighted、仅 selected、仅 disabled,以及三者同时存在 | 缺少某个属性,或某行的状态不再成立却仍保留该属性,则失败。 | audit:Item/theming |
| AR1, AR2 | first-line 行与 center 行的无障碍树快照对比 |
普通行和选项行 | 在名称、角色、描述或顺序上出现任何差异则失败。 | audit:Item/a11y |
| PR1 | 对 Item 对齐样式的源码评审 | 所有值 | 为对齐而新增的 ref、observer 或 Effect 会导致评审不通过。 | audit:Item/layout |
决策日志¶
DEC-1 — first-line 是选用值;center 仍为默认值¶
参考: component:Item/DEC-1
决策者: cixzhang, 2026-10-16
对于带有一个单行大小标记的换行标签,该标记需要位于其第一行,而现有的两个值都无法做到:center 将标记放到行的中间,start 把标记的顶部固定,这会让一个小标记位于该行中心的上方。新增一个值可以修复这些行,而不会移动任何依赖当前默认值的行。
已否决:将 first-line 设为默认值,因为一个与整个文本块等大的槽位(例如位于标签和描述旁边的头像)在 center 下才是正确的。
DEC-2 — 主题设置是 item 目标的对齐轴¶
Reference: component:Item/DEC-2
Decider: cixzhang, 2026-10-16
主题通过 item 目标现有的 align 选择器轴到达 first-line 行,与到达 center 和 start 的方式相同。主题可以设置这些行的样式;它不会选择某一行接收哪个值。
开放问题¶
无。
内容边界¶
本文件不会重复使用方 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx