Back to Details

swiftui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SwiftUI Excellence Playbook

SwiftUI 卓越实践手册

Tactical guide for designing and building world-class SwiftUI interfaces—the kind that feel at home next to Apple's own apps.
这是一份设计和构建世界级SwiftUI界面的实用指南——打造出与苹果原生应用质感一致的界面。

Six Non-Negotiables

六大核心原则

  1. Content first — UI is a frame, not the painting
  2. System components unless measured reason not to — buy accessibility, platform behavior, design updates for free
  3. Design for states, not screens — every screen handles: loading, empty, error, offline, partial, permission denied
  4. Accessibility is a constraint — Dynamic Type, VoiceOver, Reduce Motion/Transparency, Increased Contrast
  5. Performance is a feature — "feels instant" interactions, instrument when hitches occur
  6. Coherence over cleverness — best interfaces feel inevitable
  1. 内容优先 — UI是框架，而非画作本身
  2. 优先使用系统组件 — 除非有充分理由不使用，这样可免费获得无障碍支持、平台原生行为和设计更新
  3. 针对状态设计，而非仅针对屏幕 — 每个界面需处理：加载中、空状态、错误、离线、部分加载、权限拒绝等场景
  4. 无障碍访问是硬性要求 — 需支持Dynamic Type、VoiceOver、减少动态效果/透明度、增强对比度
  5. 性能是核心特性 — 交互需“感觉即时响应”，出现卡顿时代入工具分析
  6. 一致性优先于炫技 — 优秀的界面会让用户觉得理所当然

Quick Reference: ADA Rubric

快速参考：ADA评估准则

CategoryRequirement
DelightMicro-delight at success moments only, never reduces clarity
InnovationIn discovery, state communication, simplifying complexity
InteractionPredictable, direct, forgiving, platform-appropriate
InclusivityDynamic Type XXL+, VoiceOver, no color-only meaning, reduced motion
VisualsConsistent rhythm, coherent materials, restrained tint
类别要求
愉悦感仅在成功时刻添加微交互愉悦感，且不得降低界面清晰度
创新性体现在交互探索、状态传递、简化复杂度上
交互性可预测、直接、容错性强、符合平台规范
包容性支持Dynamic Type XXL+、VoiceOver，不依赖颜色传递信息，提供减少动态效果选项
视觉设计节奏一致、材质统一、色调克制

Design Workflow (Step-by-Step)

设计工作流（分步指南）

  1. Define experience — 10-line spec: goal, primary action, states, edge cases, platforms
  2. Sketch IA — TabView vs NavigationSplitView vs deep navigation
  3. Design hierarchy — one hero, one primary CTA per moment, progressive disclosure
  4. Build tokens first — spacing, radius, typography, motion, colors
  5. Build components — cards, rows, buttons, empty states, filters
  6. Integrate structure — NavigationStack, NavigationSplitView, TabView, Sheets
  7. Add motion — only what improves comprehension and causality
  8. Accessibility + performance pass — Dynamic Type, VoiceOver, Instruments
  1. 定义体验目标 — 撰写10行以内的规格说明：目标、核心操作、状态、边缘情况、适配平台
  2. 绘制信息架构草图 — 选择TabView、NavigationSplitView还是深度导航模式
  3. 设计层级结构 — 每个场景突出一个核心内容和一个主要操作，采用渐进式信息披露
  4. 先构建设计令牌 — 定义间距、圆角、字体、动效、颜色规范
  5. 构建组件 — 卡片、列表行、按钮、空状态、筛选器等
  6. 整合界面结构 — 集成NavigationStack、NavigationSplitView、TabView、Sheets等
  7. 添加动效 — 仅添加能提升因果传递和层级感知的动效
  8. 无障碍访问与性能检测 — 验证Dynamic Type、VoiceOver支持，使用Instruments分析性能

Liquid Glass Quick Rules (iOS 26+)

Liquid Glass 快速规则（iOS 26+）

Do:
  • Use glass for navigation/control layer floating above content
  • Group nearby glass in 
    GlassEffectContainer
  • Use 
    glassEffect(.interactive)
    for custom controls
  • Use 
    glassEffectID
    for morphing transitions
Don't:
  • Glass on content layer (tables, documents)
  • Glass on glass stacking
  • Tint everything — only primary actions/meaning
  • Custom backgrounds behind toolbars (let system handle scroll edge effects)
