跳转至

ListItem (Swift) 组件契约

契约一览

领域 契约
公共契约 ListItem(_ label:, description:, align:, href:, isDisabled:, isSelected:, startContent:, endContent:, onClick:) 和 ListItem(_ props: ListItemProps, startContent:, endContent:),一个泛型 SwiftUI View。
行为 以周围 List 的密度、标记、分隔线和边缘绘制 component:swift/Item:在标签首行显示一个圆点、一个圆环或其行号;分隔线之间的转角为直角;在贴边(flush)列表中无内联内缩。
终端用户影响 用户在 iPhone 上看到的项目符号列表、编号列表、设置列表和分隔列表,其布局与 Web 端一致;无论行如何换行,每个标记都位于该行首行的旁边。
构建方影响 应用将 ListItem 放入 List;该行采用列表的外观。滑动操作、target 和 rel 没有对应的 Swift 形式。
兼容性/就绪度 增量式:新增一个视图、生成的 ListItemProps,以及 Item 上的内部列表钩子。草稿;已在 macOS 和 iOS 模拟器上构建并测试;变更附有设备截图。
审查检查项 拒绝以下情况:标记处于标签首行之外、行忽略所属列表的密度、分隔线带有圆角、贴边(flush)列表中出现内缩,或列表样式泄漏到嵌套在插槽中的行。
约束规则 spec:AST-082 FR3、FR4、FR7;spec:AST-093 FR1–FR5;component:swift/Item;packages/native/specs/swift/library/ 下的 Swift 组件 API、插槽、主题环境和无障碍记录。

此表为审查概览;下文正文为权威内容。

意图

在 Apple 平台上,ListItem 是一个属于列表的行:它绘制为 Item,并采用列表的密度、标记、分隔线和边缘,因此列表中的每一行都能保持一致,应用无需重复设置这些属性。

兼容性与迁移

  • 已发布默认值保留:not yet released
  • 兼容性类别:增量式(additive)
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明应放在消费者文档和发布说明中。

职责边界

负责

  • 读取周围的列表,并向 Item 传递其密度、标记、内联内缩和边角。
  • 绘制标记:圆点、圆环或该行的编号。

不负责 / 非目标

  • 行的布局、文本、状态和点击——由 component:swift/Item 负责。
  • 编号、行间分隔线和列表边缘——由包含这些行的列表负责。
  • 滑动操作——目前仅限 Web(component:swift/Item DEC-1)。

公共概念

概念 封闭取值或状态 含义 变体/方向/状态下的可用性 默认值 负责方 稳定性 无效值行为
标记 无、圆点、圆环、数字 该行从所属列表样式中获得的列表标记 位于带标记样式的列表中时 无 component:ListItem 实验性 无
列表 位于列表中;单独使用 在列表中,该行采用列表的外观;单独使用时,它是一个普通的 Item 始终 单独使用 component:swift/ListItem 实验性 无

行为与布局契约

ID 候选不变量 依据 草稿审查状态
FR1 该行 MUST 绘制为 component:swift/Item,带有自己的标签、描述、对齐方式、链接、点击和状态,并具有周围列表的密度;单独使用时 MUST 完全绘制为该 Item。 核心 ListItem 验证
FR2 在具有标记样式的列表中,该行 MUST 在其起始内容之前绘制一个标记,位于宽度为 space.s4 的列中,该列随 Dynamic Type 缩放,并且在每一行上都相同:对于 disc,是一个以 color.textPrimary 填充的 6 点圆点;对于 circle,是一个以 color.textPrimary 描边 1 点的 6 点圆环;对于 decimal,则是其数字和一个句点,采用正文排版并使用表格数字,结束于列尾,使列表中的每个句点都对齐,正如核心的编号标记所做的那样。比列更宽的数字会延伸到该行的内联内边距中;比列和该内边距都更宽的数字会在列表的每一行上同样地加宽该列,因此任何数字都不会移动其所在行的文字、与文字重叠或被截断,并且每一行都保持列表的文本边缘。对于每种对齐方式,标记的中心都位于标签第一行框的中心。 核心 ListItem 标记 验证
FR3 在带有分隔线的列表中,该行 MUST 以直角绘制其背景;在齐平列表中,它 MUST 没有内联内边距,因此其内容和背景达到列表边缘。 核心 ListItem withDivider、edgeFlush 验证
FR4 列表的处理方式、外观和编号 MUST 仅应用于该行,而不应用于嵌套在其起始或结束内容中的行。 核心 ListContext 作用域 验证
FR5 两个初始化器 MUST 构建相同的 ListItemProps。槽位是泛型 @ViewBuilder 闭包,具有空默认值;单个尾随闭包是起始内容,onClick 位于最后。基础属性通过 ListItemProps 传入。由逻辑核心发送的 ListItem 节点会在这些槽位中绘制其起始和结束内容节点(spec:AST-082 FR19)。 Swift 组件 API A2–A4、A7;槽位 S3 验证

