UIDocumentPickerViewController — lucrul cu documente în iOS

Ce este UIDocumentPickerViewController?

UIDocumentPickerViewController — este un controler UIKit care oferă o interfață de sistem pentru selectarea documentelor. Face parte din framework-ul UIKit și este disponibil începând cu iOS 8. Controlerul afișează un browser de fișiere care include stocarea locală, iCloud Drive și serviciile cloud terțe înregistrate.

Controlerul funcționează asincron: după apelarea present, utilizatorul vede un dialog de sistem, selectează fișierul, iar rezultatul este returnat prin delegat. Aplicația nu necesită permisiuni speciale pentru accesarea fișierului selectat — picker-ul de sistem oferă automat acces temporar la URI.

UIDocumentPickerViewController suportă iPad prin UIPopoverPresentationController și o interfață adaptivă pentru iPhone. Începând cu iOS 14, controlerul a primit un design actualizat și suport pentru navigarea sidebar în iPadOS.

Moduri de lucru: import și export

UIDocumentPickerViewController funcționează în două moduri principale, fiecare determinând modul în care aplicația accesează fișierul. Modul este setat prin parametrul forOpeningContentTypes sau forExporting în funcție de sarcină.

Modul Import (forOpeningContentTypes) copiază fișierul selectat în sandbox-ul aplicației. Aplicația primește URL-ul propriei copii a fișierului, accesibilă doar ei. Este un mod sigur: fișierul altei aplicații nu este modificat, iar copia este complet controlată de aplicația curentă.

Modul Export (forExporting) oferă URL-ul fișierului original fără copiere. Aplicația poate citi fișierul prin link, dar modificările nu sunt salvate înapoi. Acest mod este utilizat când trebuie să transferați un fișier către o altă aplicație sau să îl trimiteți prin poștă. Pentru scrierea modificărilor se utilizează modul open cu URL securizat (security-scoped).

Configurarea picker-ului și filtrarea după UTI

UTI (Uniform Type Identifier) — este un sistem de identificare a tipurilor de conținut în ecosistemul Apple. UIDocumentPickerViewController filtrează fișierele afișate după un tablou UTI transmis prin forOpeningContentTypes. Dacă UTI nu este specificat, picker-ul afișează toate tipurile de fișiere.

• PDF — com.adobe.pdf. Picker-ul arată doar documente PDF.
• Imagini — public.image. Include JPEG, PNG, HEIC și alte formate.
• Text — public.plain-text. Afișează fișiere .txt, .csv și alte fișiere text.
• Audio — public.audio. Include MP3, AAC, WAV și formate Lossless.
• Video — public.movie. Afișează MP4, MOV, AVI și alte formate video.

Pentru selectarea mai multor tipuri se transmite tabloul [UTType.pdf, UTType.image]. Începând cu iOS 14, Apple recomandă utilizarea UTType în locul constantelor șir. UIDocumentPickerViewController actualizează automat lista tipurilor afișate la schimbarea furnizorului selectat.

Exemplu de cod: selectarea unui document în Swift

Implementarea UIDocumentPickerViewController în Swift este minimă: creați o instanță a controlerului cu tipuri UTI, setați delegatul și apelați present. După selectarea fișierului, delegatul primește un tablou de URL-uri în metoda didPickDocumentsAt. Fiecare URL este un link securizat (security-scoped) care necesită apelarea 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() }
    // citește fișierul din url
}

Resurse security-scoped

URL-ul securizat (security-scoped) necesită apelarea startAccessingSecurityScopedResource înainte de citire. Această metodă informează sistemul că aplicația obține acces temporar la un fișier în afara sandbox-ului. După finalizare, apelați obligatoriu stopAccessingSecurityScopedResource, altfel sistemul poate bloca accesul.

UIDocumentPickerDelegate și gestionarea rezultatelor

UIDocumentPickerDelegate primește rezultatele selecției fișierului prin două metode: didPickDocumentsAt la succes și didPickDocumentsAt la anulare. iOS apelează automat metoda de anulare dacă utilizatorul a închis picker-ul fără a selecta.

Gestionarea erorilor include verificarea disponibilității URL-ului. Dacă utilizatorul a selectat un fișier din iCloud Drive, dar dispozitivul este offline, URL-ul poate fi indisponibil. Se recomandă verificarea FileManager.default.isReadableFile înainte de citire și afișarea unui mesaj de eroare ușor de înțeles.

Pentru iOS 14+ este disponibilă noua metodă documentPicker:didPickDocumentsAt cu un tablou de URL-uri. Vechea metodă didPickDocumentAt (unică) este deprecated. Gestionați întotdeauna tabloul, chiar dacă allowsMultipleSelection este dezactivat — Apple recomandă utilizarea unui handler unic.

UIDocumentPickerViewController pe iPad

iPad necesită o configurație specială a UIDocumentPickerViewController. Pe iPad, picker-ul se afișează ca popover și necesită specificarea sourceView pentru poziționarea corectă. Fără sourceView, controlerul poate cădea cu excepție pe iPadOS.

Pentru popover se utilizează proprietatea popoverPresentationController. Specificați sourceView și sourceRect pentru ancorarea la un buton sau celulă de tabel. Pe iPhone acest cod nu are efect — iOS afișează automat picker-ul pe tot ecranul. Începând cu iPadOS 16, controlerul suportă sidebar și split view pentru o navigare îmbunătățită.

Designul adaptiv al UIDocumentPickerViewController comută automat între full-screen (iPhone) și popover (iPad). Dezvoltatorul nu trebuie să implementeze controlere separate pentru diferite dispozitive — este suficientă configurarea corectă a popoverPresentationController pentru iPad.