axiom-uikit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UIKit & Bridging

UIKit 与桥接

You MUST use this skill for ANY UIKit bridging, Auto Layout, Combine, TextKit, or UIKit animation work.

任何涉及UIKit桥接、Auto Layout、Combine、TextKit或UIKit动画的工作，都必须使用本技能。

Quick Reference

快速参考

Symptom / Task	Reference
UIViewRepresentable, UIViewControllerRepresentable	See `skills/uikit-bridging.md`
Embedding SwiftUI in UIKit (UIHostingController)	See `skills/uikit-bridging.md`
Coordinator pattern, updateUIView lifecycle	See `skills/uikit-bridging.md`
"Unable to simultaneously satisfy constraints"	See `skills/auto-layout-debugging.md`
Constraint conflicts, ambiguous layout	See `skills/auto-layout-debugging.md`
Views not appearing, positioned incorrectly	See `skills/auto-layout-debugging.md`
CAAnimation completion handler not firing	See `skills/uikit-animation-debugging.md`
Spring physics wrong on device, duration mismatch	See `skills/uikit-animation-debugging.md`
Animation jank, CATransaction timing	See `skills/uikit-animation-debugging.md`
Combine publishers, AnyCancellable lifecycle	See `skills/combine-patterns.md`
@Published properties, Combine ↔ async/await	See `skills/combine-patterns.md`
When to use Combine vs async/await	See `skills/combine-patterns.md`
TextKit 2 architecture, NSTextLayoutManager	See `skills/textkit-ref.md`
Writing Tools integration (iOS 26)	See `skills/textkit-ref.md`
SwiftUI TextEditor, TextKit 1 migration	See `skills/textkit-ref.md`

