UIDocumentPickerViewController — що це, робота з документами iOS

Що таке UIDocumentPickerViewController?

UIDocumentPickerViewController — це контролер UIKit, що надає системний інтерфейс для вибору документів. Він входить у фреймворк UIKit та доступний починаючи з iOS 8. Контролер відображає браузер файлів, який включає локальне сховище, iCloud Drive та зареєстровані сторонні хмарні сервіси.

Контролер працює асинхронно: після виклику present користувач бачить системний діалог, вибирає файл, і результат повертається через делегата. Застосунок не потребує спеціальних дозволів для доступу до вибраного файлу — системний пікер автоматично надає тимчасовий доступ до URI.

UIDocumentPickerViewController підтримує iPad через UIPopoverPresentationController та адаптивний інтерфейс для iPhone. Починаючи з iOS 14, контролер отримав оновлений дизайн та підтримку sidebar-навігації в iPadOS.

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

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

Import mode (forOpeningContentTypes) копіює вибраний файл у пісочницю застосунку. Застосунок отримує URL на власну копію файлу, доступну тільки йому. Це безпечний режим: файл іншого застосунку не змінюється, а копія повністю контролюється поточним застосунком.

Export mode (forExporting) надає URL на оригінальний файл без копіювання. Застосунок може читати файл за посиланням, але зміни не зберігаються. Цей режим використовується, коли потрібно передати файл іншому застосунку або надіслати поштою. Для запису змін використовується режим open з scoped security-scoped URL.

Налаштування пікера та фільтрація за UTI

UTI (Uniform Type Identifier) — це система ідентифікації типів контенту в екосистемі Apple. UIDocumentPickerViewController фільтрує файли, що відображаються, за масивом UTI, переданим через forOpeningContentTypes. Якщо UTI не вказано, пікер показує всі типи файлів.

• PDF — com.adobe.pdf. Пікер показує лише 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 автоматично викликає метод скасування, якщо користувач закрив пікер без вибору.

Обробка помилок включає перевірку доступності URL. Якщо користувач вибрав файл з iCloud Drive, але пристрій офлайн, URL може бути недоступний. Рекомендується перевіряти FileManager.default.isReadableFile перед читанням та показувати користувачеві зрозуміле повідомлення про помилку.

Для iOS 14+ доступний новий метод documentPicker:didPickDocumentsAt з масивом URL. Старий метод didPickDocumentAt (одинарний) deprecated. Завжди обробляйте масив, навіть якщо allowsMultipleSelection вимкнено — Apple рекомендує використовувати єдиний обробник.

UIDocumentPickerViewController на iPad

iPad потребує спеціальної конфігурації UIDocumentPickerViewController. На iPad пікер відображається як popover, і йому необхідно вказати sourceView для коректного позиціонування. Без sourceView контролер може впасти з exception на iPadOS.

Для popover використовується властивість popoverPresentationController. Вкажіть sourceView та sourceRect для прив’язки до кнопки або комірки таблиці. На iPhone цей код не впливає — iOS автоматично показує пікер на весь екран. Починаючи з iPadOS 16, контролер підтримує sidebar та split view для покращеної навігації.

Адаптивний дизайн UIDocumentPickerViewController автоматично перемикається між full-screen (iPhone) та popover (iPad). Розробнику не потрібно реалізовувати окремі контролери для різних пристроїв — достатньо коректно налаштувати popoverPresentationController для iPad.