在 SwiftUI 与 UIKit…

当需要在 SwiftUI 中包装 UIKit 视图/控制器、在 UIKit 中嵌入 SwiftUI，或让两端共享 @Observable 状态时使用。

适用场景

解决思路

1. 用 UIViewRepresentable 包装任意 UIView 子类：在 makeUIView(context:) 中一次性创建并配置 UIKit 视图（如设置 delegate、字体），在 updateUIView(_:context:) 中把 SwiftUI 状态同步进 UIKit 视图。
2. 理解生命周期时机：makeCoordinator() 在 makeUIView 之前调用且每个 representable 生命周期只调用一次；makeUIView 在进入视图树时调用一次；updateUIView 在 makeUIView 之后立即调用，并在任何相关状态变化时调用；dismantleUIView 在从视图树移除时调用；sizeThatFits 在布局时调用（iOS 16+）。
3. 在 dismantleUIView(_:coordinator:) 中清理观察者、定时器和订阅，例如 coordinator.cancellables.removeAll()。
4. 在 iOS 16+ 实现 sizeThatFits(_:uiView:context:) 返回自定义尺寸：返回 nil 回退到 UIKit 的 intrinsicContentSize，返回 CGSize 覆盖 SwiftUI 的尺寸计算；可用 proposal.width ?? UIView.layoutFittingExpandedSize.width 计算宽度。
5. 用 UIViewControllerRepresentable 包装 UIViewController 子类（如系统选择器、文档扫描、邮件撰写等模态控制器）：在 makeUIViewController 中创建并设置 delegate，updateUIViewController 对模态控制器通常留空。
6. 在 coordinator 中捕获 delegate 回调并把结果通过父级的 @Binding 或闭包回传 SwiftUI，例如在 didFinishWith 中把扫描结果写入 parent.scannedImages 并调用 parent.dismiss()。
7. 使用 Coordinator 模式：因为 SwiftUI representable 是值类型不能充当 delegate，需用 class 类型的 Coordinator，并把它嵌套在 representable 内或扩展中，存储 parent 引用以便写回 @Binding。
8. 在 makeUIView/makeUIViewController 中设置 delegate，绝不在 updateUIView/updateUIViewController 中设置，避免重复赋值和意外副作用。
9. 在 updateUIView 或 updateUIViewController 开头执行 context.coordinator.parent = self，刷新 coordinator 中复制的 parent 状态（闭包和非绑定值会被复制）。
10. 在闭包中使用 [weak coordinator] 避免 coordinator 与捕获它的 UIKit 对象之间产生循环引用。
11. 用 UIHostingController 在 UIKit 中嵌入 SwiftUI：必须按三步顺序执行 addChild(hostingController)、添加并约束 hostingController.view、didMove(toParent: self)，缺任一步会导致 containment 回调错乱、外观转场和 trait 传播失效。
12. iOS 16+ 用 hostingController.sizingOptions = [.intrinsicContentSize] 让宿主视图把 SwiftUI 内容尺寸报告为 intrinsicContentSize；用 .preferredContentSize 让 preferredContentSize 匹配 SwiftUI 内容（用于 popover 或 form sheet）。
13. 数据变化时通过 hostingController.rootView = ProfileView(profile: profile) 推送新状态；若传入 @Observable 对象则 SwiftUI 自动跟踪变化，无需重新赋值 rootView。
14. iOS 16+ 用 UIHostingConfiguration 在 UICollectionViewCell 或 UITableViewCell 中直接渲染 SwiftUI 内容，无需手动管理子 hosting controller，例如 cell.contentConfiguration = UIHostingConfiguration { ItemRow(item: items[indexPath.item]) }。
15. 尺寸桥接：被包装的 UIKit 视图通过 intrinsicContentSize 向 SwiftUI 传达自然尺寸，SwiftUI 在布局时尊重它，除非被 frame() 或 fixedSize() 覆盖。
16. 不要直接设置被包装视图的 center、bounds、frame、transform，这些由 SwiftUI 拥有；应使用 sizeThatFits、intrinsic content size、SwiftUI 布局修饰符或自定义 UIKit 子视图内部布局。
17. 理解 fixedSize() 与 frame() 的交互：无修饰符时 SwiftUI 用 intrinsicContentSize 作为理想尺寸且视图可伸缩；.fixedSize() 在两个轴向上强制理想尺寸；.fixedSize(horizontal: true, vertical: false) 固定宽度、高度可伸缩；.frame(width:height:) 覆盖建议尺寸。
18. 用 @Binding 实现双向同步：updateUIView 中读绑定推入 UIKit（如 if uiView.text != text { uiView.text = text }），coordinator 的 delegate 回调中写回 parent.text。
19. 对一次性事件（按钮点击、搜索提交、扫描完成）用闭包而非绑定，例如 var onNavigationFinished: ((URL) -> Void)?。
20. 在 representable 方法中通过 context.environment 读取 SwiftUI 环境值，例如 context.environment.isEnabled 控制 uiView.isEditable，context.environment.colorScheme 响应深浅色。
21. 防止更新循环：在 updateUIView 中用 if uiView.text != text 之类的守卫，只在值真正不同时才更新，避免设置 uiView.text 触发 delegate 写回 parent.text 再次触发 updateUIView。
22. UIKit 与 SwiftUI 共享 @Observable 模型时使用 UIKit 自动观察跟踪：iOS 26+ 用 updateProperties() 更新标签、颜色、可见性、启用状态等非布局 UI，用布局钩子处理几何，用 cell 配置更新处理器处理 cell；iOS 18 需在 Info.plist 中设置 UIObservationTrackingEnabled；iOS 17 只有 @Observable 而无 UIKit 自动跟踪，withObservationTracking 是一次性的，不要构建轮询循环；iOS 15-16 或已有 ObservableObject 用 Combine objectWillChange、delegate、通知或显式回调。
23. 在 Swift 6 严格并发下把 coordinator 标记为 @MainActor（如 @MainActor final class Coordinator: NSObject, UISearchBarDelegate），因为 UIKit delegate 协议不是 Sendable，标记后 delegate 方法在主 actor 上可安全访问 UIKit 和 @Binding；跨隔离边界传闭包时确保是 @Sendable 或在正确 actor 上捕获。
24. 避免常见错误：不要在 update* 中重建 UIKit 对象或 delegate；不要直接改被包装视图的 frame/bounds/transform；不要被 UIKit 闭包强引用 coordinator；确保 picker/控制器的所有退出路径都走统一的 coordinator 清理路径；观察者/定时器/订阅要在 dismantle* 中移除；hosting controller 不要用手动 frame 而不做 containment；不要在 coordinator 中使用 @State，改用存储属性并通过绑定/回调通信；不要手动轮询 withObservationTracking。

适用边界 · 注意事项

• 需要支持 iOS 17 及更早版本时，不能依赖 UIKit 自动观察跟踪，只能用 Combine objectWillChange、delegate、通知或显式回调。
• 当 SwiftUI 已能原生实现所需 UI 时，不必为了包装而包装 UIKit 视图，避免引入不必要的桥接复杂度。
• 不要在被包装视图上直接设置 frame、bounds、center、transform，这些几何属性由 SwiftUI 拥有。