UIDocumentPickerViewController — cos’è, lavoro con i documenti iOS

Cos’è UIDocumentPickerViewController?

UIDocumentPickerViewController è un controller UIKit che fornisce un’interfaccia di sistema per selezionare documenti. Fa parte del framework UIKit ed è disponibile da iOS 8. Il controller mostra un browser di file che include archiviazione locale, iCloud Drive e servizi cloud di terze parti registrati.

Il controller funziona in modo asincrono: dopo aver chiamato present, l’utente vede un dialogo di sistema, seleziona un file e il risultato viene restituito tramite il delegato. L’app non richiede autorizzazioni speciali per accedere al file selezionato — il selettore di sistema fornisce automaticamente accesso temporaneo all’URI.

UIDocumentPickerViewController supporta iPad tramite UIPopoverPresentationController e un’interfaccia adattiva per iPhone. Da iOS 14, il controller ha ricevuto un design aggiornato e il supporto per la navigazione sidebar in iPadOS.

Modalità di funzionamento: import e export

UIDocumentPickerViewController opera in due modalità principali, ciascuna determina come l’app accede al file. La modalità viene impostata tramite il parametro forOpeningContentTypes o forExporting a seconda del compito.

Import mode (forOpeningContentTypes) copia il file selezionato nella sandbox dell’app. L’app riceve un URL alla propria copia del file, accessibile solo ad essa. Questa è una modalità sicura: il file di un’altra app non viene modificato e la copia è completamente controllata dall’app corrente.

Export mode (forExporting) fornisce un URL al file originale senza copiarlo. L’app può leggere il file tramite il link, ma le modifiche non vengono salvate. Questa modalità viene utilizzata quando è necessario trasferire un file a un’altra app o inviarlo via email. Per scrivere le modifiche, viene utilizzata la modalità open con scoped security-scoped URL.

Configurazione del picker e filtraggio UTI

UTI (Uniform Type Identifier) è un sistema di identificazione dei tipi di contenuto nell’ecosistema Apple. UIDocumentPickerViewController filtra i file visualizzati in base all’array UTI passato tramite forOpeningContentTypes. Se nessun UTI è specificato, il picker mostra tutti i tipi di file.

• PDF — com.adobe.pdf. Il picker mostra solo documenti PDF.
• Immagini — public.image. Include JPEG, PNG, HEIC e altri formati.
• Testo — public.plain-text. Mostra file .txt, .csv e altri.
• Audio — public.audio. Include MP3, AAC, WAV e formati Lossless.
• Video — public.movie. Mostra MP4, MOV, AVI e altri formati video.

Per selezionare più tipi, si passa un array [UTType.pdf, UTType.image]. Da iOS 14, Apple raccomanda di usare UTType invece di costanti stringa. UIDocumentPickerViewController aggiorna automaticamente l’elenco dei tipi visualizzati quando il provider selezionato cambia.

Esempio di codice: selezione documento in Swift

Implementazione di UIDocumentPickerViewController in Swift è minima: creare un’istanza del controller con i tipi UTI, impostare il delegato e chiamare present. Dopo la selezione del file, il delegato riceve un array di URL nel metodo didPickDocumentsAt. Ogni URL è un riferimento security-scoped che richiede la chiamata di 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() }
    // leggi file da url
}

Risorse Security-Scoped

Un URL security-scoped richiede la chiamata di startAccessingSecurityScopedResource prima della lettura. Questo metodo comunica al sistema che l’app sta ottenendo accesso temporaneo a un file fuori dalla sandbox. Dopo aver terminato, chiamare sempre stopAccessingSecurityScopedResource, altrimenti il sistema potrebbe bloccare l’accesso.

UIDocumentPickerDelegate e gestione dei risultati

UIDocumentPickerDelegate riceve i risultati della selezione file tramite due metodi: didPickDocumentsAt in caso di successo e didPickDocumentsAt in caso di annullamento. iOS chiama automaticamente il metodo di annullamento se l’utente chiude il picker senza effettuare una selezione.

La gestione degli errori include la verifica della disponibilità dell’URL. Se l’utente ha selezionato un file da iCloud Drive ma il dispositivo è offline, l’URL potrebbe non essere disponibile. Si raccomanda di verificare FileManager.default.isReadableFile prima di leggere e mostrare all’utente un messaggio di errore chiaro.

Per iOS 14+, è disponibile un nuovo metodo documentPicker:didPickDocumentsAt con un array di URL. Il vecchio metodo didPickDocumentAt (singolo) è deprecato. Gestire sempre l’array, anche se allowsMultipleSelection è disattivato — Apple raccomanda di utilizzare un singolo gestore.

UIDocumentPickerViewController su iPad

iPad richiede una configurazione speciale di UIDocumentPickerViewController. Su iPad, il picker viene visualizzato come popover e deve specificare un sourceView per il corretto posizionamento. Senza sourceView, il controller potrebbe crashare con un’eccezione su iPadOS.

Per il popover, viene utilizzata la proprietà popoverPresentationController. Specificare sourceView e sourceRect per ancorarlo a un pulsante o una cella di tabella. Su iPhone, questo codice non ha effetto — iOS mostra automaticamente il picker a schermo intero. Da iPadOS 16, il controller supporta sidebar e split view per una navigazione migliorata.

Il design adattivo di UIDocumentPickerViewController passa automaticamente tra schermo intero (iPhone) e popover (iPad). Lo sviluppatore non deve implementare controller separati per dispositivi diversi — basta configurare correttamente il popoverPresentationController per iPad.