swift-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swift Apps

Swift应用

Engineer native-feeling Apple-platform software with SwiftUI-first patterns, clear state ownership, platform fidelity, accessibility, and performance discipline. Default to direct, readable code that works with Apple frameworks instead of layering web-style abstractions onto SwiftUI.

采用SwiftUI优先的模式、清晰的状态所有权、平台一致性、无障碍设计以及性能规范，打造具有原生质感的Apple平台软件。优先编写直接、易读且适配Apple框架的代码，而非在SwiftUI上叠加Web风格的抽象层。

Choose The Track

选择工作路径

New feature or screen: Define the target platform, app archetype, primary action, core states, navigation model, and data ownership before writing code. Then load references/architecture-and-state.md and references/ui-patterns.md.
Refactor or cleanup: Preserve behavior, simplify structure, reduce indirection, and make state ownership obvious. Then load references/architecture-and-state.md.
Bug fix: Reproduce first with a failing test when the project has a workable test harness. Enumerate 2-3 hypotheses before changing code. Then load references/performance-and-debugging.md and any domain-specific reference.
Performance or jank: Start code-first, then move to profiling if review is inconclusive. Load references/performance-and-debugging.md.
Liquid Glass or new design-system APIs: Use native materials and availability gating, not custom blur imitations. Load references/liquid-glass.md.
macOS-specific work: Treat menu commands, keyboard flows, windows, sidebars, toolbars, and text behavior as product requirements, not polish. Load references/macos-quality-bar.md.
Version-sensitive API questions: When the exact current API shape matters, load references/official-docs-map.md first and trust Apple docs over memory.

新功能或新页面：编写代码前，先确定目标平台、应用原型、核心操作、核心状态、导航模型以及数据所有权。然后加载references/architecture-and-state.md和references/ui-patterns.md。
重构或清理：保留原有功能，简化结构，减少间接调用，明确状态所有权。然后加载references/architecture-and-state.md。
Bug修复：若项目具备可用的测试框架，先编写失败测试用例复现问题。修改代码前先列出2-3个假设。然后加载references/performance-and-debugging.md及相关领域参考文档。
性能优化或卡顿处理：先从代码层面排查，若评审无法确定问题再进行性能分析。加载references/performance-and-debugging.md。
Liquid Glass或新设计系统API：使用原生材质和可用性控制，而非自定义模糊效果。加载references/liquid-glass.md。
macOS专属开发：将菜单命令、键盘流程、窗口、侧边栏、工具栏和文本行为视为产品需求，而非优化项。加载references/macos-quality-bar.md。
版本敏感API问题：当需要明确当前API的具体形态时，先加载references/official-docs-map.md，优先参考Apple官方文档而非依赖记忆。

Apply The Core Rules

遵循核心规则

Prefer system structure before custom structure. Use
```
NavigationStack
```
,
```
NavigationSplitView
```
,
```
TabView
```
,
```
List
```
,
```
Form
```
,
```
Table
```
,
```
Commands
```
, and built-in materials before custom containers.
Design for states, not screenshots. Every feature should account for loading, empty, error, offline, partial, and permission-restricted states.
Keep state close to the view that owns it. Use
```
@State
```
,
```
@Binding
```
,
```
@Bindable
```
,
```
@Environment
```
,
```
@Observable
```
,
```
@Query
```
, and
```
.task
```
as the default toolset. Introduce a view model only when the existing codebase already relies on them or when non-view orchestration truly needs a reference type.
Keep
```
body
```
cheap and identity stable. Do not sort, filter, format, decode images, create UUIDs, or perform I/O in
```
body
```
. Precompute or cache expensive work, and use stable IDs.
Compose small views with explicit inputs. Prefer narrow data and bindings over passing large models everywhere. Split large bodies into focused subviews instead of piling more logic into one type.
Treat accessibility and motion as first-class constraints. Verify Dynamic Type, VoiceOver, reduced motion, reduced transparency, contrast, focus order, and touch target size.
Match the platform. iPhone, iPad, Mac, and Vision Pro have different interaction contracts. Preserve platform idioms unless the product has a measured reason to diverge.