允许的变化

  • AV1 — 标记绘制。 圆点和圆环是处于核心尺寸的 SwiftUI 形状,而非 CSS 盒子。

代表性状态

状态 必需不变量 允许的变化
单独 与 Item 相同 无
在列表中:每种密度 列表的内边距 无
圆点、圆圈、数字标记 对于每种对齐方式,均位于标签的首行 AV1
分隔线;齐平 直角;无内联缩进 无
浅色与深色 各主题的颜色 无

转换与优先级顺序

  • ORD1 — 密度。 列表的密度 → balanced。

性能与资源

  • PR1 — 一次额外测量。 在带标记的列表中,居中对齐的行会测量其文字,以便将标记放在首行;其他行不进行任何测量。
  • PR2 — 编号。 在列表中,行向列表报告一次其身份,列表按行出现的顺序为行编号。带编号的行还会报告其编号的宽度,列表据此调整一个共享列的尺寸。

无障碍契约

  • AR1 — 单行。 该行是 Item 的唯一元素;数字标记会作为该行的一部分被首先朗读(“3. 搅拌面糊”);圆点或圆环被隐藏(Swift accessibility X5)。
  • AR2 — 不测量渲染后的树。 测试断言视图所设置的内容;在存在应用托管的 target 之前,不测量渲染后的无障碍树。

设计关系

解剖结构或状态 设计需求 呈现权威 层级角色 组件契约
行和标记 Apple Human Interface Guidelines 中的 Lists and tables 由核心规定 支持 FR1–FR3

该组件实现设计需求,但不照搬其设计理由。

平台控件:自身没有控件;该行是 component:swift/Item,它指明其使用的 SwiftUI 控件(spec:AST-093 FR2)。指南页面:Apple Human Interface Guidelines 中的 Lists and tables 和 Accessibility。

读取的主题值:space.s4、color.textPrimary、正文排版,以及通过 Item 读取的其令牌。

家族与系统关系

  • component:swift/Item 拥有该行;本记录仅说明列表行额外添加的内容。
  • component:ListItem 拥有 props 和标记。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1 ListItemTests.swift 的单独渲染与密度渲染 单独;紧凑列表和宽松列表 与单独状态下的 Item 不同的行,或忽略密度的行,将失败 audit:swift/ListItem/row
FR2, AR1 ListItemTests.swift 中的 number、numbering、column、period-alignment、shared-column、first-line、largest-text、two-theme 和 read-aloud 测试 decimal;从 3 开始的编号;"1." 和 "10.";一个比列宽和缩进都宽的数字;最大文本尺寸下的 "9.";每种对齐方式及最大文本尺寸下的 disc;neutral 与 butter 缺少或错误的数字、未对齐的句点、列在数字适合缩进时变宽或未对每一行变宽、标记偏离第一行、使用独立颜色,或朗读点失败 audit:swift/ListItem/marker
FR3 ListItemTests.swift 中的 flush 和 divider 渲染 带内边距与 flush;带分隔线与不带分隔线 flush 列表中出现缩进,或分隔线之间出现圆角,则失败 audit:swift/ListItem/edge
FR4 ListItemTests.swift 中的 nested-row 测试 位于某行结束内容中的一行 嵌套行带有列表的标记或缩进时失败 audit:swift/ListItem/scope
FR5 ListItemTests.swift 中的 initializer 和 wire-slot 测试;contracts.test.ts 两种 initializer;一个带有开始内容的 wire 节点 props 不一致,或 wire 节点的插槽未绘制,则失败 audit:swift/ListItem/api

决策日志

未记录任何组件级决策。

未决问题

无。

内容边界

本文件不重复使用者 prop 表格/示例、当前审计结果、实施步骤或家族/系统规则。它链接到其所有者。

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