swiftui

SwiftUI 卓越实践指南

SwiftUI 界面设计与构建实用指南，助你打造世界级体验，让应用与 Apple 自家应用并肩而立。

六项不可妥协的原则

1. 内容优先 — UI 是画框，不是画作
2. 除非有经验证的理由，否则使用系统组件 — 免费获得无障碍功能、平台行为和设计更新
3. 围绕状态而非屏幕进行设计 — 每个屏幕都要处理：加载、空状态、错误、离线、部分内容、权限被拒
4. 将无障碍视为约束条件 — 动态字体、VoiceOver、减弱动态效果／透明度、增强对比度
5. 性能也是一项功能 — 交互应“感觉即时”，出现卡顿时使用性能分析工具
6. 连贯胜过巧思 — 最好的界面让人觉得理所当然

快速参考：ADA 评分标准

类别	要求
愉悦感	只在成功时刻带来微小惊喜，绝不降低清晰度
创新	体现在内容发现、状态传达和简化复杂操作方面
交互	可预测、直接、宽容，符合平台习惯
包容性	支持 XXL+ 动态字体、VoiceOver；不只依靠颜色传达含义；支持减弱动态效果
视觉效果	节奏一致、材质协调、谨慎使用强调色

设计工作流（逐步进行）

1. 定义体验 — 用 10 行说明：目标、主要操作、状态、边缘情况、平台
2. 勾勒信息架构 — 选择 TabView、NavigationSplitView 或深层导航
3. 设计层级 — 每个时刻突出一个主视觉焦点和一个主要 CTA，并渐进式展示信息
4. 先构建设计令牌 — 间距、圆角、排版、动态效果、颜色
5. 构建组件 — 卡片、行、按钮、空状态、筛选器
6. 整合结构 — NavigationStack、NavigationSplitView、TabView、表单页
7. 添加动态效果 — 仅添加有助于理解和表达因果关系的效果
8. 检查无障碍功能与性能 — 动态字体、VoiceOver、Instruments

Liquid Glass 快速规则（iOS 26+）

应该：

• 将玻璃效果用于悬浮在内容上方的导航／控制层
• 在 GlassEffectContainer 中组合相邻的玻璃效果
• 为自定义控件使用 glassEffect(.interactive)
• 使用 glassEffectID 实现形变转场

不应该：

• 在内容层（表格、文档）使用玻璃效果
• 叠加玻璃效果
• 为所有内容添加色调 — 仅用于主要操作／含义表达
• 在工具栏后方设置自定义背景（让系统处理滚动边缘效果）

布局要点

容器	用途
List	大型数据集、选择、滑动操作、编辑模式
ScrollView + LazyVStack	自定义表面、卡片、混合内容
Grid	表单、设置、密集的结构化布局
LazyVGrid	自适应图库
NavigationSplitView	iPad／Mac 层级式应用
NavigationStack	深层导航流程

动画原则

• 动态效果传达因果关系、层级和连续性
• 使用由状态驱动的动画，而非命令式编排
• 使用弹簧效果呈现自然的 UI；使用缓入／缓出效果呈现淡入淡出
• 仅在标志性时刻使用自定义转场
• 始终提供减弱动态效果的替代方案

性能规则

规则	实现方式
Body 必须轻量	不要在 body 中进行排序、筛选、格式化或 I/O 操作
身份标识保持稳定	使用 ForEach(items, id: \.id) 而非 \.self；不要在 body 中调用 UUID()
保持依赖整洁	将 @State 保持在本地，传递 Binding 而非整个模型
使用性能分析工具	使用 SwiftUI instrument（Instruments 26）排查卡顿

无障碍功能检查清单

• 使用系统文本样式，XXL+ 字号下不裁切
• 布局能够自适应（堆叠布局转为垂直排列，行支持多行显示）
• 为不明显的控件设置 VoiceOver 标签／提示
• 焦点顺序与阅读顺序一致
• 触控目标至少为 44×44pt
• 减弱动态效果会移除视差并改用不透明度变化
• 减弱透明度会增强内容区分度

组件基元（构建这些组件）

1. 屏幕框架
2. 区块标题
3. 卡片表面
4. 列表行
5. 主要按钮／次要按钮／图标按钮
6. 空状态
7. 加载骨架屏
8. 错误横幅
9. 表单字段行
10. 标签／标记／胶囊

完整参考

如需查看完整的实现模式、代码方案、设计令牌、Liquid Glass 详情以及完整的 ADA 审查清单：

请参阅：swiftui-playbook.md