axiom-uikit

UIKit 与桥接

任何 UIKit 桥接、Auto Layout、Combine、TextKit 或 UIKit 动画相关工作都必须使用此技能。

无法启动 Axiom Agent？ 如果此路由将你引导至某个 Agent，请直接按照其流程操作。通过 MCP，axiom_get_agent 会返回该流程；在其他环境中，请读取下面的文件，该操作只需搜索和读取文件。

此处可用：skills/resize-auditor.md。

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

快速参考

症状 / 任务	参考
UIViewRepresentable、UIViewControllerRepresentable	参见 skills/uikit-bridging.md
在 UIKit 中嵌入 SwiftUI（UIHostingController）	参见 skills/uikit-bridging.md
Coordinator 模式、updateUIView 生命周期	参见 skills/uikit-bridging.md
构建自适应 UIKit 布局：参考线、宽度条件约束、组合式布局、自适应尺寸单元格	参见 skills/adaptive-layout.md
“Unable to simultaneously satisfy constraints”	参见 skills/auto-layout-debugging.md
约束冲突、布局不明确	参见 skills/auto-layout-debugging.md
视图未显示、位置不正确	参见 skills/auto-layout-debugging.md
CAAnimation 完成处理程序未触发	参见 skills/uikit-animation-debugging.md
设备上的弹簧物理效果不正确、时长不匹配	参见 skills/uikit-animation-debugging.md
动画卡顿、CATransaction 时序	参见 skills/uikit-animation-debugging.md
Combine 发布者、AnyCancellable 生命周期	参见 skills/combine-patterns.md
@Published 属性、Combine ↔ async/await	参见 skills/combine-patterns.md
何时使用 Combine 与 async/await	参见 skills/combine-patterns.md
需要 UIScene 生命周期、可调整大小的应用、尺寸类别、标签栏侧边栏 OS27	参见 skills/uikit-modernization.md
iPhone 镜像兼容性：间接输入、配套 Face ID、竖屏陷阱	参见 skills/uikit-modernization.md
场景边界：拆除、激活请求、按场景恢复、外接显示器、activeAppearance	参见 skills/uikit-modernization.md
导航栏标题和副标题：UINavigationItem.subtitle、largeSubtitleView、attributedTitle/attributedSubtitle、副标题文本属性（iOS 26）	参见 skills/uikit-modernization.md
自动调整大小就绪情况扫描（场景生命周期、UIScreen.main、固定画布、镜像输入、iPhone Duo）	启动 resize-auditor Agent 或 /axiom:audit resize
UIKit 中的 iPhone Duo：竖向栏、折叠处、外侧显示屏上的窗口请求	参见 axiom-swiftui（skills/iphone-duo.md）——UIKit 对应项位于各 SwiftUI API 旁
TextKit 2 架构、NSTextLayoutManager	参见 skills/textkit-ref.md
写作工具集成（iOS 26）	参见 skills/textkit-ref.md
视口渲染表面、附件复用、可折叠文本 OS27	参见 skills/textkit-ref.md
SwiftUI TextEditor、TextKit 1 迁移	参见 skills/textkit-ref.md
语法检查（UITextChecker）、逐边文本块边框 OS27	参见 skills/textkit-ref.md
PencilKit 画布、PKToolPicker、绘图持久化	参见 skills/pencilkit-paperkit.md
Apple Pencil Pro（捏压、笔杆滚转、悬停、触觉反馈）	参见 skills/pencilkit-paperkit.md
手写识别（PKStrokeRecognizer）、笔画身份/切片 OS27	参见 skills/pencilkit-paperkit-ref.md
PaperKit 标注画布（形状、图像、文本与绘图）	参见 skills/pencilkit-paperkit-ref.md
PaperKit 程序化标注模型（子元素、装饰项）OS27	参见 skills/pencilkit-paperkit-ref.md

决策树

digraph uikit {
    start [label="UIKit task" shape=ellipse];
    what [label="What do you need?" shape=diamond];

    start -> what;
    what -> "skills/uikit-bridging.md" [label="wrap UIKit in SwiftUI\nor SwiftUI in UIKit"];
    what -> "skills/adaptive-layout.md" [label="build adaptive layout\n(guides, constraint sets,\ncompositional)"];
    what -> "skills/auto-layout-debugging.md" [label="constraint errors,\nlayout issues"];
    what -> "skills/uikit-animation-debugging.md" [label="CAAnimation bugs,\nspring physics,\ncompletion handlers"];
    what -> "skills/combine-patterns.md" [label="publishers, sinks,\n@Published,\nasync/await bridge"];
    what -> "skills/textkit-ref.md" [label="text layout,\nWriting Tools,\nTextKit migration"];
    what -> "skills/pencilkit-paperkit.md" [label="drawing canvas,\nApple Pencil,\nPaperKit markup"];
    what -> "skills/uikit-modernization.md" [label="scene lifecycle (required 27),\nresizable apps,\nsize classes"];
}

