用途:当 SwiftUI 接近但不足以实现原生 macOS 行为时,指导选择最小、最明确的 AppKit 桥接方式。SwiftUI 通常保持为数据源,AppKit 只处理命令式边界。
主要能力:帮助区分能力缺口,如窗口行为、文本系统行为、菜单校验、拖放、文件打开/保存面板、第一响应者控制;并给出桥接选型建议:纯 SwiftUI 已能满足时不用桥接;需要特定 AppKit 视图且生命周期轻量时用 NSViewRepresentable;需要控制器生命周期、委托或呈现协调时用 NSViewControllerRepresentable;需要 NSWindow、响应者链、菜单校验、面板或应用级行为时用直接 AppKit 窗口或应用钩子。
使用方式:先精确命名能力缺口,再选最小边界,避免把整屏移植到 AppKit。保持所有权明确:SwiftUI 拥有值状态、选择与可观察模型;AppKit 对象留在 representable、coordinator 或桥接对象内;向 SwiftUI 暴露窄接口,如可编辑状态的绑定、事件的小回调,必要时才提供聚焦的桥接服务。验证生命周期假设,注意 SwiftUI 可能重建 representable,Coordinator 只用于持有委托与 target-action 胶水,不应成为第二套应用架构。
参考文件:references/representables.md 讨论视图与视图控制器包装的选择及 coordinator 模式;references/window-panels.md 涉及窗口访问、工具窗口与打开/保存面板;references/responder-menus.md 涉及第一响应者、命令路由与菜单校验;references/drag-drop-pasteboard.md 涉及剪贴板、文件 URL 与桌面拖放边界。
限制与护栏:不要在 SwiftUI 与 AppKit 之间重复数据源;不要让 Coordinator 变成无结构堆放处;不要无强所有权理由全局存储长期存活的 NSView 或 NSWindow;优先使用小而可测试的桥接,而非用原始 AppKit 重写功能;若模式可完全留在 swiftui-patterns 中,就保留在那里。输出应包含:跨越的确切 SwiftUI 限制、推荐的最小桥接类型、SwiftUI 与 AppKit 之间的数据流边界、需关注的生命周期或验证风险。