跳转至

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-057 DEP-0017,其 astryx upgrade codemod 将 swipeActions 和 swipeBehavior 重写为 swipe={createSwipe(…)};这是从弃用版本开始的可选早期迁移,并将在 0.8.0 的升级中随 spec:AST-057 CLN-0025 的移除再次运行

消费者迁移说明属于消费者文档和发布说明。

当前状态影响

  • 标记是额外元素。 项目符号标记绘制为两个装饰性 span 元素,数字标记绘制为一个带有计数器伪元素的 span,位于行内容旁边。architecture:component-style-authoring INV7 将无语义角色的装饰放在伪元素上,而不是额外元素上。

所有权边界

拥有

  • 通过 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-061 FR11 和 component:List DEC-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:List FR5)检查。
  • FR4:每个标记和任务复选框位于标签的第一行。
  • FR3:balanced 密度、无分隔线,以及 List 之外无标记。
  • FR4:每个项目符号标记的形状(圆点的填充、圆圈的环),以及数字标记及其计数器。
  • FR5:list-item 目标,以及 xstyle 在 ListItem 的样式之后应用。

决策日志

未记录任何组件局部决策。

开放问题

无。

内容边界

本文件不重复使用者 prop 表、Item 的行行为,或 List 的边缘和几何规则。它链接到它们的拥有者。

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