症状/任务	参考文档
UIViewRepresentable、UIViewControllerRepresentable	查看 `skills/uikit-bridging.md`
在UIKit中嵌入SwiftUI（UIHostingController）	查看 `skills/uikit-bridging.md`
Coordinator模式、updateUIView生命周期	查看 `skills/uikit-bridging.md`
"无法同时满足约束条件"	查看 `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 vs async/await	查看 `skills/combine-patterns.md`
TextKit 2架构、NSTextLayoutManager	查看 `skills/textkit-ref.md`
写作工具集成（iOS 26）	查看 `skills/textkit-ref.md`
SwiftUI TextEditor、TextKit 1迁移	查看 `skills/textkit-ref.md`

Decision Tree

决策树

dot

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/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"];
}

UIViewRepresentable / UIViewControllerRepresentable / UIHostingController? →
```
skills/uikit-bridging.md
```
"Unable to simultaneously satisfy constraints" / layout bugs? →
```
skills/auto-layout-debugging.md
```
CAAnimation completion missing / spring physics wrong / animation jank? →
```
skills/uikit-animation-debugging.md
```
Combine publishers / AnyCancellable / @Published / Combine ↔ async bridge? →
```
skills/combine-patterns.md
```
TextKit 2 / Writing Tools / TextEditor / TextKit 1 migration? →
```
skills/textkit-ref.md
```
Pure SwiftUI view question (no UIKit bridging)? →
```
/skill axiom-swiftui
```
Design decisions, HIG, Liquid Glass, SF Symbols, typography? →
```
/skill axiom-design
```
Block retain cycles in UIKit callbacks? → See axiom-performance (
```
skills/objc-block-retain-cycles.md
```
)
Memory leaks from Combine subscriptions? → Start with
```
skills/combine-patterns.md
```
, then axiom-performance if leak persists

dot

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/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"];
}

涉及UIViewRepresentable / UIViewControllerRepresentable / UIHostingController？→
```
skills/uikit-bridging.md
```
出现"无法同时满足约束条件" / 布局bug？→
```
skills/auto-layout-debugging.md
```
CAAnimation完成回调丢失 / 弹簧物理效果异常 / 动画卡顿？→
```
skills/uikit-animation-debugging.md
```
涉及Combine发布者 / AnyCancellable / @Published / Combine ↔ async桥接？→
```
skills/combine-patterns.md
```
涉及TextKit 2 / 写作工具 / TextEditor / TextKit 1迁移？→
```
skills/textkit-ref.md
```
纯SwiftUI视图问题（无UIKit桥接）？→
```
/skill axiom-swiftui
```
设计决策、HIG、Liquid Glass、SF Symbols、排版？→
```
/skill axiom-design
```
UIKit回调中的循环引用问题？→ 查看axiom-performance（
```
skills/objc-block-retain-cycles.md
```
）
Combine订阅导致内存泄漏？→ 先查看
```
skills/combine-patterns.md
```
，若泄漏仍存在再使用axiom-performance

Conflict Resolution

冲突解决

uikit vs swiftui: When working with UI code:

Use uikit when wrapping UIKit in SwiftUI or vice versa, or debugging UIKit-specific issues (Auto Layout, CAAnimation)
Use swiftui for pure SwiftUI views, navigation, layout, animations

uikit vs concurrency: When Combine interacts with async/await:

Use uikit (
```
skills/combine-patterns.md
```
) for bridging Combine pipelines with async/await
Use concurrency for pure async/await patterns, actors, Sendable

uikit vs performance: When animations or layout cause performance issues:

Try uikit FIRST — Most animation jank is CATransaction timing or layer state, not a profiling issue
Only use performance if animation logic is correct but rendering is slow

uikit vs axiom-data: When @Published properties relate to data persistence:

Use uikit for Combine publisher patterns and @Published lifecycle
Use axiom-data for SwiftData/Core Data model layer concerns

uikit vs swiftui：处理UI代码时：

使用uikit：当需要在SwiftUI中封装UIKit或反之，或调试UIKit特定问题（Auto Layout、CAAnimation）时
使用swiftui：用于纯SwiftUI视图、导航、布局、动画

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

使用uikit（
```
skills/combine-patterns.md
```
）：用于Combine管道与async/await的桥接
使用concurrency：用于纯async/await模式、actors、Sendable

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

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

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

使用uikit：用于Combine发布者模式和@Published生命周期管理
使用axiom-data：用于SwiftData/Core Data模型层相关问题

Anti-Rationalization

误区纠正

Thought	Reality
"I'll just use UIHostingController, it's simple"	Hosting has sizing, lifecycle, and navigation edge cases. `skills/uikit-bridging.md` covers the gotchas.
"Auto Layout error is just a warning, I'll ignore it"	Unsatisfied constraints cause unpredictable layout at runtime. Fix them now.
"I know how CAAnimation works"	90% of CAAnimation bugs are CATransaction timing, not Core Animation. Check `skills/uikit-animation-debugging.md` .
"Combine is dead, just rewrite with async/await"	Combine has no deprecation notice. Rewriting working pipelines wastes time. `skills/combine-patterns.md` covers when to migrate vs maintain.
"TextKit 1 still works fine"	TextKit 1 misses Writing Tools integration and has known layout bugs Apple won't fix. See `skills/textkit-ref.md` .
"I'll store cancellables in a local variable"	Local AnyCancellable deallocates immediately, killing the subscription.

错误想法	实际情况
"我直接用UIHostingController就行，很简单"	UIHostingController存在尺寸、生命周期和导航的边缘情况。 `skills/uikit-bridging.md` 涵盖了这些陷阱。
"Auto Layout错误只是警告，我可以忽略"	未满足的约束会导致运行时布局不可预测。现在就修复它们。
"我知道CAAnimation怎么用"	90%的CAAnimation bug是CATransaction时序问题，而非Core Animation本身。请查看 `skills/uikit-animation-debugging.md` 。
"Combine已经过时了，直接用async/await重写就行"	Combine没有被弃用的通知。重写可用的管道是浪费时间。 `skills/combine-patterns.md` 涵盖了何时迁移 vs 何时维护。
"TextKit 1仍然能用得很好"	TextKit 1缺少写作工具集成，且存在苹果不会修复的已知布局bug。请查看 `skills/textkit-ref.md` 。
"我把cancellables存在局部变量里就行"	局部AnyCancellable会立即释放，导致订阅终止。

Example Invocations

调用示例

User: "How do I wrap a UIKit view in SwiftUI?" → Read:

skills/uikit-bridging.md

User: "I'm getting 'Unable to simultaneously satisfy constraints'" → Read:

skills/auto-layout-debugging.md

User: "My CAAnimation completion handler never fires" → Read:

skills/uikit-animation-debugging.md

User: "Should I use Combine or async/await for this?" → Read:

skills/combine-patterns.md

User: "How do I integrate Writing Tools with my text editor?" → Read:

skills/textkit-ref.md

User: "My SwiftUI view has a memory leak from a Combine subscription" → Read:

skills/combine-patterns.md

User: "How do I embed SwiftUI in my UIKit app?" → Read:

skills/uikit-bridging.md

用户："如何在SwiftUI中封装UIKit视图？" → 参考：

skills/uikit-bridging.md

用户："我遇到了'无法同时满足约束条件'的错误" → 参考：

skills/auto-layout-debugging.md

用户："我的CAAnimation完成处理程序从未触发" → 参考：

skills/uikit-animation-debugging.md

用户："我应该用Combine还是async/await来做这个？" → 参考：

skills/combine-patterns.md

用户："如何将写作工具集成到我的文本编辑器中？" → 参考：

skills/textkit-ref.md

用户："我的SwiftUI视图因Combine订阅导致内存泄漏" → 参考：

skills/combine-patterns.md

用户："如何在我的UIKit应用中嵌入SwiftUI？" → 参考：

skills/uikit-bridging.md