swift-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

swift-patterns

Review, refactor, or build SwiftUI features with correct state management, modern API usage, optimal view composition, and performance-conscious patterns. Prioritize native APIs, Apple design guidance, and testable code structure. This skill focuses on facts and best practices without enforcing specific architectural patterns.

遵循正确的状态管理、现代API使用、最优视图组合和性能优先模式，审查、重构或构建SwiftUI功能。优先使用原生API、苹果设计指南和可测试的代码结构。本技能聚焦于事实和最佳实践，不强制要求使用特定的架构模式。

Workflow Decision Tree

工作流决策树

1) Review existing SwiftUI code

1) 审查现有SwiftUI代码

→ Read

references/workflows-review.md

for review methodology

Check state management against property wrapper selection (see
```
references/state.md
```
)
Verify view composition and extraction patterns (see
```
references/view-composition.md
```
)
Audit list performance and identity stability (see
```
references/lists-collections.md
```
)
Validate modern API usage (see
```
references/modern-swiftui-apis.md
```
)
Check async work patterns with .task (see
```
references/concurrency.md
```
)
Verify navigation implementation (see
```
references/navigation.md
```
)
Use Review Response Template (below)

→ 查看

references/workflows-review.md

了解审查方法

对照属性包装器选择规则检查状态管理（参考
```
references/state.md
```
）
验证视图组合和拆分模式（参考
```
references/view-composition.md
```
）
审核列表性能和标识稳定性（参考
```
references/lists-collections.md
```
）
校验现代API使用规范（参考
```
references/modern-swiftui-apis.md
```
）
检查使用.task的异步工作模式（参考
```
references/concurrency.md
```
）
验证导航实现逻辑（参考
```
references/navigation.md
```
）
使用下方的审查响应模板

2) Refactor existing SwiftUI code

2) 重构现有SwiftUI代码

→ Read

references/workflows-refactor.md

for refactor methodology

Extract complex views using playbooks (see
```
references/refactor-playbooks.md
```
)
Migrate deprecated APIs to modern equivalents (see
```
references/modern-swiftui-apis.md
```
)
Optimize performance hot paths (see
```
references/performance.md
```
)
Restructure state ownership (see
```
references/state.md
```
)
Apply common patterns (see
```
references/patterns.md
```
)
Use Refactor Response Template (below)

→ 查看

references/workflows-refactor.md

了解重构方法

使用操作手册拆分复杂视图（参考
```
references/refactor-playbooks.md
```
）
将废弃API迁移到现代等效方案（参考
```
references/modern-swiftui-apis.md
```
）
优化性能热点路径（参考
```
references/performance.md
```
）
调整状态所有权结构（参考
```
references/state.md
```
）
应用通用模式（参考
```
references/patterns.md
```
）
使用下方的重构响应模板

3) Implement new SwiftUI features

3) 实现新的SwiftUI功能

Design data flow first: identify owned vs injected state (see
```
references/state.md
```
)
Structure views for optimal composition (see
```
references/view-composition.md
```
)
Use modern APIs only (see
```
references/modern-swiftui-apis.md
```
)
Handle async work with .task modifier (see
```
references/concurrency.md
```
)
Apply performance patterns early (see
```
references/performance.md
```
)
Implement navigation flows (see
```
references/navigation.md
```
)

优先设计数据流：区分自有状态和注入状态（参考
```
references/state.md
```
）
结构设计支持最优视图组合（参考
```
references/view-composition.md
```
）
仅使用现代API（参考
```
references/modern-swiftui-apis.md
```
）
使用.task修饰符处理异步工作（参考
```
references/concurrency.md
```
）
提前应用性能优化模式（参考
```
references/performance.md
```
）
实现导航流程（参考
```
references/navigation.md
```
）

4) Answer best practice questions

4) 解答最佳实践相关问题

Load relevant reference file(s) based on topic (see Reference Files below)
Provide direct guidance with examples

If intent unclear, ask: "Do you want findings only (review), or should I change the code (refactor)?"

根据主题加载对应的参考文件（参考下方参考文件列表）
提供带示例的直接指导

如果意图不明确，请询问： "您只需要审查结果，还是需要我修改代码（重构）？"

Response Templates

响应模板

Review Response:

Scope - What was reviewed
Findings - Grouped by severity with actionable statements
Evidence - File paths or code locations
Risks and tradeoffs - What could break or needs attention
Next steps - What to fix first or verify

Refactor Response:

Intent + scope - What is being changed and why
Changes - Bulleted list with file paths
Behavior preservation - What should remain unchanged
Next steps - Tests or verification needed

审查响应：

范围 - 本次审查覆盖的内容
发现问题 - 按严重程度分组，附带可执行的整改说明
证据 - 文件路径或代码位置
风险与权衡 - 可能出现的故障或需要注意的点
下一步动作 - 需要优先修复或验证的内容

重构响应：

