axiom-swiftui

SwiftUI

任何 SwiftUI 工作都必须使用此技能，包括视图、状态、导航、布局、动画、架构、手势和调试。

**Claude Code 中捆绑的工具：**如果 command -v <tool> 没有找到任何内容（hooks 关闭或使用了 --bare），请改用 <plugin-root>/tools/<tool>，而不是直接使用工具名称；<plugin-root> 是此技能的 Base directory for this skill: 路径向上两级的目录。

无法启动 Axiom Agent？ 如果此路由将你指向某个 Agent，请直接按其流程操作。通过 MCP 时，axiom_get_agent 会返回该流程；其他情况下，请读取下方对应文件，只需进行文件搜索和读取即可。

此处可用：skills/swiftui-architecture-auditor.md、skills/swiftui-layout-auditor.md、skills/swiftui-nav-auditor.md、skills/swiftui-performance-analyzer.md、skills/textkit-auditor.md、skills/ux-flow-auditor.md。 位于另一个套件中：axiom-design/skills/liquid-glass-auditor.md。

对于任何其他 Agent，通过 MCP 使用 axiom_get_agent 也能获取其流程；请使用 axiom_xclog_*、axiom_xcsym_* 和 axiom_xcprof_* 工具执行其 xclog、xcsym 和 xcprof 步骤。其他情况下，请在 Axiom 的技能中搜索 skills/<agent>.md；如果没有该文件，请使用此套件的技能自行完成相关工作，并使用 PATH 中的任意 Axiom 工具。

快速参考

症状／任务	参考
视图未更新	参阅 skills/debugging.md
调试后视图仍无法更新	参阅 skills/debugging-diag.md
预览缓慢／构建优质预览／@Previewable／PreviewModifier／变体矩阵	参阅 skills/previews.md
预览 API 参考（#Preview、特征、模式、Development Assets）	参阅 skills/previews-ref.md
预览崩溃／无法加载	参阅 skills/debugging.md（Preview Crashes 部分）
热重载／实时编辑／在设备上编辑正在运行的应用	参阅 skills/hot-reload.md
导航问题	参阅 skills/nav.md
调试后导航仍有问题	参阅 skills/nav-diag.md
导航 API 参考	参阅 skills/nav-ref.md
iPad／旋转时布局错乱	参阅 skills/layout.md
调整大小／旋转时状态丢失（滚动、选择、焦点、草稿）	参阅 skills/layout.md（State Survives the Transition）
布局 API 参考	参阅 skills/layout-ref.md
性能／卡顿／滚动缓慢	参阅 skills/swiftui-performance.md
架构／可测试性	参阅 skills/architecture.md
每次视图初始化时都会重建 @State 对象，或运行时忽略 init 赋值	参阅 skills/architecture.md（@State 现在是宏）
动画问题	参阅 skills/animation-ref.md
堆栈／网格／大纲	参阅 skills/containers-ref.md
自定义容器／List 替代方案（iOS 18+）	参阅 skills/containers-ref.md 第 7 部分
搜索实现	参阅 skills/search-ref.md
工具栏、ToolbarItem、sheet 按钮位置、自定义	参阅 skills/toolbars.md
导航副标题：navigationSubtitle、.title／.subtitle／.largeTitle／.largeSubtitle 位置（iOS 26）	参阅 skills/toolbars.md（模式 14）
工作表、停靠点、弹出框、fullScreenCover、呈现适配	参阅 skills/presentations.md
多列 Table、可排序／可调整大小的列（iPad／Mac；紧凑模式下折叠为首列）	参阅 axiom-macos（skills/swiftui-differences.md）
检查器面板（.inspector——常规宽度下为尾随列，紧凑模式下为工作表）	参阅 axiom-macos（skills/swiftui-differences.md）
手势冲突	参阅 skills/gestures.md
分区索引——列表尾随边缘的垂直 A–Z 索引条／字母快速滚动器、跳转到分区	参阅 skills/26-ref.md（Section Index）
列表分区边距／Section 周围的内边距	参阅 skills/26-ref.md（Section Margins）
Web 内容——WebView／WebPage、滚动修饰符、NavigationStack 中的 WebView	参阅 skills/26-ref.md（WebView & WebPage）
iPhone Duo／折叠屏 iPhone：姿态、竖条、折叠处、排列方式、铰链、场景配件（SwiftUI 和 UIKit）	参阅 skills/iphone-duo.md
iOS 26 功能	参阅 skills/26-ref.md