0. 场景生命周期迁移、“应用在 27 上无法启动”、可调整大小、尺寸类别、标签页侧边栏？→ skills/uikit-modernization.md 0b. 应用在 iPhone Mirroring 中表现异常（手势失效、Face ID 被阻止、布局卡在竖屏）？→ skills/uikit-modernization.md 0c. iPhone Duo／可折叠 iPhone（竖条、折痕、外屏窗口请求）？→ axiom-swiftui（skills/iphone-duo.md）
1. UIViewRepresentable / UIViewControllerRepresentable / UIHostingController？→ skills/uikit-bridging.md
2. “Unable to simultaneously satisfy constraints”／布局问题？→ skills/auto-layout-debugging.md 2b. 构建自适应布局（布局指南、尺寸类别约束集、组合式列计算、自调整大小的单元格）？→ skills/adaptive-layout.md
3. CAAnimation 缺少完成回调／弹簧物理效果不对／动画卡顿？→ skills/uikit-animation-debugging.md
4. Combine 发布者／AnyCancellable／@Published／Combine ↔ async 桥接？→ skills/combine-patterns.md
5. TextKit 2 / Writing Tools / TextEditor / 从 TextKit 1 迁移？→ skills/textkit-ref.md
6. PencilKit 画布／Apple Pencil／PaperKit 标注？→ skills/pencilkit-paperkit.md
7. 纯 SwiftUI 视图问题（不涉及 UIKit 桥接）？→ /skill axiom-swiftui
8. 设计决策、HIG、Liquid Glass、SF Symbols、排版？→ /skill axiom-design
9. 在 UIKit 回调中阻止循环引用？→ 参阅 axiom-performance（skills/objc-block-retain-cycles.md）
10. Combine 订阅导致的内存泄漏？→ 先从 skills/combine-patterns.md 入手，如果泄漏仍然存在，再查看 axiom-performance

冲突解决

uikit 与 swiftui：编写 UI 代码时：

• 在 SwiftUI 中封装 UIKit 或反过来封装，或者调试 UIKit 特有问题（Auto Layout、CAAnimation）时，使用 uikit
• 编写纯 SwiftUI 视图、导航、布局和动画时，使用 swiftui

uikit 与 concurrency：Combine 与 async/await 交互时：

• 桥接 Combine 工作流与 async/await 时，使用 uikit（skills/combine-patterns.md）
• 编写纯 async/await 模式、actor、Sendable 时，使用 concurrency

uikit 与 performance：动画或布局导致性能问题时：

1. 先尝试 uikit——大多数动画卡顿都是 CATransaction 时序或图层状态问题，而不是性能分析问题
2. 仅当动画逻辑正确但渲染缓慢时，才使用 performance

uikit 与 axiom-data：@Published 属性与数据持久化相关时：

• 处理 Combine 发布者模式和 @Published 生命周期时，使用 uikit
• 处理 SwiftData/Core Data 模型层问题时，使用 axiom-data

避免自我合理化

想法	实际情况
“我直接用 UIHostingController 就行，很简单”	Hosting 有尺寸调整、生命周期和导航方面的边缘情况。skills/uikit-bridging.md 介绍了这些注意事项。
“Auto Layout 错误只是警告，我忽略就好”	未满足的约束会导致运行时布局不可预测。现在就修复它们。
“我知道 CAAnimation 怎么工作”	90% 的 CAAnimation 问题都出在 CATransaction 时序，而不是 Core Animation。请查看 skills/uikit-animation-debugging.md。
“Combine 已经过时了，直接用 async/await 重写吧”	Combine 没有弃用通知。重写能正常工作的工作流是在浪费时间。skills/combine-patterns.md 介绍了何时迁移、何时维护。
“TextKit 1 仍然很好用”	TextKit 1 缺少 Writing Tools 集成，并且存在 Apple 不会修复的已知布局问题。请参阅 skills/textkit-ref.md。
“我把 cancellable 存在局部变量里就行”	局部 AnyCancellable 会立即释放，导致订阅终止。
“我把 PKCanvasView 归档起来保存绘图”	归档视图会丢失可编辑性。请持久化 drawing.dataRepresentation()。请参阅 skills/pencilkit-paperkit.md。
“我的工具选择器不显示，肯定是 API 有问题”	调用 setVisible(_:forFirstResponder:) 后，画布必须调用 becomeFirstResponder()。请参阅 skills/pencilkit-paperkit.md。

示例调用

用户：“如何在 SwiftUI 中封装 UIKit 视图？” → 阅读：skills/uikit-bridging.md

用户：“我遇到了‘Unable to simultaneously satisfy constraints’错误。” → 阅读：skills/auto-layout-debugging.md

用户：“我的 CAAnimation 完成处理程序始终不会触发。” → 阅读：skills/uikit-animation-debugging.md

用户：“这种情况应该用 Combine 还是 async/await？” → 阅读：skills/combine-patterns.md

用户：“如何将 Writing Tools 集成到我的文本编辑器中？” → 阅读：skills/textkit-ref.md

用户：“如何添加带有工具选取器的 Apple Pencil 绘图画布？” → 阅读：skills/pencilkit-paperkit.md

用户：“如何添加带有形状和文本的 PaperKit 标注画布？” → 阅读：skills/pencilkit-paperkit-ref.md

用户：“我的 SwiftUI 视图因 Combine 订阅而发生内存泄漏。” → 阅读：skills/combine-patterns.md

用户：“如何在我的 UIKit 应用中嵌入 SwiftUI？” → 阅读：skills/uikit-bridging.md

用户：“审核我的应用是否支持屏幕尺寸调整。” → 启动 resize-auditor Agent（或运行 /axiom:audit resize）

用户：“我的自定义捏合手势在应用运行于 iPhone Mirroring 时停止工作。” → 阅读：skills/uikit-modernization.md

用户：“如何根据窗口宽度调整集合视图的列数？” → 阅读：skills/adaptive-layout.md