意图+范围 - 变更内容和变更原因
变更内容 - 带文件路径的项目符号列表
行为保留说明 - 哪些内容不会发生改变
下一步动作 - 需要进行的测试或验证

Quick Reference: Property Wrapper Selection

快速参考：属性包装器选择

Wrapper	Use When	Ownership
`@State`	Internal view state (value type or `@Observable` class)	View owns
`@Binding`	Child needs to modify parent's state	Parent owns
`@Bindable`	Injected `@Observable` object needing bindings	Injected
`let`	Read-only value from parent	Injected
`var` + `.onChange()`	Read-only value needing reactive updates	Injected

Key rules:

Always mark
```
@State
```
as
```
private
```
(makes ownership explicit)
Never use
```
@State
```
for passed values (accepts initial value only)
Use
```
@State
```
with
```
@Observable
```
classes (not
```
@StateObject
```
)

See

references/state.md

for detailed guidance and tradeoffs.

包装器	适用场景	所有权
`@State`	视图内部状态（值类型或 `@Observable` 类）	视图自有
`@Binding`	子视图需要修改父视图状态时	父视图所有
`@Bindable`	注入的 `@Observable` 对象需要生成绑定时	注入获得
`let`	从父视图传入的只读值	注入获得
`var` + `.onChange()`	需要响应式更新的只读值	注入获得

核心规则：

始终将
```
@State
```
标记为
```
private
```
（明确所有权）
永远不要对传入值使用
```
@State
```
（仅接收初始值）
```
@State
```
搭配
```
@Observable
```
类使用（而非
```
@StateObject
```
）

查看

references/state.md

获取详细指导和权衡说明。

Quick Reference: Modern API Replacements

快速参考：现代API替代方案

Deprecated	Modern Alternative	Notes
`foregroundColor()`	`foregroundStyle()`	Supports dynamic type
`cornerRadius()`	`.clipShape(.rect(cornerRadius:))`	More flexible
`NavigationView`	`NavigationStack`	Type-safe navigation
`tabItem()`	`Tab` API	iOS 18+
`onTapGesture()`	`Button`	Unless need location/count
`onChange(of:) { value in }`	`onChange(of:) { old, new in }` or `onChange(of:) { }`	Two or zero parameters
`UIScreen.main.bounds`	`GeometryReader` or layout APIs	Avoid hard-coded sizes

See

references/modern-swiftui-apis.md

for complete migration guide.

废弃API	现代替代方案	说明
`foregroundColor()`	`foregroundStyle()`	支持动态类型
`cornerRadius()`	`.clipShape(.rect(cornerRadius:))`	灵活性更高
`NavigationView`	`NavigationStack`	类型安全的导航
`tabItem()`	`Tab` API	iOS 18及以上可用
`onTapGesture()`	`Button`	除非需要获取点击位置/次数
`onChange(of:) { value in }`	`onChange(of:) { old, new in }` 或 `onChange(of:) { }`	两个参数或无参数
`UIScreen.main.bounds`	`GeometryReader` 或布局API	避免硬编码尺寸

查看

references/modern-swiftui-apis.md

获取完整迁移指南。

Review Checklist

审查清单

Use this when reviewing SwiftUI code:

审查SwiftUI代码时使用此清单：

State Management

状态管理

```
@State
```
properties marked
```
private
```
Passed values NOT declared as
```
@State
```
or
```
@StateObject
```
```
@Binding
```
only where child modifies parent state
Property wrapper selection follows ownership rules
State ownership clear and intentional

```
@State
```
属性已标记为
```
private
```
传入值未声明为
```
@State
```
或
```
@StateObject
```
仅在子视图需要修改父视图状态时使用
```
@Binding
```
属性包装器选择符合所有权规则
状态所有权清晰且符合设计意图

Modern APIs

现代API

No deprecated modifiers (foregroundColor, cornerRadius, etc.)
Using
```
NavigationStack
```
instead of
```
NavigationView
```
Using
```
Button
```
instead of
```
onTapGesture
```
when appropriate
Using two-parameter or no-parameter
```
onChange()
```

无废弃修饰符（foregroundColor、cornerRadius等）
使用
```
NavigationStack
```
而非
```
NavigationView
```
合适场景下使用
```
Button
```
而非
```
onTapGesture
```
使用双参数或无参数的
```
onChange()
```

View Composition

视图组合

Using modifiers over conditionals for state changes (maintains identity)
Complex views extracted to separate subviews
Views kept small and focused
View
```
body
```
simple and pure (no side effects)

使用修饰符而非条件语句处理状态变化（维持标识稳定）
复杂视图已拆分为独立子视图
视图保持精简、职责单一
视图
```
body
```
简单且纯函数化（无副作用）

Navigation & Sheets

导航与弹窗

Using
```
navigationDestination(for:)
```
for type-safe navigation
Using
```
.sheet(item:)
```
for model-based sheets
Sheets own their dismiss actions

使用
```
navigationDestination(for:)
```
实现类型安全导航
使用
```
.sheet(item:)
```
实现基于模型的弹窗
弹窗自身持有 dismiss 动作

