PDFKit是苹果生态中处理PDF文档的官方框架，从iOS到macOS都有完整的API支持。在macOS上开发一款PDF阅读器时，读者最常用的三个功能就是文本高亮、下划线笔记和通过目录快速跳转章节。这三个功能看似独立，实际上都围绕PDFDocument的数据层和PDFView的展示层展开。本文将以一个实际阅读器项目为线索，逐步讲解如何搭建文档加载流程、实现标注工具栏、处理文本选区与注释的映射关系，最后解析PDFOutline目录树并接入侧边栏导航，帮助你把这些能力完整地集成到自己的App中。
一、搭建基础阅读环境：PDFView的配置与文档加载
在动手实现标注功能之前，先把文档展示的基础流程跑通。PDFKit的核心思路是数据与视图分离：PDFDocument负责承载PDF的页面数据、注释数据和目录结构，而PDFView则负责渲染、缩放、翻页和文本选择交互。开发者在Interface Builder中拖入一个PDFView，或者在代码中直接初始化都可以。
下面的代码演示了如何在App启动时加载一份PDF文档，并做一些实用的初始配置。其中autoScales属性会让页面自动适配窗口宽度，displaysPageBreaks控制分页线显示，而displaysAsBook适合双页阅读模式。
import PDFKit
import Cocoa
class ReaderViewController: NSViewController {
@IBOutlet weak var pdfView: PDFView!
override func viewDidLoad() {
super.viewDidLoad()
guard let path = Bundle.main.path(forResource: "sample", ofType: "pdf"),
let document = PDFDocument(url: URL(fileURLWithPath: path)) else {
print("文档加载失败")
return
}
pdfView.document = document
pdfView.autoScales = true // 自动适配窗口大小
pdfView.displaysPageBreaks = true // 显示页面分隔线
pdfView.backgroundColor = NSColor(white: 0.18, alpha: 1)
pdfView.displaysRTL = false // 从左到右阅读
}
}
需要特别注意的是，PDFDocument的初始化可能因为文件损坏、加密或权限问题而返回nil。对于带密码的PDF，可以尝试调用unlock(withPassword:)方法，并根据返回值判断解锁是否成功。在实际项目中建议把加载逻辑封装成独立方法，加上沙盒安全作用域访问（如果文档来自用户的文件选择器，NSOpenPanel返回的URL本身就带了访问权限，通常不需要额外处理）。
加载成功后，你还可以监听PDFViewPageChanged通知来跟踪当前阅读位置，为后续实现"记住上次阅读页"的功能打基础。这个通知在用户翻页时触发，配合pdfView.currentPage和PDFDestination可以把阅读进度保存到UserDefaults中。
二、实现高亮与下划线标注：从文本选区到PDFAnnotation
1. 理解选区与注释的关系
高亮和下划线标注的本质是：从用户选中的文本区域提取PDFSelection对象，再把它转换成若干个PDFAnnotation添加到对应页面上。PDFKit提供了addAnnotation系列API专门处理这件事，其中addHighlight和addUnderline是最常用的两个便捷方法，它们内部会自动计算选区覆盖的矩形区域。
2. 代码实现标注工具栏
下面的代码展示了如何监听选区变化，并根据当前工具模式添加不同类型的注释。这里用工具栏按钮切换模式，currentTool枚举区分高亮、下划线和无操作三种状态。
enum AnnotateTool {
case none, highlight, underline
}
class ReaderViewController: NSViewController {
var currentTool: AnnotateTool = .none
// 在viewDidLoad中注册选区变化通知
func setupObservers() {
NotificationCenter.default.addObserver(
self,
selector: #selector(selectionChanged),
name: .PDFViewSelectionChanged,
object: pdfView
)
}
@objc func selectionChanged() {
guard let selection = pdfView.currentSelection,
let tool = currentToolAsEnum() else { return }
switch tool {
case .highlight:
pdfView.addHighlight(for: selection,
options: [.color : NSColor.systemYellow])
case .underline:
pdfView.addUnderline(for: selection,
options: [.color : NSColor.systemRed])
case .none:
break
}
pdfView.clearSelection() // 标注完成后清除选区，避免重复添加
}
}
选区变化通知触发非常频繁，用户拖动选择文本时每一步都会触发。如果直接在通知回调里加注释，会出现同一段文字被叠加多次标注的问题。解决办法是加一个防抖逻辑，或者只在用户松开鼠标后处理（例如监听鼠标up事件，或者在回调里用perform(#selector, with: nil, afterDelay: 0.3)做延迟合并，并在再次触发时cancelPreviousPerformRequests）。这是PDFKit开发中最常见的坑之一。
3. 手动构建注释对象
除了便捷方法，你也可以手动创建PDFAnnotation来获得更细的控制。比如需要给高亮设置透明度、添加备注内容（用户点击注释时弹出便签），就必须走手动创建的路线。
func addCustomHighlight(to selection: PDFSelection, in page: PDFPage) {
// 获取选区在页面上的矩形区域，可能跨越多行
let bounds = selection.bounds(for: page)
let highlight = PDFAnnotation(
bounds: bounds,
forType: .highlight,
withProperties: nil
)
highlight.color = NSColor.systemYellow.withAlphaComponent(0.35)
highlight.contents = "这里重点看一下，第三段论证有问题"
page.addAnnotation(highlight)
pdfView.needsDisplay = true // 手动添加后强制刷新视图
}
手动添加注释后视图不刷新也是高频问题。便捷方法内部会自动触发重绘，但手动调用page.addAnnotation后，某些情况下需要手动设置pdfView.needsDisplay = true，或者调用pdfView.layoutDocumentView()来强制刷新。
4. 注释的持久化保存
添加的注释默认只存在于内存中的document对象里。如果用户通过打开面板选择的是原始文件URL，直接调用document.write(to:)会因为沙盒权限不足而失败。正确做法有两条：一是用NSDocument架构管理文档，让系统自动处理保存；二是把注释导出为独立的JSON文件，与原PDF分离存储，阅读时再动态加载回页面。第二种方案的好处是不会污染原始文件，且天然支持多设备同步。
// 方案二示例：导出注释数据
func exportAnnotations() throws -> Data {
guard let document = pdfView.document else { return Data() }
var notes: [[String: Any]] = []
for pageIndex in 0..<document.pageCount {
guard let page = document.page(at: pageIndex) else { continue }
for annotation in page.annotations where annotation.type == .highlight {
let note: [String: Any] = [
"page": pageIndex,
"text": annotation.stringValue ?? "",
"rect": NSStringFromRect(annotation.bounds),
"color": annotation.color.hexString
]
notes.append(note)
}
}
return try JSONSerialization.data(withJSONObject: notes)
}
三、解析目录大纲并实现侧边栏跳转
1. PDFOutline的树形结构
PDF的目录在PDFKit中用PDFOutline表示，它是一个典型的树形结构：根节点通过document.outlineRoot获取，每个节点的numberOfChildren和child(at:)用于遍历子节点，label是章节标题，destination则记录了跳转目标（包含目标页面和位置坐标）。需要注意的是，有些PDF没有内嵌目录，此时outlineRoot为nil，你的应用需要提供优雅的降级方案，比如显示纯页面缩略图列表。
2. 构建目录数据源并接入NSOutlineView
macOS上展示树形结构最合适的控件是NSOutlineView，它和PDFOutline的层级模型天然契合。下面的代码把大纲节点包装成模型对象并实现数据源代理。
class OutlineNode {
let outline: PDFOutline
var children: [OutlineNode] = []
var isExpanded = false
init(_ outline: PDFOutline) {
self.outline = outline
var nodes: [OutlineNode] = []
for i in 0..<outline.numberOfChildren {
if let child = outline.child(at: i) {
nodes.append(OutlineNode(child))
}
}
children = nodes
}
}
class SidebarViewController: NSViewController, NSOutlineViewDataSource, NSOutlineViewDelegate {
@IBOutlet weak var outlineView: NSOutlineView!
var rootNode: OutlineNode?
func loadOutline(from document: PDFDocument) {
guard let root = document.outlineRoot else { return }
rootNode = OutlineNode(root)
outlineView.reloadData()
outlineView.expandItem(outlineView.item(atRow: 0))
}
// 点击行时执行跳转
func outlineViewSelectionDidChange(_ notification: Notification) {
guard let node = outlineView.item(atRow: outlineView.selectedRow) as? OutlineNode,
let destination = node.outline.destination,
let page = destination.page else { return }
pdfView.go(to: PDFDestination(page: page,
at: destination.point))
// 记录当前章节，便于"回到目录"功能
}
}
跳转的核心是pdfView.go(to:)方法，它接收一个PDFDestination对象，支持带动画滚动到指定页面的指定坐标点。如果只需要跳到某页顶部，也可以直接用pdfView.go(toPage:)。跳转后记得同步侧边栏的选中行与实际页面的对应关系，否则用户翻页后侧边栏高亮不会跟着移动，体验会大打折扣。可以通过PDFViewPageChanged通知反查当前页属于哪个章节，再调用outlineView.selectRow同步选中状态。
3. 处理无目录PDF的补救方案
对于没有内嵌大纲的文档，可以考虑基于页面字体大小分析自动提取标题生成目录，也可以提供手动添加书签的功能。手动书签的实现很简单：记录当前pdfView.currentPage的索引和滚动位置，存入数组并在侧边栏展示。这本质上是自己维护一套轻量的"个人大纲"，实现成本远低于全文分析算法，实际产品中往往更受用户欢迎。
四、常见问题与排查思路
选区获取不到：确认PDF是文本型而非扫描图片。图片型PDF的currentSelection永远为nil，需要先接入OCR方案。可以用page.string是否为空来快速判断文档是否包含可提取文本。
保存后注释丢失：重点检查沙盒权限。如果文档URL来自NSOpenPanel，用户选择时会授予持久访问权限，但document.write(to:)写入新路径时仍需确认目标位置可写。另外，写入前建议先复制一份文件再操作，避免写坏原文件。
目录跳转位置不准：部分PDF的大纲destination只有页码没有坐标，此时destination.point可能是.zero，跳转后会落在页面左上角而不是章节标题处。这种情况只能接受页级跳转，或者结合标题文本用page.selection(for:)搜索定位具体位置。
掌握以上三块内容后，一个具备完整笔记能力的PDF阅读器骨架就成型了。后续还可以继续扩展方形框选、删除线、自由画笔等注释类型，PDFKit的PDFAnnotation支持十几种子类型，扩展方式和本文讲的高亮下划线完全一致，照着同样的模式添加即可。
macOS PDFKitPDF高亮注释PDFView目录跳转修改时间：2026-09-14 22:31:09