macOS分栏控制器NSSplitViewController

NSSplitViewController 是 macOS AppKit 框架中用于构建可调节的分栏界面（Split View UI） 的控制器类，是 UIViewController 在 iOS 中的 macOS 对应实现之一。

基本信息

NSSplitViewController继承自NSViewController，适用于macOS 10.10+。

通常配合NSSplitView, NSSplitViewItem, 各子控制器使用。

初始化代码：

let splitVC = NSSplitViewController()

基本结构

NSSplitViewController控制器会自动创建NSSplitView。

每个子视图控制器都会被包装成NSSplitViewItem，显示NSViewController自定义的控制器。

基本用法

let splitVC = NSSplitViewController()

let sidebarVC = NSViewController()
sidebarVC.view = NSView(frame: .init(x: 0, y: 0, width: 200, height: 600))
sidebarVC.view.wantsLayer = true
sidebarVC.view.layer?.backgroundColor = NSColor.gray.cgColor

let contentVC = NSViewController()
contentVC.view = NSView(frame: .init(x: 0, y: 0, width: 400, height: 600))
contentVC.view.wantsLayer = true
contentVC.view.layer?.backgroundColor = NSColor.white.cgColor

let sidebarItem = NSSplitViewItem(viewController: sidebarVC)
let contentItem = NSSplitViewItem(viewController: contentVC)

splitVC.addSplitViewItem(sidebarItem)
splitVC.addSplitViewItem(contentItem)

基本用途

NSSplitViewController 是 macOS 桌面应用中最常用于实现如下 UI：

1、Finder（左侧导航栏 + 文件列表）

2、Xcode（文件导航 + 编辑器 + 右侧属性栏）

3、邮箱（邮件列表 + 内容）

4、图像处理软件（工具栏 + 画布）

它可以垂直或水平分隔多个视图，支持用户拖拽调整。

常用属性

每一个子控制器都由一个 NSSplitViewItem 包装，提供以下配置：

1、isCollapsed：是否折叠（隐藏）此栏。

2、canCollapse：是否允许用户折叠。

注意：如果不希望在缩小窗口尺寸时，NSSplitViewItem 被折叠，canCollapse 必须设置为 false。

3、minimumThickness / maximumThickness：最小/最大宽度限制。

4、holdingPriority：控制栏的“抗压性”，决定当空间不足时哪个栏先被缩小。

5、preferredThicknessFraction：初始宽度占比（0.0 ~ 1.0）。

6、behavior：枚举类型，控制交互行为，如 .sidebar, .contentList, .default。

常用方法

1、addSplitViewItem(_:)：添加分栏。

2、removeSplitViewItem(_:)：移除栏。

3、splitViewItems：当前所有栏的数组。

4、splitView：底层 NSSplitView。

使用场景

1、样式与方向控制

默认是垂直（即左右分栏），如需改为上下布局：

splitVC.splitView.isVertical = false // 上下排列

注意：splitView 不是直接创建的，需要在 viewDidLoad 或设置完视图后访问。

2、2栏带拖拽分割线

class MainSplitViewController: NSSplitViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let leftVC = SidebarViewController()
        let rightVC = ContentViewController()

        let leftItem = NSSplitViewItem(viewController: leftVC)
        leftItem.minimumThickness = 150
        leftItem.canCollapse = true
        leftItem.holdingPriority = .defaultLow

        let rightItem = NSSplitViewItem(viewController: rightVC)

        addSplitViewItem(leftItem)
        addSplitViewItem(rightItem)
    }
}

和SwiftUI的NavigationSplitView相比

1、可用平台：NSSplitViewController仅用于macOS，NavigationSplitView适用于macOS + iOS。

2、控制灵活性：NSSplitViewController可以自定义参数和配置，NavigationSplitView封装简单。

3、控件类型：NSSplitViewController适用于NSViewController，NavigationSplitView适用于SwiftUI View。

在SwiftUI中使用NSSplitViewController

在AppDelegate中创建窗口，这部分详细内容可参考《macOS限制窗口尺寸的实际案例》。

class AppDelegate: NSObject, NSApplicationDelegate {
    var statusBarController: StatusBarController?
    
    func applicationDidFinishLaunching(_ notification: Notification) {
        statusBarController = StatusBarController()
        
        let contentVC = NSHostingController(rootView: ContentView())
        let workspaceVC = NSHostingController(rootView: WorkspaceView())
        
        // 创建 NSSplitViewController 并添加子项
        let splitVC = NSSplitViewController()
        splitVC.addSplitViewItem(NSSplitViewItem(sidebarWithViewController: contentVC))
        splitVC.addSplitViewItem(NSSplitViewItem(viewController: workspaceVC))
        
        let window = NSWindow(
            contentRect: NSRect(x: 0, y: 0, width: 900, height: 550),
            styleMask: [.titled, .closable, .miniaturizable, .resizable], // 可以调大小
            backing: .buffered,
            defer: false)
        
        window.center()
        window.isReleasedWhenClosed = false
        window.contentViewController = splitVC
        window.makeKeyAndOrderFront(nil)
        
        WindowManager.shared.mainWindow = window
        print("window完成初始化")
    }
    
    func applicationShouldHandleReopen(_ sender: NSApplication, hasVisibleWindows flag: Bool) -> Bool {
        print("点击Dock栏，显示window")
        if !flag {
            WindowManager.shared.mainWindow?.makeKeyAndOrderFront(nil)
        }
        return true
    }
}

使用NSHostingController桥接ContentView和WorkspaceView两个视图。

创建NSSplitViewController并添加到分栏视图中。

NSWindow窗口的contentViewController配置为NSSplitViewController。

这样就可以实现在SwiftUI视图显示分栏视图。

总结

如果开发macOS App（SwiftUI + AppKit混用），可以通过 NSViewRepresentable 封装 NSSplitView。不过 SwiftUI 现在的 NavigationSplitView 基本已满足主流需求。

NSViewRepresentable分割线如果无法置顶，则需要配置Window的styleMask属性：

window.styleMask.insert(.fullSizeContentView)

相关文章

1、macOS子视图区域NSSplitView：https://fangjunyu.com/2025/07/03/macos%e5%ad%90%e8%a7%86%e5%9b%be%e5%8c%ba%e5%9f%9fnssplitview/

2、SwiftUI多栏导航界面NavigationSplitView：https://fangjunyu.com/2024/12/21/swiftui%e5%a4%9a%e6%a0%8f%e5%af%bc%e8%88%aa%e7%95%8c%e9%9d%a2navigationsplitview/

3、macOS限制窗口尺寸的实际案例：https://fangjunyu.com/2025/07/07/macos%e9%99%90%e5%88%b6%e7%aa%97%e5%8f%a3%e5%b0%ba%e5%af%b8%e7%9a%84%e5%ae%9e%e9%99%85%e6%a1%88%e4%be%8b/