PDFKit 技能用于在 Apple 平台应用中显示和操作 PDF 文档，围绕 PDFView、PDFDocument、PDFPage、PDFAnnotation、PDFSelection 等核心类型展开。
用途 适用于需要嵌入 PDF 阅读器、创建或修改 PDFDocument 实例、添加标注、处理表单、生成缩略图、搜索文本以及进行页面叠加等场景。
主要能力
- 文档加载：安全加载 PDF，处理密码保护（isLocked / unlock(withPassword:)）与无效数据。
- 显示与导航：配置 PDFView 的显示模式、缩放、导航，并观察页面变化通知（PDFViewPageChanged）。
- 搜索与选择：使用 PDFSelection 进行文本搜索与选择，大文档搜索采用异步 beginFindString 配合 delegate。
- 标注与表单：添加、修改标注，处理表单、水印、合并与打印等操作。
- 缩略图：通过 PDFThumbnailView 与主 PDFView 联动展示页面缩略图。
- SwiftUI 集成：通过 UIViewRepresentable 包装 PDFView，保持身份稳定。
- 页面叠加：使用 PDFPageOverlayViewProvider 实现自定义绘制与叠加生命周期管理。
使用方式 工作流建议：先安全加载文档并明确变更与保存的归属；再根据实际产品界面配置 PDFView 的显示、缩放、导航与观察；随后执行搜索、选择、标注、表单、缩略图或页面操作，并注意 PDF 坐标转换；保持 SwiftUI representable 身份稳定，强引用弱 delegate/provider；最后保存到明确目标并验证重新加载、旋转、大文件、受保护文件与标注持久化。
关键决策与常见错误
- PDFDocument(url:) 与 PDFDocument(data:) 是可失败初始化器，必须使用可选绑定而非强制解包。
- 设置 pdfView.autoScales = true，否则 PDF 按原生分辨率渲染。
- PDF 页面坐标原点在左下角、Y 轴向上，与 UIKit 相反，放置或命中测试标注前需转换坐标。
- PDFKit 类非线程安全，所有变更必须在 @MainActor 上执行。
- 在 UIViewRepresentable 的 updateUIView 中比较 PDFDocument 应使用身份比较（!==），避免更新循环。
- 访问页面前检查索引是否超出 pageCount。
- 需要加密时使用 write(to:withOptions:) 保存文档。
适用场景 iOS/macOS 应用中的 PDF 阅读器、标注工具、表单处理、文档生成与打印、缩略图导航、自定义页面叠加等。
限制 资料未提供具体收费、价格、平台版本要求或效果数据；PDFKit 类非线程安全，所有变更需在主线程执行；坐标系统与 UIKit 不同，需手动转换。