swiftui-expert-skill

SwiftUI 专家技能

操作规则

• 每项任务开始时查阅 references/latest-apis.md，以避免使用已弃用的 API
• 优先使用原生 SwiftUI API，除非确有必要，否则避免通过 UIKit/AppKit 桥接
• 关注正确性和性能；不强制采用特定架构（MVVM、VIPER 等）
• 建议将业务逻辑与视图分离，以便测试，但不强制规定具体做法
• 遵循 Apple 人机界面指南和 API 设计模式
• 仅在用户明确提出要求时采用 Liquid Glass（参见 references/liquid-glass.md）
• 将性能优化作为建议，而非要求
• 对特定版本的 API 使用 #available 限制，并提供合理的回退方案

任务工作流

审查现有 SwiftUI 代码

• 阅读待审查的代码，并确定适用的主题
• 标记已弃用的 API（对照 references/latest-apis.md）
• 对每个相关主题运行下方的主题路由器
• 验证 iOS 26+ 功能的 #available 限制和回退路径

改进现有 SwiftUI 代码

• 根据主题路由器中的主题审核当前实现
• 使用 references/latest-apis.md 中的现代替代方案替换已弃用的 API
• 重构热点路径，减少不必要的状态更新
• 将复杂的视图主体提取为独立子视图
• 遇到 UIImage(data:) 时，建议对图像进行降采样（可选优化，参见 references/image-optimization.md）

实现新的 SwiftUI 功能

• 先设计数据流：确定哪些状态由视图持有，哪些由外部注入
• 组织视图以实现最佳差异计算（尽早提取子视图）
• 应用恰当的动画模式（隐式或显式、转场）
• 所有可点击元素均使用 Button；添加辅助功能分组和标签
• 使用 #available 限制特定版本的 API，并提供回退方案

主题路由器

针对当前任务中的每个相关主题，查阅对应的参考文件：

主题	参考文件
状态管理	references/state-management.md
视图组合	references/view-structure.md
性能	references/performance-patterns.md
列表和 ForEach	references/list-patterns.md
布局	references/layout-best-practices.md
工作表和导航	references/sheet-navigation-patterns.md
ScrollView	references/scroll-patterns.md
动画（基础）	references/animation-basics.md
动画（转场）	references/animation-transitions.md
动画（高级）	references/animation-advanced.md
辅助功能	references/accessibility-patterns.md
Swift Charts	references/charts.md
图表辅助功能	references/charts-accessibility.md
图像优化	references/image-optimization.md
Liquid Glass（iOS 26+）	references/liquid-glass.md
macOS 场景	references/macos-scenes.md
macOS 窗口样式	references/macos-window-styling.md
macOS 视图	references/macos-views.md
已弃用 API 查询	references/latest-apis.md

正确性检查清单

以下均为硬性规则——违反任何一条都属于错误：

• @State 属性必须为 private
• 仅在子视图需要修改父视图状态时使用 @Binding
• 传入的值绝不能声明为 @State 或 @StateObject（否则会忽略更新）
• 视图拥有的对象使用 @StateObject；注入的对象使用 @ObservedObject
• iOS 17+：对 @Observable 使用 @State；对需要绑定的注入式可观察对象使用 @Bindable
• ForEach 使用稳定标识（动态内容绝不使用 .indices）
• 每个 ForEach 元素包含固定数量的视图
• .animation(_:value:) 始终包含 value 参数
• iOS 26+ API 必须使用 #available 限制，并提供回退方案
• 使用图表类型的文件中必须包含 import Charts

参考资料

• references/latest-apis.md —— 每项任务都要先阅读。 从已弃用 API 迁移到现代 API（iOS 15+ 至 iOS 26+）
• references/state-management.md —— 属性包装器、数据流、@Observable 迁移
• references/view-structure.md —— 提取视图、容器模式、@ViewBuilder
• references/performance-patterns.md —— 热路径优化、更新控制、_logChanges()
• references/list-patterns.md —— ForEach 标识、Table（iOS 16+）、内联筛选的陷阱
• references/layout-best-practices.md —— 布局模式、GeometryReader 的替代方案
• references/accessibility-patterns.md —— VoiceOver、动态字体、分组、特征
• references/animation-basics.md —— 隐式／显式动画、时序、性能
• references/animation-transitions.md —— 视图转场、matchedGeometryEffect、Animatable
• references/animation-advanced.md —— 阶段／关键帧动画（iOS 17+）、@Animatable 宏（iOS 26+）
• references/charts.md —— Swift Charts 标记、坐标轴、选择、样式、Chart3D（iOS 26+）
• references/charts-accessibility.md —— 图表的 VoiceOver、Audio Graph、备用策略
• references/sheet-navigation-patterns.md —— 工作表、NavigationSplitView、检查器
• references/scroll-patterns.md —— ScrollViewReader、程序化滚动
• references/image-optimization.md —— AsyncImage、降采样、缓存
• references/liquid-glass.md —— iOS 26+ Liquid Glass 效果和回退模式
• references/macos-scenes.md —— 设置、MenuBarExtra、WindowGroup、多窗口
• references/macos-window-styling.md —— 工具栏样式、窗口大小、Commands
• references/macos-views.md —— HSplitView、Table、PasteButton、AppKit 互操作