JordanCoin/ios-skills-collection

PDFKit

使用 PDFView、PDFDocument、PDFPage、PDFAnnotation 和 PDFSelection 显示、导航、搜索、标注和操作 PDF 文档。目标平台：Swift 6.3 / iOS 26+。

目录

• 设置
• 显示 PDF
• 加载文档
• 页面导航
• 文本搜索和选择
• 标注
• 缩略图
• SwiftUI 集成
• 常见错误
• 审查清单
• 参考

设置

PDFKit 无需任何授权或 Info.plist 条目。

import PDFKit

平台可用性： iOS 11+、iPadOS 11+、Mac Catalyst 13.1+、macOS 10.4+、tvOS 11+、visionOS 1.0+。

显示 PDF

PDFView 是 UIView 的子类，它渲染 PDF 内容，并内置处理缩放、滚动、文本选择和页面导航。

import PDFKit
import UIKit

class PDFViewController: UIViewController {
    let pdfView = PDFView()

    override func viewDidLoad() {
        super.viewDidLoad()
        pdfView.frame = view.bounds
        pdfView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(pdfView)

        pdfView.autoScales = true
        pdfView.displayMode = .singlePageContinuous
        pdfView.displayDirection = .vertical

        if let url = Bundle.main.url(forResource: "sample", withExtension: "pdf") {
            pdfView.document = PDFDocument(url: url)
        }
    }
}

显示模式

模式	行为
.singlePage	一次显示一页
.singlePageContinuous	页面垂直堆叠，可滚动
.twoUp	两页并排显示
.twoUpContinuous	双页模式并连续滚动

缩放与外观

pdfView.autoScales = true
pdfView.minScaleFactor = pdfView.scaleFactorForSizeToFit
pdfView.maxScaleFactor = 4.0

pdfView.displaysPageBreaks = true
pdfView.pageShadowsEnabled = true
pdfView.interpolationQuality = .high

加载文档

PDFDocument 可以从 URL、Data 加载，或者创建空文档。

let fileDoc = PDFDocument(url: fileURL)
let dataDoc = PDFDocument(data: pdfData)
let emptyDoc = PDFDocument()

受密码保护的 PDF

guard let document = PDFDocument(url: url) else { return }
if document.isLocked {
    if !document.unlock(withPassword: userPassword) {
        // 显示密码提示
    }
}

保存与页面操作

document.write(to: outputURL)
document.write(to: outputURL, withOptions: [
    .ownerPasswordOption: "ownerPass", .userPasswordOption: "userPass"
])
let data = document.dataRepresentation()

// 页面（0 为起始）
let count = document.pageCount
document.insert(PDFPage(), at: count)
document.removePage(at: 2)
document.exchangePage(at: 0, withPageAt: 3)

页面导航

PDFView 提供内置导航，并支持历史记录。

// 跳转到指定页面
if let page = pdfView.document?.page(at: 5) {
    pdfView.go(to: page)
}

// 顺序导航
pdfView.goToNextPage(nil)
pdfView.goToPreviousPage(nil)
pdfView.goToFirstPage(nil)
pdfView.goToLastPage(nil)

// 检查导航状态
if pdfView.canGoToNextPage { /* ... */ }

// 历史导航
if pdfView.canGoBack { pdfView.goBack(nil) }

// 跳转到页面的指定点
let destination = PDFDestination(page: page, at: CGPoint(x: 0, y: 500))
pdfView.go(to: destination)

监听页面变化

NotificationCenter.default.addObserver(
    self, selector: #selector(pageChanged),
    name: .PDFViewPageChanged, object: pdfView
)

@objc func pageChanged(_ notification: Notification) {
    guard let page = pdfView.currentPage,
          let doc = pdfView.document else { return }
    let index = doc.index(for: page)
    pageLabel.text = "第 \(index + 1) 页，共 \(doc.pageCount) 页"
}

文本搜索和选择

同步搜索

let results: [PDFSelection] = document.findString(
    "搜索词", withOptions: [.caseInsensitive]
)

异步搜索

对大型文档进行后台搜索时使用 PDFDocumentDelegate。实现 didMatchString(_:) 以接收每个匹配结果，并使用 documentDidEndDocumentFind(_:) 获取完成通知。

增量搜索和查找交互

// 从当前选择中查找下一个匹配项
let next = document.findString("搜索词", fromSelection: current, withOptions: [.caseInsensitive])

// 系统查找栏（iOS 16+）
pdfView.isFindInteractionEnabled = true

文本提取

let fullText = document.string                          // 整个文档
let pageText = document.page(at: 0)?.string             // 单页
let attributed = document.page(at: 0)?.attributedString  // 带格式

// 基于区域的提取
if let page = document.page(at: 0) {
    let selection = page.selection(for: CGRect(x: 50, y: 50, width: 400, height: 200))
    let text = selection?.string
}

高亮搜索结果

let results = document.findString("重要", withOptions: [.caseInsensitive])
for selection in results { selection.color = .yellow }
pdfView.highlightedSelections = results

if let first = results.first {
    pdfView.setCurrentSelection(first, animate: true)
    pdfView.go(to: first)
}

标注

使用 PDFAnnotation(bounds:forType:withProperties:) 创建标注并添加到 PDFPage。

高亮标注

func addHighlight(to page: PDFPage, selection: PDFSelection) {
    let highlight = PDFAnnotation(
        bounds: selection.bounds(for: page),
        forType: .highlight, withProperties: nil
    )
    highlight.color = UIColor.yellow.withAlphaComponent(0.5)
    page.addAnnotation(highlight)
}

文本备注标注

let note = PDFAnnotation(
    bounds: CGRect(x: 100, y: 700, width: 30, height: 30),
    forType: .text, withProperties: nil
)
note.contents = "这是一条便签。"
note.color = .systemYellow
note.iconType = .comment
page.addAnnotation(note)

自由文本标注

let freeText = PDFAnnotation(
    bounds: CGRect(x: 50, y: 600, width: 300, height: 40),
    forType: .freeText, withProperties: nil
)
freeText.contents = "添加的注释"
freeText.font = UIFont.systemFont(ofSize: 14)
freeText.fontColor = .darkGray
page.addAnnotation(freeText)

链接标注

let link = PDFAnnotation(
    bounds: CGRect(x: 50, y: 500, width: 200, height: 20),
    forType: .link, withProperties: nil
)
link.url = URL(string: "https://example.com")
page.addAnnotation(link)

// 内部页面链接
link.destination = PDFDestination(page: targetPage, at: .zero)

移除标注

for annotation in page.annotations {
    page.removeAnnotation(annotation)
}

标注子类型参考

子类型	常量	用途
高亮	.highlight	文本标记（黄色高亮）
下划线	.underline	文本标记（下划线）
删除线	.strikeOut	文本标记（删除线）
文本	.text	便签图标
自由文本	.freeText	行内文本块
墨水	.ink	手绘路径
链接	.link	URL 或页面目的地
线条	.line	带端点的直线
方形	.square	矩形形状
圆形	.circle	椭圆形
印章	.stamp	橡皮图章（如“已批准”）
控件	.widget	表单元素（文本字段、复选框）

缩略图

PDFThumbnailView

PDFThumbnailView 显示与 PDFView 关联的页面缩略图条。

let thumbnailView = PDFThumbnailView()
thumbnailView.pdfView = pdfView
thumbnailView.thumbnailSize = CGSize(width: 60, height: 80)
thumbnailView.layoutMode = .vertical
thumbnailView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(thumbnailView)

程序化生成缩略图

let thumbnail = page.thumbnail(of: CGSize(width: 120, height: 160), for: .mediaBox)

// 所有页面
let thumbnails = (0..<document.pageCount).compactMap {
    document.page(at: $0)?.thumbnail(of: CGSize(width: 120, height: 160), for: .mediaBox)
}

SwiftUI 集成

将 PDFView 包装为 UIViewRepresentable 以在 SwiftUI 中使用。

import SwiftUI
import PDFKit

struct PDFKitView: UIViewRepresentable {
    let document: PDFDocument