优先使用系统结构而非自定义结构。优先使用
```
NavigationStack
```
、
```
NavigationSplitView
```
、
```
TabView
```
、
```
List
```
、
```
Form
```
、
```
Table
```
、
```
Commands
```
及内置材质，再考虑自定义容器。
针对状态设计，而非仅针对截图。每个功能都需考虑加载、空数据、错误、离线、部分加载及权限受限状态。
状态尽可能靠近所属视图。默认使用
```
@State
```
、
```
@Binding
```
、
```
@Bindable
```
、
```
@Environment
```
、
```
@Observable
```
、
```
@Query
```
和
```
.task
```
作为工具集。仅当现有代码库已依赖视图模型，或非视图编排确实需要引用类型时，才引入视图模型。
保持
```
body
```
代码轻量化且标识稳定。不要在
```
body
```
中进行排序、过滤、格式化、图片解码、创建UUID或I/O操作。预先计算或缓存耗时操作，并使用稳定ID。
组合小型视图并使用明确输入。优先传递窄范围数据和绑定，而非到处传递大型模型。将大型
```
body
```
拆分为专注的子视图，而非在单个类型中堆积更多逻辑。
将无障碍设计和动效视为一等约束。验证动态字体、VoiceOver、减少动效、减少透明度、对比度、焦点顺序和触摸目标尺寸。
匹配平台特性。 iPhone、iPad、Mac和Vision Pro有不同的交互约定。除非产品有明确的理由偏离，否则需遵循平台惯例。

Load The Right Reference

加载对应参考文档

Need	Load
State ownership, Observation, async flow, routing, dependency injection	references/architecture-and-state.md
Container choice, component composition, sheets, navigation, app-shell wiring	references/ui-patterns.md
Jank, invalidation storms, layout thrash, profiling, bug triage, verification	references/performance-and-debugging.md
Menu bar, shortcuts, windows, sidebars, toolbars, Mac polish, AppKit escape hatches	references/macos-quality-bar.md
Liquid Glass placement, modifier order, containers, availability, transitions	references/liquid-glass.md
Official Apple docs and WWDC sessions for state, navigation, scenes, Liquid Glass, and performance	references/official-docs-map.md

需求	加载文档
状态所有权、Observation、异步流程、路由、依赖注入	references/architecture-and-state.md
容器选择、组件组合、弹窗、导航、应用框架连接	references/ui-patterns.md
卡顿、无效风暴、布局抖动、性能分析、Bug分类、验证	references/performance-and-debugging.md
菜单栏、快捷方式、窗口、侧边栏、工具栏、macOS优化、AppKit兼容方案	references/macos-quality-bar.md
Liquid Glass布局、修饰符顺序、容器、可用性、过渡效果	references/liquid-glass.md
关于状态、导航、场景、Liquid Glass和性能的Apple官方文档及WWDC会话	references/official-docs-map.md

Deliver The Result

交付成果规范

Start by naming the target platform, app archetype, and primary interaction model.
Call out the chosen state and data-flow approach whenever the architecture is non-obvious.
Use previews for fast iteration, but verify critical behavior in Simulator or on device when scenes, windows, focus, animation, or performance are involved.
When reviewing, report the highest-risk issues first: correctness, platform mismatch, accessibility gaps, performance risks, then style.
When debugging, share the leading hypotheses, the evidence that ruled them in or out, and the final root cause.
Finish with verification steps: tests, build or lint commands, profiling passes, and any manual checks still needed.

首先明确目标平台、应用原型和核心交互模型。
当架构不明显时，说明所选的状态和数据流方案。
使用预览进行快速迭代，但涉及场景、窗口、焦点、动画或性能时，需在模拟器或真机上验证关键行为。
评审时，优先报告高风险问题：正确性、平台不匹配、无障碍设计缺口、性能风险，其次是代码风格。
调试时，分享主要假设、验证假设的证据以及最终根因。
最后提供验证步骤：测试、构建或 lint 命令、性能分析流程，以及仍需手动检查的内容。