跳转至

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