macOS SwiftUI 文档应用纯SwiftUI方式实例化非文档独立窗口

完全不需要借助NSWindow、NSHostingView这类AppKit桥接代码，原生SwiftUI API就支持在基于文档的应用里共存独立的自包含工具窗口。你之前添加WindowGroup后无法正常显示的问题，本质是踩了SwiftUI多场景配置的默认规则坑。

WindowGroup和DocumentGroup共存失效的根因 #

SwiftUI从macOS 13、iOS 16开始的多场景注册逻辑存在一个很容易忽略的规则：

• 没有传入自定义id参数的WindowGroup，会被系统自动识别为应用的默认主窗口场景
• 当应用中已经存在DocumentGroup作为文档主窗口时，两个被标记为“主窗口”的场景会产生优先级冲突，系统会优先渲染已注册的文档场景，直接把无id的WindowGroup入口屏蔽，这就是你必须注释掉DocumentGroup才能看到WindowGroup的核心原因。

正确的实现方式 #

1. 声明带唯一标识的独立工具窗口场景 #

在App的Scene构建代码中，把独立工具窗口的WindowGroup和原有DocumentGroup并列放置，必须给WindowGroup传入全局唯一的字符串id，从根源上避免场景优先级冲突：

@main struct MyApp: App
{
    var addTerrainGeneratorLayerCommand = NotificationCenter.default.publisher(for: .addTerrainLayer)
    
    var body: some Scene {
        // 原有文档场景保持完全不变
        DocumentGroup(newDocument: ProjectDocument.init) { inGroup in
            ProjectWindowContentView(document: inGroup.document)
                .frame(minWidth: 301.0, minHeight: 100.0)
                .onReceive(self.addTerrainGeneratorLayerCommand) { _ in
                    inGroup.document.addTerrainGeneratorLayer()
                }
        }
        .commands {
            // 原有菜单配置保持不变，在此处新增打开工具窗口的菜单按钮
            CommandGroup(after: .newItem) {
                Button("打开地形生成器工具") {
                    // 窗口触发逻辑见下方说明
                }
            }
        }
        
        // 新增独立工具窗口场景，关键：必须传入唯一id
        WindowGroup(id: "terrain-generator-tool") {
            TerrainGeneratorUtilityView()
                .frame(minWidth: 300, minHeight: 400)
        }
    }
}

2. 触发工具窗口打开的原生方式 #

macOS 13及以上可以直接用SwiftUI提供openWindow环境方法触发窗口打开，完全不需要写URL scheme或者AppKit调用：

struct OpenToolMenuButton: View {
    // 直接通过环境拿到窗口打开能力
    @Environment(\.openWindow) private var openWindow
    
    var body: some View {
        Button("打开地形生成器工具") {
            // 传入之前给WindowGroup定义的对应id即可唤起窗口
            openWindow(id: "terrain-generator-tool")
        }
    }
}

关键注意事项 #

• 给WindowGroup配置的id必须全局唯一，不能和应用内其他场景、其他应用的场景重复，否则依然会出现路由错乱、窗口唤起失败的问题
• 这种方式创建的工具窗口完全匹配SwiftUI的场景生命周期，系统会自动处理窗口的状态恢复、菜单栏联动、窗口列表归类，和系统原生检查器、偏好设置窗口的行为完全一致
• 不需要手动管理窗口的关闭、内存释放、焦点跳转逻辑，比自己写NSWindow+NSHostingView的桥接方案稳定得多

容易踩坑的反例写法：

// 没有带id的WindowGroup，会和DocumentGroup产生主窗口优先级冲突，被系统屏蔽
WindowGroup {
    TerrainGeneratorUtilityView()
}

只要给这个WindowGroup加上唯一id，和DocumentGroup并列声明，两个场景就可以正常共存：文档操作时走DocumentGroup的窗口逻辑，点菜单打开的就是独立的工具窗口。

常见认知误区说明 #

网上大量提到需要创建NSWindow、套NSHostingView的方案，本质是SwiftUI早期（macOS 12及更早版本）多场景API不完善时的兼容方案，现在已经完全可以被原生带id的WindowGroup替代，不存在所谓“SwiftUI设计疏漏”的问题——只是很多教程没有提WindowGroup必须加id才能和DocumentGroup共存的规则。

内容的提问来源于stack exchange，提问作者Rick