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：是否允许用户折叠。

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。

总结

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

相关文章

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/