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/ItemDEC-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