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/