非 SwiftUI 界面路径

这些主题属于更广泛的 iOS 界面领域，但位于单独的套件中：

UIKit 问题

• Auto Layout 冲突 → 参阅 axiom-uikit（skills/auto-layout-debugging.md）
• 动画时序 → 参阅 axiom-uikit（skills/uikit-animation-debugging.md）
• SwiftUI ↔ UIKit 桥接 → 参阅 axiom-uikit（skills/uikit-bridging.md）

设计与指南

• 采用 Liquid Glass → 参阅 axiom-design（skills/liquid-glass.md）
• SF Symbols → 参阅 axiom-design（skills/sf-symbols.md）
• 符合 HIG → 参阅 axiom-design（skills/hig.md）
• 排版 → 参阅 axiom-design（skills/typography-ref.md）
• TextKit／富文本 → 参阅 axiom-uikit（skills/textkit-ref.md）

其他

• tvOS（焦点、遥控器、文本输入）→ 参阅 axiom-swift（skills/tvos.md）
• 应用级组合（根视图、身份验证、场景）→ 参阅 axiom-design（skills/app-composition.md）
• 拖放、共享、复制／粘贴 → 参阅 axiom-swift（skills/transferable-ref.md）
• VoiceOver、动态字体 → /skill axiom-accessibility
• UI 测试不稳定 → /skill axiom-testing
• UX 流程死胡同、无法关闭的陷阱 → 启动 ux-flow-auditor agent

watchOS 专用模式

• 一目了然的 UI、手表导航、智能叠放小组件 → 参见 axiom-watchos

冲突解决

axiom-swiftui 与 axiom-performance：当 UI 响应缓慢时（例如“SwiftUI List 很慢”）：

1. 先尝试 axiom-swiftui — 特定领域的修复（LazyVStack、视图标识、@State 优化）通常能在 5 分钟内解决 UI 性能问题
2. 只有领域修复无效时才使用 axiom-performance — 性能分析耗时更长，而且可能只是确认领域知识已经掌握的情况

决策树

digraph swiftui {
    start [label="SwiftUI issue" shape=ellipse];
    what [label="What's wrong?" shape=diamond];

    start -> what;
    what -> "skills/debugging.md" [label="view not updating"];
    what -> "skills/nav.md" [label="navigation"];
    what -> "skills/swiftui-performance.md" [label="slow/lag"];
    what -> "skills/layout.md" [label="adaptive layout"];
    what -> "skills/containers-ref.md" [label="stacks/grids/outlines"];
    what -> "skills/architecture.md" [label="feature architecture"];
    what -> "skills/animation-ref.md" [label="animations"];
    what -> "skills/gestures.md" [label="gestures"];
    what -> "skills/search-ref.md" [label="search"];
    what -> "skills/toolbars.md" [label="toolbars / sheet buttons"];
    what -> "skills/presentations.md" [label="sheets/detents/popovers"];
    what -> "skills/26-ref.md" [label="iOS 26 features"];
    what -> "skills/iphone-duo.md" [label="iPhone Duo / foldable"];
    what -> "skills/previews.md" [label="slow previews / building good previews"];
    what -> "skills/previews-ref.md" [label="preview API reference"];
    what -> "skills/debugging.md" [label="preview crashes / won't load"];
    what -> "skills/hot-reload.md" [label="hot reload / live editing"];
    what -> "axiom-macos (skills/swiftui-differences.md)" [label="Table / .inspector\n(large-window density)"];
    what -> "axiom-uikit (skills/uikit-bridging.md)" [label="UIKit interop"];
    what -> "axiom-design (skills/app-composition.md)" [label="app-level (root, auth)"];
    what -> "axiom-swift (skills/transferable-ref.md)" [label="drag/drop, sharing"];
}

