Item (Swift) 组件契约¶
契约一览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | Item(_ label:, description:, align:, density:, labelLines:, descriptionLines:, layout:, href:, isHighlighted:, isSelected:, isDisabled:, startContent:, endContent:, marker:, onClick:) 和 Item(_ props: ItemProps, startContent:, endContent:, marker:),一个泛型 SwiftUI View。 |
| 行为 | 绘制 core 的行:marker、start content、位于描述上方或旁边的标签、end content,并应用 core 的密度内边距、对齐方式、行数限制以及高亮、选中和禁用外观。当提供 href 时它是一个 SwiftUI Link;仅提供 onClick 时则是一个 SwiftUI Button。 |
| 最终用户影响 | 用户看到的列表、菜单和设置行与 Web 端排列一致、阅读体验一致,可以点击整行,VoiceOver 会按插槽顺序朗读每一行及其选中或变暗状态。 |
| 构建方影响 | 插槽通过闭包接受任意 SwiftUI 视图;单个尾随闭包即 start content。滑动操作、target、rel 和 data-testid 没有对应的 Swift 形式。 |
| 兼容性/就绪状态 | 增量式:新增一个视图和生成的 ItemProps。草稿;已在 macOS 和 iOS 模拟器上构建和测试;设备截图已附在变更中。 |
| 评审检查 | 拒绝以下情况:插槽类型为 AnyView;作为链接或按钮时绘制不同的行;静态行被扩展到触摸目标大小;被禁用的链接仍会打开;颜色不是主题令牌;或行无法兑现的滑动属性。 |
| 治理规则 | spec:AST-082 FR3、FR4、FR7;spec:AST-093 FR1–FR5;位于 packages/native/specs/swift/library/ 下的 Swift 组件 API (A2–A4, A7, A9)、插槽 (S1, S3–S5)、主题环境和无障碍 (X1, X2, X5, X7) 记录。 |
此表是评审投影;下文正文才具有权威性。
意图¶
Item 在 Apple 平台上是 core 的行原语:列表行、菜单行和设置行的共享布局,使用主题令牌以及 SwiftUI 自身的链接和按钮控件绘制。
兼容性与迁移¶
- 已发布默认值保留:
not yet released - 兼容性类别:增量式
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移指引应放在消费者文档和发布说明中。
所有权边界¶
拥有
- 行的插槽顺序、间距、每种密度下的内边距,以及 start 和 end content 相对于文字的对齐方式。
- 行数限制、标签和描述类型,以及高亮、选中和禁用外观。
- 在不改变绘制效果的前提下切换到 SwiftUI
Link或Button,以及行的无障碍元素。
不拥有 / 非目标
- props 的含义——由
component:Item拥有。 - 列表标记、分隔线和边缘——由承载这些行的列表拥有。
- 插槽绘制的内容:
Icon、Avatar或任何视图都保持其自身的大小和外观(Swift 插槽 S4:未设置大小的 Avatar 保持为md)。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 插槽 | marker、startContent、endContent | 通过 @ViewBuilder 闭包传入的任意 SwiftUI 视图 |
始终 | 空 | component:Item |
实验性 | 无 |
| 密度 | compact、balanced、spacious |
块方向内边距为 spacing 1、2、3;行内内边距为 2,spacious 时为 3 | 始终 | balanced |
component:Item |
实验性 | 无 |
| 对齐 | center、start、firstLine |
插槽相对于文字居中、位于其顶部,或位于标签首行 | 始终 | center |
component:Item |
实验性 | 无 |
| 布局 | stacked、inline |
描述位于标签下方或旁边 | 有描述时 | stacked |
component:Item |
实验性 | 无 |
| 控件 | 静态、链接(href)、按钮(onClick) |
点击的行为方式;绘制效果相同 | 始终 | 静态 | component:swift/Item |
实验性 | 不是绝对 URL 的 href 不会成为链接 |
行为与布局约定¶
| ID | 候选不变量 | 依据 | 草稿审查状态 |
|---|---|---|---|
| FR1 | 行 MUST 按顺序排列 marker、start content、words 和 end content,它们之间的间距为 space.s2;words 占据剩余宽度;在 compact、balanced 或 spacious 下,块级内边距分别为 space.s1、s2 或 s3,行内内边距为 space.s2,spacious 时为 s3。 |
core Item styles |
verify |
| FR2 | 标签 MUST 以正文字体和 color.textPrimary 绘制,描述以辅助字体和 color.textSecondary 绘制,并分别限制在 labelLines 或 descriptionLines 行内并在超出后截断:未设置时为一行,为零时则每一行都截断,与 core 的 row 行为一致。每行使用主题的 leading,并随 Dynamic Type 缩放。使用 inline 且有描述时,描述位于标签旁边,间距为 space.s1,标签不收缩;没有描述时,标签保持其行数限制。 |
core Item styles |
verify |
| FR3 | center MUST 将每个槽位在 words 上居中;start MUST 将每个槽位的顶部与 words 的顶部对齐;firstLine MUST 将每个槽位在标签的第一行上居中。 |
core Item align |
verify |
| FR4 | isSelected MUST 在行后方绘制 color.accentMuted,isHighlighted 绘制 color.overlayHover,选中态优先,并使用元素圆角。isDisabled MUST 以半透明度绘制 words 和 end content,与 core 一致;marker 和 start content 保持自身外观。被按下的按钮或链接行会在其选中或高亮填充之上绘制 color.overlayPressed,与 core 一致。 |
core Item styles |
verify |
| FR5 | 当 href 是绝对 URL(带有协议)时,该行 MUST 是 SwiftUI Link,且 onClick 不会运行。在 core 中,链接是标签,点击行上其他位置会运行 onClick;而 SwiftUI Link 占据整行,因此 Swift 行没有这样的区域。脚本 URL(javascript:、vbscript:)或 data: URL 中的 HTML 文档 MUST 使该行保持无响应,绝不能成为链接,因为 core 的导航目标会拒绝它们(family:navigation-destinations FR4)。非绝对 URL(例如 Web 路径)的 href MUST 停止开发构建,并显示一条指出该 href 的消息;发布构建则绘制不带链接的行。仅有 onClick 时,使用 SwiftUI Button。可点击的行至少 44 点高;静态行保持 core 的高度。禁用的链接或按钮仍可访问,读作变暗,且不执行任何操作。 |
Swift 组件 API A4;Swift 辅助功能 X2、X7 | 验证 |
| FR6 | 两个初始化器 MUST 构建相同的 ItemProps。槽位是带有空默认值的泛型 @ViewBuilder 闭包,绝不使用 AnyView;单个尾随闭包用作起始内容,而 onClick 位于最后。基础属性通过 ItemProps 传递:设置 isHidden 时视图不绘制任何内容;id 成为辅助功能标识符。 |
Swift 组件 API A2–A4、A7;Swift 槽位 S3 | 验证 |
允许的变化¶
- AV1 — 触控高度。 可点击的行至少 44 点高,可能高于 core 的紧凑或均衡行。
- AV2 — 行度量。 行的高度来自主题的 leading 叠加于系统字体自身行高之上,因此自定义字体可能相差一个点。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 每种密度 | core 的块级和内联内边距 | 无 |
| 标签和描述,两种布局 | 描述位于标签下方或旁边 | 无 |
| 带有高槽位的每种对齐方式 | 槽位居中、位于顶部或第一行 | 无 |
| 选中、高亮、禁用 | 每种外观均来自主题;选中优先 | 无 |
| 静态、链接、按钮 | 相同的绘制;可点击的行至少 44 点 | AV1 |
| 浅色与深色,两套主题 | 每套主题的颜色 | 无 |
转换与优先级顺序¶
- ORD1 — 背景。 选中 → 高亮 → 无。
- ORD2 — 控件。
href(链接)→onClick(按钮)→ 静态。
性能与资源¶
- PR1 — 无类型擦除。 槽位是泛型的,因此该行不会增加
AnyView装箱。
辅助功能契约¶
- AR1 — 每行一个元素。 静态行是一个元素,其标签按顺序读取槽位:标记、起始内容、标签、描述、结束内容。链接或按钮行是一个链接或按钮元素,以相同方式读取(Swift 辅助功能 X5;Swift 槽位 S5)。
- AR2 — 状态。 选中的行读作“已选中”。禁用的行保留在 VoiceOver 顺序中,并读作“变暗”(X1、X2)。
- AR3 — 触控目标。 可点击的行至少 44 点高(X7)。
- AR4 — 不测量渲染树。 测试断言视图设置的内容;在应用托管的测试目标存在之前,不测量渲染后的辅助功能树。
设计关系¶
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Row | Apple Human Interface Guidelines,列表和表格 | 由 core 规定 | 辅助 | FR1–FR5 |
该组件实现设计需求,但不复述其背后的理由。
平台控件:SwiftUI List 曾被考虑但不适用:它是一个滚动容器,拥有自己的行,而 core 的 Item 是位于任何容器中的行,包括 Card、Section 或对话框(spec:AST-093 FR2)。该行使用 SwiftUI Link 和 Button 处理点击,并自行绘制布局。指南页面:Apple Human Interface Guidelines 中的列表和表格、按钮和辅助功能。
读取的主题值:space.s1、space.s2、space.s3、radius.element、color.textPrimary、color.textSecondary、color.accentMuted、color.overlayHover、color.overlayPressed、正文和支持字体,以及 Dynamic Type。
家族与系统关系¶
component:Item拥有 props、插槽和行的外观;本记录仅说明 Swift 如何绘制它们。- 列表拥有其行的标记、分隔线和边缘。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR2 | ItemTests.swift 密度、行距、行数限制和最大文本渲染 |
每种密度;一行和三行标签;最大文本尺寸 | 如果内边距、行距或行数限制错误,或行不能增长,则失败 | audit:swift/Item/layout |
| FR3 | ItemTests.swift 对齐渲染 |
带描述的 start 和 center;高于一行的插槽的 firstLine |
如果插槽偏离文字的顶部、中间或标签首行,则失败 | audit:swift/Item/align |
| FR4 | ItemTests.swift 背景、双主题和禁用渲染 |
选中、高亮、两者;中性、奶油色;禁用 | 如果 token 错误、高亮盖过选中,或禁用行未变暗,则失败 | audit:swift/Item/states |
| FR5, AR2 | ItemTests.swift 触控高度渲染;点击、trait、linkURL 和拒绝目标地址测试 |
静态、按钮、链接;选中;空 href;javascript:、vbscript: 和 data:text/html href |
如果可点击行过短、静态行被拉伸或缺少选中 trait,则失败;如果被拒绝的目标地址变成链接,则失败 | audit:swift/Item/control |
| FR6 | ItemTests.swift 初始化器、尾随闭包、隐藏和 wire-slot 测试;contracts.test.ts |
两种初始化器;每个插槽;isHidden |
如果 props 不一致、闭包填充了错误的插槽,或隐藏行仍被绘制,则失败;wire 节点的插槽未被绘制则失败 | audit:swift/Item/api |
决策日志¶
DEC-1 — 滑动操作目前仅限 Web¶
参考: component:swift/Item/DEC-1
决策者: cixzhang,2026-10-31
swipeActions 没有 Swift 形式。SwiftUI 的滑动操作仅适用于 SwiftUI List 内部的行,因此任何其他位置的 Item 都无法支持它们;iPhone 或 Mac 上的用户改为使用行自身的操作或行尾内容。Swift 形式要等到行在任何位置都能支持滑动操作后再实现。
开放问题¶
无。
内容边界¶
本文件不重复使用者 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx