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 режим (forOpeningContentTypes) копира изабрану датотеку у пешчаник апликације. Апликација добија URL сопствене копије датотеке, доступне само њој. Ово је сигуран режим: датотека друге апликације се не мења, а копија је у потпуности контролисана од стране тренутне апликације.

Export режим (forExporting) обезбеђује URL оригиналне датотеке без копирања. Апликација може читати датотеку преко линка, али измене се не чувају назад. Овај режим се користи када је потребно пренети датотеку другој апликацији или је послати поштом. За упис промена користи се режим open са 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-а контролер може пасти са изузетком на iPadOS-у.

За popover се користи својство popoverPresentationController. Наведите sourceView и sourceRect за причвршћивање за дугме или ћелију табеле. На iPhone-у овај код нема утицаја — iOS аутоматски приказује пикер преко целог екрана. Од iPadOS 16, контролер подржава sidebar и split view за побољшану навигацију.

Адаптивни дизајн UIDocumentPickerViewController-а аутоматски се пребацује између full-screen (iPhone) и popover (iPad). Програмер не мора да имплементира засебне контролере за различите уређаје — довољно је правилно подесити popoverPresentationController за iPad.