ListItem 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | ListItem 带有 label、description、startContent、endContent、onClick、interactiveRef、href、target、rel、align、isDisabled、isSelected、itemKey、swipe、xstyle、className、style 和 ref,附带已弃用的 swipeActions 和 swipeBehavior,直至 spec:AST-057 CLN-0025 将其移除;该行应用 component:List 的 list-item 目标。itemKey 是该项的键(spec:AST-103 DEC-4)。 |
| 行为 | 由 component:Item 渲染的一个 <li> 行,它接收所有行级 prop。在 List 内部,该行采用列表的密度、分隔线、边缘处理和标记;在 List 外部,它使用 Item 的默认值且不绘制标记。 |
| 最终用户影响 | 每个列表条目都呈现为一个列表项,其前面有列表的项目符号、编号或任务复选框,并具有 Item 赋予任何行的相同交互。 |
| 构建者影响 | 已弃用的 swipeActions 和 swipeBehavior 在 spec:AST-057 DEP-0017 下迁移为 swipe={createSwipe(…)};其 astryx upgrade codemod 是从弃用版本开始的可选早期迁移,并将在 0.8.0 的升级中随 CLN-0025 的移除再次运行。 |
| 兼容性/就绪状态 | 记录已发布行为;itemKey 是增量新增的。有一个实现差距,列在“当前状态影响”下。 |
| 审查检查 | 拒绝以下情况:不是 <li> 的行、ListItem 级别的边缘、密度或分隔线 prop、在带标记的 List 之外绘制的标记,或丢失的 Item prop。 |
| 治理规则 | component:Item(用于起始和结束内容的 align);component:List;family:navigation-destinations;spec:AST-057;spec:AST-103;architecture:component-theming-surface;architecture:component-style-authoring INV7。 |
此表是审查概览;下文正文才具有权威性。
意图¶
ListItem 是 List 为每个条目渲染的行。它负责将行转换为列表项:<li> 元素、它从 List 读取的内容、绘制在行前的标记,以及如何应用 component:List 的 list-item 目标。行作为行所做的一切均来自 component:Item。消费者用法见 ListItem.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共变更
- 受控/非受控行为:不适用;
isSelected和isDisabled由调用方所有 - 迁移决策:
spec:AST-057DEP-0017,其astryx upgradecodemod 将swipeActions和swipeBehavior重写为swipe={createSwipe(…)};这是从弃用版本开始的可选早期迁移,并将在 0.8.0 的升级中随spec:AST-057CLN-0025 的移除再次运行
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 标记是额外元素。 项目符号标记绘制为两个装饰性
span元素,数字标记绘制为一个带有计数器伪元素的span,位于行内容旁边。architecture:component-style-authoringINV7 将无语义角色的装饰放在伪元素上,而不是额外元素上。
所有权边界¶
拥有
- 通过
component:Item将行渲染为<li>,并将所有行级 prop 传递给它(FR1)。 - 从外部 List 读取密度、分隔线、边缘处理和标记,以及在 List 外部时的默认值(FR2、FR3)。
- 绘制标记或任务项的只读复选框(FR4)。
- 将
component:List的list-item目标应用到该行(FR5)。
不拥有 / 非目标
align、起始和结束内容的对齐方式 —— 由component:Item拥有;滑动操作 —— 由spec:AST-057拥有;链接目标 —— 由family:navigation-destinations拥有,ListItem 是其成员。- Item 的标签、描述、插槽、隐形按钮、委托激活以及禁用和选中语义 —— Item 的已发布行为,此处不另行约定。
- 每种边缘处理对行几何形状和行内边距的作用、触摸目标、按压绘制、行动画和行菜单 —— 由
component:List拥有。 - 为 Markdown 嵌套列表设置标记或任务状态的
ListMarkerScope—— 内部实现,此处不另行约定。 - Markdown 列表的整数标记和文本对齐 —— 由
spec:AST-061FR11 和component:ListDEC-5 拥有。
公共概念¶
除了消费者 props 之外,没有其他组件局部概念;行的 props 是 component:Item 的 props。
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | ListItem 将 component:Item 渲染为一个 <li>,并把 label、description、startContent、endContent、onClick、interactiveRef、href、target、rel、align、isDisabled、isSelected、swipe、已弃用的 swipeActions 和 swipeBehavior(spec:AST-057 DEP-0017)以及 ref 原样传递给它;其他 DOM 和数据 props 也会到达该行。 |
当前源码与测试 |
| FR2 | 在 List 内部,行采用该 List 的 density、其 hasDividers 设置(该设置会在行之间绘制分隔线,不添加额外元素,并使用方角;但如果 bleed 列表的首行或末行位于圆角宿主中,则采用宿主的圆角,component:List FR5)以及其 edge 处理。 |
当前源码与测试 |
| FR3 | 在 List 外部,行使用 balanced 密度、无分隔线、padded 处理且无标记,同时保留 Item 的内联内边距。 |
当前源码与测试 |
| FR4 | 在 listStyle 为 disc、circle 或 decimal 的 List 中,行会于其内容之前绘制相应标记:圆点或圆圈形状,或一个计数器编号。为行设置的任务状态会在标记位置绘制一个只读、带标签的复选框。每个标记和任务复选框都位于标签的首行。listStyle 为 none 的 List 两者都不绘制。为 Markdown 嵌套列表在内部设置的其他标记,此处不做契约约定。 |
当前源码与测试 |
| FR5 | 行携带 component:List 的 list-item 目标,并与调用方的 className 和 style 合并;xstyle 在 ListItem 自身样式之后应用。 |
当前源码 |
允许的变体¶
- AV1 — 行内容。 标签、描述和插槽内容可变。
- AV2 — 主题样式。 主题可重设
list-item的样式。
代表性状态¶
| 状态 | 必需不变式 | 允许的变体 |
|---|---|---|
| List 中的静态行 | 一个 <li>;无按钮或锚点。 |
内容。 |
| 交互式行 | Item 的不可见按钮或锚点;一个 Tab 焦点位置。 | 内容。 |
| 带分隔线的列表 | 行之间有一条分隔线;方角,但 bleed 列表在圆角宿主中的端部行除外(component:List FR5)。 |
密度。 |
| 编号列表 | 每行前面有一个计数器编号。 | 编号样式。 |
| 任务行 | 在标记位置有一个只读复选框。 | 选中状态。 |
| List 外部的行 | Item 的内联内边距;无标记。 | 内容。 |
转换与优先级顺序¶
- ORD1 — 标记。 当 List 的
listStyle为none时无标记;否则,如果行具有任务状态,则先绘制任务复选框,再绘制标记。 - ORD2 — 样式。 先应用 ListItem 自身样式,再应用调用方的
xstyle。
性能与资源¶
- 无资源规则。
无障碍契约¶
- AR1 — List 语义。 在 List 内部,每行都是 List 的
<ul>或<ol>中的一个<li>(FR1)。 - AR2 — 行语义。 Item 的交互、禁用和选中语义原样应用;这些是 Item 的既定行为,此处不另作契约约定。
- AR3 — 任务状态。 任务行的复选框是只读且带标签的(FR4)。
设计关系¶
| 结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 行 | 通过 Item 呈现一个列表条目。 | component:Item |
突出 | FR1, FR5 |
| 标记 | 显示列表的项目符号、编号或任务状态。 | 当前源 | 支持 | FR4 |
尚未记录解剖主题映射;该块在迁移期间是可选的,因此映射被推迟。
家族与系统关系¶
component:Item拥有align,即起始和结束内容的对齐方式;其其他行行为未契约化。spec:AST-057拥有滑动操作,family:navigation-destinations拥有链接目标。component:List拥有边缘处理以及其行几何和缩进;其记录将密度、分隔线和标记样式设置保持未契约化,此处的 FR2 和 FR4 涵盖行如何使用它们。architecture:component-theming-surface拥有目标限定;component:List拥有list-item目标,FR5 涵盖行如何应用它。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | List.test.tsx 行元素、align、数据属性和滑动透传测试 |
静态和交互行 | 不是 <li> 的行,或丢失 prop 的行,将失败。 |
audit:ListItem/behavior |
| FR2 | List.test.tsx 密度、分隔线、圆角和边缘处理测试 |
每种密度;分隔线开启和关闭;每种边缘 | 忽略其 List 设置的行将失败。 | audit:ListItem/layout |
| FR3 | List.test.tsx “在 List 之外保留 ListItem 的缩进” |
List 之外的行 | 在 List 之外丢失缩进的行将失败。 | audit:ListItem/layout |
| FR4, AR3 | List.test.tsx 标记和 ListMarkerScope 测试 |
有标记、无标记、作用域标记、任务 | 缺失、多余或未标记的标记将失败。 | audit:ListItem/anatomy |
| AR2 | List.test.tsx 不可见按钮、锚点、禁用和选择测试 |
点击、href、禁用、选中 | 丢失的行语义将失败。 | audit:ListItem/accessibility |
| RTL 关系 | RTL 审计精选 D2 目标(apps/storybook/rtl-audit/targets.json)上的 List / Interactive |
起始图标和结束 chevron;LTR 和 RTL | 不在结束内容内联起始位置的起始内容将导致 D2 失败。 | audit:ListItem/i18n-rtl |
从源码读取,尚无聚焦测试:
- FR1:
interactiveRef、rel和ref到达 Item 行。 - FR2:分隔线边框和方形角。
bleed结束行圆角例外由ContainerCorners.a11y.chromium.spec.ts(component:ListFR5)检查。 - FR4:每个标记和任务复选框位于标签的第一行。
- FR3:
balanced密度、无分隔线,以及 List 之外无标记。 - FR4:每个项目符号标记的形状(圆点的填充、圆圈的环),以及数字标记及其计数器。
- FR5:
list-item目标,以及xstyle在 ListItem 的样式之后应用。
决策日志¶
未记录任何组件局部决策。
开放问题¶
无。
内容边界¶
本文件不重复使用者 prop 表、Item 的行行为,或 List 的边缘和几何规则。它链接到它们的拥有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx