PDFKit
Exiba, navegue, pesquise, anote e manipule documentos PDF com
PDFView, PDFDocument, PDFPage, PDFAnnotation e PDFSelection.
Alvo: Swift 6.3 / iOS 26+.
Conteúdo
- Configuração
- Exibindo PDFs
- Carregando Documentos
- Navegação entre Páginas
- Busca e Seleção de Texto
- Anotações
- Miniaturas
- Integração com SwiftUI
- Erros Comuns
- Lista de Verificação de Revisão
- Referências
Configuração
PDFKit não requer entitlements ou entradas no Info.plist.
import PDFKit
Disponibilidade de plataforma: iOS 11+, iPadOS 11+, Mac Catalyst 13.1+, macOS 10.4+, tvOS 11+, visionOS 1.0+.
Exibindo PDFs
PDFView é uma subclasse de UIView que renderiza conteúdo PDF, lida com zoom,
rolagem, seleção de texto e navegação entre páginas prontamente.
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)
}
}
}
Modos de Exibição
| Modo | Comportamento |
|---|---|
.singlePage | Uma página por vez |
.singlePageContinuous | Páginas empilhadas verticalmente, roláveis |
.twoUp | Duas páginas lado a lado |
.twoUpContinuous | Duas páginas com rolagem contínua |
Escala e Aparência
pdfView.autoScales = true
pdfView.minScaleFactor = pdfView.scaleFactorForSizeToFit
pdfView.maxScaleFactor = 4.0
pdfView.displaysPageBreaks = true
pdfView.pageShadowsEnabled = true
pdfView.interpolationQuality = .high
Carregando Documentos
PDFDocument carrega a partir de uma URL, Data, ou pode ser criado vazio.
let fileDoc = PDFDocument(url: fileURL)
let dataDoc = PDFDocument(data: pdfData)
let emptyDoc = PDFDocument()
PDFs Protegidos por Senha
guard let document = PDFDocument(url: url) else { return }
if document.isLocked {
if !document.unlock(withPassword: userPassword) {
// Mostrar prompt de senha
}
}
Salvando e Manipulando Páginas
document.write(to: outputURL)
document.write(to: outputURL, withOptions: [
.ownerPasswordOption: "ownerPass", .userPasswordOption: "userPass"
])
let data = document.dataRepresentation()
// Páginas (base 0)
let count = document.pageCount
document.insert(PDFPage(), at: count)
document.removePage(at: 2)
document.exchangePage(at: 0, withPageAt: 3)
Navegação entre Páginas
PDFView fornece navegação integrada com histórico.
// Ir para uma página específica
if let page = pdfView.document?.page(at: 5) {
pdfView.go(to: page)
}
// Navegação sequencial
pdfView.goToNextPage(nil)
pdfView.goToPreviousPage(nil)
pdfView.goToFirstPage(nil)
pdfView.goToLastPage(nil)
// Verificar estado da navegação
if pdfView.canGoToNextPage { /* ... */ }
// Navegação pelo histórico
if pdfView.canGoBack { pdfView.goBack(nil) }
// Ir para um ponto específico em uma página
let destination = PDFDestination(page: page, at: CGPoint(x: 0, y: 500))
pdfView.go(to: destination)
Observando Mudanças de Página
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 = "Página \(index + 1) de \(doc.pageCount)"
}
Busca e Seleção de Texto
Busca Síncrona
let results: [PDFSelection] = document.findString(
"termo de busca", withOptions: [.caseInsensitive]
)
Busca Assíncrona
Use PDFDocumentDelegate para buscas em segundo plano em documentos grandes.
Implemente didMatchString(_:) para receber cada correspondência e
documentDidEndDocumentFind(_:) para conclusão.
Busca Incremental e Interação de Localizar
// Encontrar próxima correspondência a partir da seleção atual
let next = document.findString("termo", fromSelection: current, withOptions: [.caseInsensitive])
// Barra de localizar do sistema (iOS 16+)
pdfView.isFindInteractionEnabled = true
Extração de Texto
let fullText = document.string // Documento inteiro
let pageText = document.page(at: 0)?.string // Página única
let attributed = document.page(at: 0)?.attributedString // Com formatação
// Extração baseada em região
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
}
Destacando Resultados de Busca
let results = document.findString("importante", 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)
}
Anotações
Anotações são criadas com PDFAnnotation(bounds:forType:withProperties:)
e adicionadas a uma PDFPage.
Anotação de Destaque
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)
}
Anotação de Nota de Texto
let note = PDFAnnotation(
bounds: CGRect(x: 100, y: 700, width: 30, height: 30),
forType: .text, withProperties: nil
)
note.contents = "Esta é uma nota adesiva."
note.color = .systemYellow
note.iconType = .comment
page.addAnnotation(note)
Anotação de Texto Livre
let freeText = PDFAnnotation(
bounds: CGRect(x: 50, y: 600, width: 300, height: 40),
forType: .freeText, withProperties: nil
)
freeText.contents = "Comentário adicionado"
freeText.font = UIFont.systemFont(ofSize: 14)
freeText.fontColor = .darkGray
page.addAnnotation(freeText)
Anotação de Link
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 para página interna
link.destination = PDFDestination(page: targetPage, at: .zero)
Removendo Anotações
for annotation in page.annotations {
page.removeAnnotation(annotation)
}
Referência de Subtipos de Anotação
| Subtipo | Constante | Propósito |
|---|---|---|
| Destaque | .highlight | Marcação de texto (destaque amarelo) |
| Sublinhado | .underline | Marcação de texto (sublinhado) |
| Tachado | .strikeOut | Marcação de texto (tachado) |
| Texto | .text | Ícone de nota adesiva |
| TextoLivre | .freeText | Bloco de texto inline |
| Tinta | .ink | Traços de desenho à mão livre |
| Link | .link | URL ou destino de página |
| Linha | .line | Linha reta com pontos finais |
| Quadrado | .square | Forma retangular |
| Círculo | .circle | Forma elíptica |
| Carimbo | .stamp | Carimbo (Aprovado, etc.) |
| Widget | .widget | Elemento de formulário (campo de texto, caixa de seleção) |
Miniaturas
PDFThumbnailView
PDFThumbnailView mostra uma faixa de miniaturas de página vinculadas a um PDFView.
let thumbnailView = PDFThumbnailView()
thumbnailView.pdfView = pdfView
thumbnailView.thumbnailSize = CGSize(width: 60, height: 80)
thumbnailView.layoutMode = .vertical
thumbnailView.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(thumbnailView)
Gerando Miniaturas Programaticamente
let thumbnail = page.thumbnail(of: CGSize(width: 120, height: 160), for: .mediaBox)
// Todas as páginas
let thumbnails = (0..<document.pageCount).compactMap {
document.page(at: $0)?.thumbnail(of: CGSize(width: 120, height: 160), for: .mediaBox)
}
Integração com SwiftUI
Envolva PDFView em um UIViewRepresentable para 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
}
}
}
Uso
struct DocumentScreen: View {
let url: URL
var body: some View {
if let document = PDFDocument(url: url) {
PDFKitView(document: document)
.ignoresSafeArea()
} else {
ContentUnavailableView("Não foi possível carregar o PDF", systemImage: "doc.questionmark")
}
}
}
Para wrappers interativos com rastreamento de página, detecção de toque em anotações e padrões de coordenador, veja references/pdfkit-patterns.md.
Sobreposições de Página (iOS 16+)
PDFPageOverlayViewProvider coloca visualizações UIKit sobre páginas individuais
para controles interativos ou renderização personalizada além das anotações padrão.
class OverlayProvider: NSObject, PDFPageOverlayViewProvider {
func pdfView(_ view: PDFView, overlayViewFor page: PDFPage) -> UIView? {
let overlay = UIView()
// Adicionar subvisualizações personalizadas
return overlay
}
}
pdfView.pageOverlayViewProvider = overlayProvider
Erros Comuns
NÃO FAÇA: Forçar desempacotamento do init de PDFDocument
PDFDocument(url:) e PDFDocument(data:) são inicializadores falíveis.
// ERRADO
let document = PDFDocument(url: url)!
// CORRETO
guard let document = PDFDocument(url: url) else { return }
NÃO FAÇA: Esquecer autoScales no PDFView
Sem autoScales, o PDF renderiza em sua resolução nativa.
// ERRADO
pdfView.document = document
// CORRETO
pdfView.autoScales = true
pdfView.document = document
NÃO FAÇA: Ignorar o sistema de coordenadas PDF em anotações
As coordenadas de página PDF têm origem no canto inferior esquerdo com Y aumentando para cima — oposto ao UIKit.
// ERRADO: Coordenadas UIKit
let bounds = CGRect(x: 50, y: 50, width: 200, height: 30)
// CORRETO: Coordenadas PDF (origem canto inferior esquerdo)
let pageBounds = page.bounds(for: .mediaBox)
let pdfY = pageBounds.height - 50 - 30
let bounds = CGRect(x: 50, y: pdfY, width: 200, height: 30)
NÃO FAÇA: Modificar anotações em uma thread de segundo plano
As classes PDFKit não são thread-safe.
// ERRADO
DispatchQueue.global().async { page.addAnnotation(annotation) }
// CORRETO
DispatchQueue.main.async { page.addAnnotation(annotation) }
NÃO FAÇA: Comparar PDFDocument com == em UIViewRepresentable
PDFDocument é um tipo de referência. Use identidade (!==).
// ERRADO: Sempre substitui o documento
func updateUIView(_ pdfView: PDFView, context: Context) {
pdfView.document = document
}
// CORRETO
func updateUIView(_ pdfView: PDFView, context: Context) {
if pdfView.document !== document {
pdfView.document = document
}
}
Lista de Verificação de Revisão
-
PDFDocumentinit usa ligação opcional, não força desempacotamento -
pdfView.autoScales = truedefinido para exibição inicial adequada - Índices de página verificados em relação a
pageCountantes do acesso -
displayModeedisplayDirectionconfigurados para corresponder ao design - Anotações usam o espaço de coordenadas PDF (origem no canto inferior esquerdo, Y para cima)
- Todas as mutações do PDFKit ocorrem na thread principal
- PDFs protegidos por senha tratados com
isLocked/unlock(withPassword:) - Wrapper SwiftUI usa verificação de identidade
!==emupdateUIView - Notificação
PDFViewPageChangedobservada para rastreamento de página -
PDFThumbnailView.pdfViewvinculado aoPDFViewprincipal - Busca em documentos grandes usa
beginFindStringassíncrono com delegate - Documentos salvos usam
write(to:withOptions:)quando a criptografia é necessária
Referências
- Padrões estendidos (formulários, marcas d'água, mesclagem, impressão, sobreposições, esboços, desenho personalizado): references/pdfkit-patterns.md
- PDFKit framework
- PDFView
- PDFDocument
- PDFPage
- PDFAnnotation
- PDFSelection
- PDFThumbnailView
- PDFPageOverlayViewProvider
- Adicionando Widgets a um Documento PDF
- Adicionando Gráficos Personalizados a um PDF