UIDocumentPickerViewController — работа с документи в iOS

Какво е UIDocumentPickerViewController?

UIDocumentPickerViewController — е UIKit контролер, който предоставя системен интерфейс за избор на документи. Той е част от рамката UIKit и е достъпен от iOS 8. Контролерът показва браузър за файлове, който включва локално хранилище, iCloud Drive и регистрирани облачни услуги на трети страни.

Контролерът работи асинхронно: след извикване на present, потребителят вижда системен диалог, избира файла и резултатът се връща чрез делегат. Приложението не изисква специални разрешения за достъп до избрания файл — системният picker автоматично предоставя временен достъп до URI.

UIDocumentPickerViewController поддържа iPad чрез UIPopoverPresentationController и адаптивен интерфейс за iPhone. От iOS 14, контролерът получи обновен дизайн и поддръжка за sidebar навигация в iPadOS.

Режими на работа: import и export

UIDocumentPickerViewController работи в два основни режима, всеки от които определя как приложението получава достъп до файла. Режимът се задава чрез параметъра forOpeningContentTypes или forExporting в зависимост от задачата.

Режим Import (forOpeningContentTypes) копира избрания файл в пясъчника на приложението. Приложението получава URL на собственото си копие на файла, достъпно само за него. Това е безопасен режим: файлът на друго приложение не се променя, а копието е напълно контролирано от текущото приложение.

Режим Export (forExporting) предоставя URL на оригиналния файл без копиране. Приложението може да чете файла чрез връзката, но промените не се запазват обратно. Този режим се използва, когато трябва да прехвърлите файл към друго приложение или да го изпратите по имейл. За запис на промени се използва режим open с security-scoped URL.

Конфигуриране на picker и филтриране по UTI

UTI (Uniform Type Identifier) — е система за идентификация на типове съдържание в екосистемата на Apple. UIDocumentPickerViewController филтрира показаните файлове според UTI масив, предаден чрез forOpeningContentTypes. Ако UTI не е посочен, picker показва всички типове файлове.

• PDF — com.adobe.pdf. Picker показва само PDF документи.
• Изображения — public.image. Включва JPEG, PNG, HEIC и други формати.
• Текст — public.plain-text. Показва .txt, .csv и други текстови файлове.
• Аудио — public.audio. Включва MP3, AAC, WAV и Lossless формати.
• Видео — public.movie. Показва MP4, MOV, AVI и други видео формати.

За избор на множество типове се предава масив [UTType.pdf, UTType.image]. От iOS 14, Apple препоръчва използването на UTType вместо низови константи. UIDocumentPickerViewController автоматично актуализира списъка с показани типове при промяна на избрания доставчик.

Примерен код: избор на документ в Swift

Имплементация на UIDocumentPickerViewController в Swift е минимална: създайте инстанция на контролера с UTI типове, задайте делегат и извикайте present. След избор на файл, делегатът получава масив от URL в метода didPickDocumentsAt. Всеки URL е security-scoped връзка, която изисква извикване на startAccessingSecurityScopedResource.

let picker = UIDocumentPickerViewController(
    forOpeningContentTypes: [.pdf, .image],
    asCopy: true
)
picker.delegate = self
picker.allowsMultipleSelection = false
present(picker, animated: true)

// MARK: - UIDocumentPickerDelegate
func documentPicker(
    _ controller: UIDocumentPickerViewController,
    didPickDocumentsAt urls: [URL]
) {
    guard let url = urls.first else { return }
    url.startAccessingSecurityScopedResource()
    defer { url.stopAccessingSecurityScopedResource() }
    // четене на файл от url
}

Security-scoped ресурси

Security-scoped URL изисква извикване на startAccessingSecurityScopedResource преди четене. Този метод уведомява системата, че приложението получава временен достъп до файл извън пясъчника. След приключване задължително извикайте stopAccessingSecurityScopedResource, в противен случай системата може да блокира достъпа.

UIDocumentPickerDelegate и обработка на резултати

UIDocumentPickerDelegate получава резултатите от избора на файл чрез два метода: didPickDocumentsAt при успех и didPickDocumentsAt при отказ. iOS автоматично извиква метода за отказ, ако потребителят е затворил picker-а без избор.

Обработката на грешки включва проверка на наличността на URL. Ако потребителят е избрал файл от iCloud Drive, но устройството е офлайн, URL може да не е наличен. Препоръчва се проверка на FileManager.default.isReadableFile преди четене и показване на разбираемо съобщение за грешка.

За iOS 14+ е наличен новият метод documentPicker:didPickDocumentsAt с масив от URL. Старият метод didPickDocumentAt (единичен) е остарял. Винаги обработвайте масива, дори ако allowsMultipleSelection е изключен — Apple препоръчва използване на единен handler.

UIDocumentPickerViewController на iPad

iPad изисква специална конфигурация на UIDocumentPickerViewController. На iPad picker-ът се показва като popover и изисква посочване на sourceView за правилно позициониране. Без sourceView контролерът може да падне с изключение на iPadOS.

За popover се използва свойството popoverPresentationController. Посочете sourceView и sourceRect за закрепване към бутон или клетка от таблица. На iPhone този код няма ефект — iOS автоматично показва picker-а на цял екран. От iPadOS 16, контролерът поддържа sidebar и split view за подобрена навигация.

Адаптивният дизайн на UIDocumentPickerViewController автоматично превключва между full-screen (iPhone) и popover (iPad). Разработчикът не трябва да имплементира отделни контролери за различни устройства — достатъчно е правилно да конфигурира popoverPresentationController за iPad.