如何在SwiftUI Mac应用的帮助菜单中打开并展示内置用户指南？

1. 自定义帮助菜单项 #

通过SwiftUI的Commands API 替换系统默认帮助菜单，添加你需要的文档入口：

@main
struct YourApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .commands {
            CommandGroup(replacing: .help) {
                Button("用户指南") {
                    HelpWindowManager.shared.open(fileName: "user-guide")
                }
                Button("技术指南") {
                    HelpWindowManager.shared.open(fileName: "tech-guide")
                }
                // 按需添加更多文档入口
            }
        }
    }
}

注意：请提前确认所有.md文件已经加入Xcode项目的应用Target成员中，否则Bundle.main无法读取到对应文件。

2. 实现帮助窗口管理单例 #

用单例统一管理帮助窗口的生命周期，避免同一份文档重复打开多个窗口：

class HelpWindowManager: NSObject {
    static let shared = HelpWindowManager()
    private var activeWindows: [String: NSWindow] = [:]
    
    func open(fileName: String) {
        // 已打开的窗口直接唤起，不重复创建
        if let window = activeWindows[fileName] {
            window.makeKeyAndOrderFront(nil)
            return
        }
        // 读取包内md文件内容
        guard let fileUrl = Bundle.main.url(forResource: fileName, withExtension: "md"),
              let mdContent = try? String(contentsOf: fileUrl, encoding: .utf8) else {
            return
        }
        // 创建新窗口
        let window = NSWindow(
            contentRect: NSRect(x: 0, y: 0, width: 850, height: 650),
            styleMask: [.titled, .closable, .resizable, .miniaturizable],
            backing: .buffered, defer: false
        )
        window.center()
        window.title = fileName.replacingOccurrences(of: "-", with: " ").localizedCapitalized
        window.contentView = NSHostingView(rootView: MarkdownRenderView(content: mdContent))
        window.delegate = self
        window.makeKeyAndOrderFront(nil)
        activeWindows[fileName] = window
    }
}

extension HelpWindowManager: NSWindowDelegate {
    func windowWillClose(_ notification: Notification) {
        guard let closedWindow = notification.object as? NSWindow else { return }
        activeWindows = activeWindows.filter { $0.value !== closedWindow }
    }
}

3. 实现Markdown渲染视图 #

如果你的应用最低支持macOS 12+，可以直接用SwiftUI原生的Markdown渲染能力，无需引入第三方依赖：

struct MarkdownRenderView: View {
    let content: String
    
    var body: some View {
        ScrollView(.vertical, showsIndicators: true) {
            Text(.init(content))
                .padding(.vertical, 24)
                .padding(.horizontal, 32)
                .frame(maxWidth: .infinity, alignment: .leading)
        }
        .frame(minWidth: 700, minHeight: 500)
    }
}

如果你需要支持表格、代码块高亮等复杂Markdown语法，可以自行实现富文本转换逻辑，或是引入轻量的原生Markdown解析库，所有逻辑都可以完全内置，无需依赖网络。

可选优化项 #

• 增加全局搜索功能，遍历所有内置md文件匹配关键词，快速定位内容
• 实现锚点跳转逻辑，支持点击目录自动滚动到对应章节
• 存储用户阅读进度，下次打开同一份文档时自动定位到上次阅读位置

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