自动扫描

• 架构审计 → 启动 swiftui-architecture-auditor Agent
• 性能扫描 → 启动 swiftui-performance-analyzer Agent 或 /axiom:audit swiftui-performance
• 导航审计 → 启动 swiftui-nav-auditor Agent 或 /axiom:audit swiftui-nav
• 布局审计 → 启动 swiftui-layout-auditor Agent 或 /axiom:audit swiftui-layout
• UX 流程审计 → 启动 ux-flow-auditor Agent 或 /axiom:audit ux-flow
• Liquid Glass 扫描 → 启动 liquid-glass-auditor Agent 或 /axiom:audit liquid-glass（检测迁移机会和采用完整性缺口：媒体表面的变体规范、玻璃表面嵌套、未设置样式的 26 之前版本回退、语义化工具栏位置、Tab(role: .search)、UIDesignRequiresCompatibility 退出选项；评分为 ADOPTED / PARTIAL / NOT ADOPTED）
• TextKit 扫描 → 启动 textkit-auditor Agent 或 /axiom:audit textkit（检测回退触发条件、会破坏复杂脚本的字形 API、缺少 Writing Tools 接线，以及架构缺口，例如缺少回退观察、SwiftUI 封装丢弃 TextKit 2 属性、缺少 isWritingToolsActive 守卫；评分为 MODERN / MIXED / LEGACY）

反合理化

想法	实际情况
“SwiftUI 布局很简单，没必要看。”	SwiftUI 布局有 12 个易踩的坑。skills/layout.md 涵盖了所有这些问题。
“我知道 NavigationStack 的工作原理。”	导航涉及状态恢复、深层链接和身份陷阱。skills/nav.md 可避免花 2 小时调试。
“只是视图没有更新而已。”	视图更新失败有 4 个根本原因。skills/debugging.md 可在 5 分钟内诊断问题。
“我只要加上 .animation() 就行。”	动画问题会不断叠加。skills/animation-ref.md 提供了正确的模式。
“不需要架构设计。”	即使是小功能，也能从职责分离中受益。skills/architecture.md 可避免重构债务。
“我知道 .searchable。”	搜索有 6 个易踩的坑。skills/search-ref.md 涵盖了所有这些问题。
“我只要加个 Done 按钮就行。”	不带 Cancel 的工作表不符合 HIG（更新于 2026-03-24）。.cancellationAction / .confirmationAction 会自动生成符合 HIG 的布局——规则见 skills/toolbars.md 的模式 2。
“工作表就是工作表，不用配置。”	Detent、紧凑模式适配、背景交互和 iOS 18 尺寸设置决定了工作表在不同窗口形状下的表现。skills/presentations.md 涵盖了适配方面的陷阱（横向工作表会悄然变成全屏覆盖层）。
“预览永远都很慢，我还是用模拟器吧。”	skills/previews.md 提供了 5 种具体的修复方法。规则 4（关闭自动刷新）只需 30 秒，通常就能让感知到的卡顿减半。
“我读过发行说明，知道 Xcode 27 中的 @State 是惰性初始化的。”	只有当属性是 private / fileprivate 并且部署目标为 iOS 17 或更高版本时才成立——低于 iOS 17 时，private 情况会悄然沿用旧的立即初始化行为。skills/architecture.md 说明了适用条件、3 个 TN3211 问题，以及 1 个能编译但运行时有误的问题。
“我只要为这个预览里的 @State 写个包装视图就行。”	@Previewable @State（Xcode 16+）可以省去这些样板代码。宏签名见 skills/previews-ref.md。
“我每次都重新构建并重新启动就行。”	热重载会直接修改正在运行的应用，并保留状态。skills/hot-reload.md 介绍了 InjectionNext + Inject 的设置，以及通过 xclog 验证的流程。
“Duo 只不过是大一号的 iPhone；我的布局本来就会调整大小。”	栏目会移到侧边，折叠处会把屏幕分开，而且外屏无法打开窗口。skills/iphone-duo.md 涵盖了仅调整大小无法解决的问题。