Lists & Collections

列表与集合

```
ForEach
```
uses stable identity (never
```
.indices
```
for dynamic data)
Constant number of views per
```
ForEach
```
element
No inline filtering in
```
ForEach
```
(prefilter and cache)
No
```
AnyView
```
in list rows

```
ForEach
```
使用稳定标识（动态数据永远不要用
```
.indices
```
）
每个
```
ForEach
```
元素对应的视图数量固定
```
ForEach
```
内没有内联过滤逻辑（提前过滤并缓存）
列表行内没有
```
AnyView
```

Performance

性能

Passing only needed values to views (not large config objects)
Eliminating unnecessary dependencies
Checking value changes before state assignment in hot paths
Using
```
LazyVStack
```
/
```
LazyHStack
```
for large lists
No object creation in view
```
body
```

仅向视图传入需要的值（不传入大型配置对象）
消除不必要的依赖
热点路径下状态赋值前先检查值是否发生变化
长列表使用
```
LazyVStack
```
/
```
LazyHStack
```
视图
```
body
```
内没有创建对象的逻辑

Async Work

异步工作

Using
```
.task
```
for automatic cancellation
Using
```
.task(id:)
```
for value-dependent tasks
Not mixing
```
.onAppear
```
with async work

See reference files for detailed explanations of each item.

使用
```
.task
```
实现自动取消
依赖特定值的任务使用
```
.task(id:)
```
异步工作没有和
```
.onAppear
```
混用

查看参考文件获取每个条目的详细说明。

Constraints

约束

Swift/SwiftUI focus only - Exclude server-side Swift and UIKit unless bridging required
No Swift concurrency patterns - Use
```
.task
```
for SwiftUI async work
No architecture mandates - Don't require MVVM/MVC/VIPER or specific structures
No formatting/linting rules - Focus on correctness and patterns
No tool-specific guidance - No Xcode, Instruments, or IDE instructions

Citations allowed:

developer.apple.com/documentation/swiftui/

developer.apple.com/documentation/swift/

All workflows must follow these constraints.

仅聚焦Swift/SwiftUI - 除非需要桥接，否则不涉及服务端Swift和UIKit
不涉及Swift并发模式 - SwiftUI异步工作统一使用
```
.task
```
不强制架构要求 - 不要求使用MVVM/MVC/VIPER或特定结构
不涉及格式/ lint规则 - 聚焦正确性和模式
不提供特定工具指导 - 不包含Xcode、Instruments或其他IDE的使用说明

允许引用官方文档：

developer.apple.com/documentation/swiftui/

、

developer.apple.com/documentation/swift/

所有工作流都必须遵守上述约束。

Philosophy

设计理念

This skill focuses on facts and best practices from Apple's documentation:

Modern APIs over deprecated ones
Clear state ownership patterns
Performance-conscious view composition
Testable code structure
No architectural mandates (MVVM/VIPER not required)
Apple Human Interface Guidelines adherence

本技能聚焦于苹果官方文档给出的事实和最佳实践：

优先使用现代API而非废弃API
清晰的状态所有权模式
注重性能的视图组合
可测试的代码结构
不强制架构要求（不需要使用MVVM/VIPER）
遵守苹果人机交互指南

Reference Files

参考文件

All references in

references/

```
workflows-review.md
```
- Review methodology and findings taxonomy
```
workflows-refactor.md
```
- Refactor methodology and invariants
```
refactor-playbooks.md
```
- Step-by-step refactor guides
```
state.md
```
- Property wrappers and ownership patterns
```
navigation.md
```
- Navigation implementation patterns
```
view-composition.md
```
- View structure and extraction
```
lists-collections.md
```
- Identity and ForEach patterns
```
scrolling.md
```
- Scroll handling and pagination
```
concurrency.md
```
- Async work with .task
```
performance.md
```
- Optimization strategies
```
testing-di.md
```
- Testing and dependency injection
```
patterns.md
```
- Common SwiftUI patterns
```
modern-swiftui-apis.md
```
- Legacy API migration
```
code-review-refactoring.md
```
- Code quality checks

所有参考文件都在

references/

目录下：

```
workflows-review.md
```
- 审查方法和问题分类
```
workflows-refactor.md
```
- 重构方法和不变量
```
refactor-playbooks.md
```
- 分步重构指南
```
state.md
```
- 属性包装器和所有权模式
```
navigation.md
```
- 导航实现模式
```
view-composition.md
```
- 视图结构和拆分
```
lists-collections.md
```
- 标识和ForEach模式
```
scrolling.md
```
- 滚动处理和分页
```
concurrency.md
```
- 使用.task处理异步工作
```
performance.md
```
- 优化策略
```
testing-di.md
```
- 测试和依赖注入
```
patterns.md
```
- 通用SwiftUI模式
```
modern-swiftui-apis.md
```
- 遗留API迁移
```
code-review-refactoring.md
```
- 代码质量检查