推荐做法：
  • 为悬浮在内容上方的导航/控制层使用玻璃效果
  • 将相邻的玻璃效果组件放入
    GlassEffectContainer
    中
  • 为自定义控件使用
    glassEffect(.interactive)
  • 使用
    glassEffectID
    实现形态过渡动画
禁止做法：
  • 不要在内容层（表格、文档）使用玻璃效果
  • 不要嵌套玻璃效果
  • 不要给所有元素添加色调，仅为核心操作/关键信息添加
  • 不要在工具栏后添加自定义背景（让系统处理滚动边缘效果）

Layout Essentials

布局要点

ContainerUse For
List
Large datasets, selection, swipe actions, edit mode
ScrollView
+ 
LazyVStack
Custom surfaces, cards, mixed content
Grid
Forms, settings, dense structured layouts
LazyVGrid
Responsive galleries
NavigationSplitView
iPad/Mac hierarchical apps
NavigationStack
Deep navigation flows
容器组件适用场景
List
大型数据集、选择操作、滑动操作、编辑模式
ScrollView
+ 
LazyVStack
自定义界面、卡片、混合内容
Grid
表单、设置页面、密集结构化布局
LazyVGrid
响应式画廊
NavigationSplitView
iPad/Mac 层级式应用
NavigationStack
深度导航流程

Animation Principles

动画原则

  • Motion communicates causality, hierarchy, continuity
  • State-driven animation, not imperative choreography
  • Springs for organic UI, ease-in/out for fades
  • Custom transitions for signature moments only
  • Always provide Reduce Motion fallback
  • 动效用于传递因果关系、层级结构、连续性
  • 采用状态驱动的动画，而非命令式编排
  • 弹簧动画用于自然的UI过渡，淡入淡出使用缓入缓出曲线
  • 仅在标志性场景使用自定义过渡动画
  • 始终提供减少动态效果的替代方案

Performance Rules

性能规则

RuleImplementation
Body must be cheapNo sorting, filtering, formatting, I/O in body
Stable identity
ForEach(items, id: \.id)
not 
\.self
, no UUID() in body
Dependency hygieneKeep @State local, pass Binding not whole model
InstrumentUse SwiftUI instrument (Instruments 26) for hitches
规则实现方式
Body计算必须轻量化不要在body中进行排序、过滤、格式化、I/O操作
稳定的标识使用
ForEach(items, id: \.id)
而非
\.self
，不要在body中生成UUID()
依赖管理规范保持@State的局部性，传递Binding而非整个模型
工具分析使用SwiftUI工具（Instruments 26）分析卡顿问题

Accessibility Checklist

无障碍访问检查清单

  • System text styles, no clipping at XXL+
  • Layout adapts (stacks turn vertical, rows multi-line)
  • VoiceOver labels/hints on non-obvious controls
  • Focus order matches reading order
  • 44×44pt minimum touch targets
  • Reduced Motion removes parallax, uses opacity
  • Reduced Transparency increases separation
  • 使用系统文本样式，XXL+字号下无内容截断
  • 布局自适应（堆叠转为垂直排列，行变为多行）
  • 为非直观控件添加VoiceOver标签/提示
  • 焦点顺序与阅读顺序一致
  • 触摸目标最小尺寸为44×44pt
  • 减少动态效果模式下移除视差，使用透明度过渡
  • 减少透明度模式下增强元素间的区分度

Component Primitives (Build These)

基础组件（需自行构建）

  1. Screen scaffold
  2. Section header
  3. Card surface
  4. List row
  5. Primary/secondary/icon buttons
  6. Empty state
  7. Loading skeleton
  8. Error banner
  9. Form field row
  10. Chip/tag/pill
  1. 界面框架
  2. 分区标题
  3. 卡片容器
  4. 列表行
  5. 主要/次要/图标按钮
  6. 空状态
  7. 加载骨架屏
  8. 错误提示条
  9. 表单字段行
  10. 标签/芯片/胶囊组件

Full Reference

完整参考

For complete implementation patterns, code recipes, design tokens, Liquid Glass details, and the full ADA review checklist:
See: swiftui-playbook.md
如需完整的实现模式、代码示例、设计令牌、Liquid Glass细节以及完整的ADA评估检查清单：
请查看：swiftui-playbook.md