    func makeUIView(context: Context) -> PDFView {
        let pdfView = PDFView()
        pdfView.autoScales = true
        pdfView.displayMode = .singlePageContinuous
        pdfView.document = document
        return pdfView
    }

    func updateUIView(_ pdfView: PDFView, context: Context) {
        if pdfView.document !== document {
            pdfView.document = document
        }
    }
}

使用

struct DocumentScreen: View {
    let url: URL

    var body: some View {
        if let document = PDFDocument(url: url) {
            PDFKitView(document: document)
                .ignoresSafeArea()
        } else {
            ContentUnavailableView("无法加载 PDF", systemImage: "doc.questionmark")
        }
    }
}

关于带页面跟踪、标注点击检测和协调器模式的交互式包装器，请参阅 references/pdfkit-patterns.md。

页面覆盖（iOS 16+）

PDFPageOverlayViewProvider 将 UIKit 视图放置在单个页面之上，用于标准标注之外的交互控件或自定义渲染。

class OverlayProvider: NSObject, PDFPageOverlayViewProvider {
    func pdfView(_ view: PDFView, overlayViewFor page: PDFPage) -> UIView? {
        let overlay = UIView()
        // 添加自定义子视图
        return overlay
    }
}

pdfView.pageOverlayViewProvider = overlayProvider

常见错误

不要：强制解包 PDFDocument 初始化

PDFDocument(url:) 和 PDFDocument(data:) 是可能失败的初始化方法。

// 错误
let document = PDFDocument(url: url)!

// 正确
guard let document = PDFDocument(url: url) else { return }

不要：忘记为 PDFView 设置 autoScales

不设置 autoScales，PDF 将以原始分辨率渲染。

// 错误
pdfView.document = document

// 正确
pdfView.autoScales = true
pdfView.document = document

不要：忽略标注中的 PDF 坐标系

PDF 页面坐标原点在左下角，Y 轴向上——与 UIKit 相反。

// 错误：UIKit 坐标
let bounds = CGRect(x: 50, y: 50, width: 200, height: 30)

// 正确：PDF 坐标（原点左下角）
let pageBounds = page.bounds(for: .mediaBox)
let pdfY = pageBounds.height - 50 - 30
let bounds = CGRect(x: 50, y: pdfY, width: 200, height: 30)

不要：在后台线程修改标注

PDFKit 类不是线程安全的。

// 错误
DispatchQueue.global().async { page.addAnnotation(annotation) }

// 正确
DispatchQueue.main.async { page.addAnnotation(annotation) }

不要：在 UIViewRepresentable 中使用 == 比较 PDFDocument

PDFDocument 是引用类型。应使用身份比较（!==）。

// 错误：总是替换文档
func updateUIView(_ pdfView: PDFView, context: Context) {
    pdfView.document = document
}

// 正确
func updateUIView(_ pdfView: PDFView, context: Context) {
    if pdfView.document !== document {
        pdfView.document = document
    }
}

审查清单

• PDFDocument 初始化使用可选绑定，而非强制解包
• 为正确初始显示设置 pdfView.autoScales = true
• 访问页面索引前检查 pageCount
• 根据设计配置 displayMode 和 displayDirection
• 标注使用 PDF 坐标空间（原点左下角，Y 向上）
• 所有 PDFKit 变更在主线程上执行
• 使用 isLocked / unlock(withPassword:) 处理受密码保护的 PDF
• SwiftUI 包装器在 updateUIView 中使用 !== 身份检查
• 观察 PDFViewPageChanged 通知以跟踪页面
• PDFThumbnailView.pdfView 与主 PDFView 关联
• 大型文档搜索使用异步 beginFindString 和代理
• 保存文档时在需要加密时使用 write(to:withOptions:)

参考

• 扩展模式（表单、水印、合并、打印、覆盖、大纲、自定义绘制）：references/pdfkit-patterns.md
• PDFKit 框架
• PDFView
• PDFDocument
• PDFPage
• PDFAnnotation
• PDFSelection
• PDFThumbnailView
• PDFPageOverlayViewProvider
• 向 PDF 文档添加控件
• 向 PDF 添加自定义图形