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() }
    // read file from 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.