UIDocumentPickerViewController — qu’est-ce que c’est, travail avec les documents iOS

Qu’est-ce que UIDocumentPickerViewController ?

UIDocumentPickerViewController est un contrôleur UIKit qui fournit une interface système pour sélectionner des documents. Il fait partie du framework UIKit et est disponible depuis iOS 8. Le contrôleur affiche un navigateur de fichiers qui inclut le stockage local, iCloud Drive et les services cloud tiers enregistrés.

Le contrôleur fonctionne de manière asynchrone : après avoir appelé present, l’utilisateur voit une boîte de dialogue système, sélectionne un fichier et le résultat est retourné via le délégué. L’application ne nécessite pas d’autorisations spéciales pour accéder au fichier sélectionné — le sélecteur système fournit automatiquement un accès temporaire à l’URI.

UIDocumentPickerViewController prend en charge iPad via UIPopoverPresentationController et une interface adaptative pour iPhone. Depuis iOS 14, le contrôleur a reçu un design mis à jour et la prise en charge de la navigation par sidebar dans iPadOS.

Modes de fonctionnement : import et export

UIDocumentPickerViewController fonctionne dans deux modes principaux, chacun détermine comment l’application accède au fichier. Le mode est défini via le paramètre forOpeningContentTypes ou forExporting selon la tâche.

Import mode (forOpeningContentTypes) copie le fichier sélectionné dans le bac à sable de l’application. L’application reçoit une URL vers sa propre copie du fichier, accessible uniquement par elle. C’est un mode sécurisé : le fichier d’une autre application n’est pas modifié et la copie est entièrement contrôlée par l’application actuelle.

Export mode (forExporting) fournit une URL vers le fichier original sans le copier. L’application peut lire le fichier via le lien, mais les modifications ne sont pas enregistrées. Ce mode est utilisé lorsqu’on doit transférer un fichier à une autre application ou l’envoyer par courriel. Pour écrire des modifications, le mode open avec scoped security-scoped URL est utilisé.

Configuration du picker et filtrage par UTI

UTI (Uniform Type Identifier) est un système d’identification des types de contenu dans l’écosystème Apple. UIDocumentPickerViewController filtre les fichiers affichés selon le tableau d’UTI passé via forOpeningContentTypes. Si aucune UTI n’est spécifiée, le picker affiche tous les types de fichiers.

• PDF — com.adobe.pdf. Le picker affiche uniquement les documents PDF.
• Images — public.image. Inclut JPEG, PNG, HEIC et d’autres formats.
• Texte — public.plain-text. Affiche les fichiers .txt, .csv et autres.
• Audio — public.audio. Inclut MP3, AAC, WAV et les formats Lossless.
• Vidéo — public.movie. Affiche MP4, MOV, AVI et autres formats vidéo.

Pour sélectionner plusieurs types, on passe un tableau [UTType.pdf, UTType.image]. Depuis iOS 14, Apple recommande d’utiliser UTType au lieu de constantes de chaîne. UIDocumentPickerViewController met automatiquement à jour la liste des types affichés lorsque le fournisseur sélectionné change.

Exemple de code : sélection de document en Swift

Implémentation de UIDocumentPickerViewController en Swift est minimale : créer une instance du contrôleur avec des types UTI, définir le délégué et appeler present. Après la sélection du fichier, le délégué reçoit un tableau d’URLs dans la méthode didPickDocumentsAt. Chaque URL est une référence security-scoped nécessitant l’appel de 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() }
    // lire le fichier depuis l’url
}

Ressources Security-Scoped

Une URL security-scoped nécessite l’appel de startAccessingSecurityScopedResource avant la lecture. Cette méthode indique au système que l’application obtient un accès temporaire à un fichier en dehors du bac à sable. Après avoir terminé, appelez toujours stopAccessingSecurityScopedResource, sinon le système peut bloquer l’accès.

UIDocumentPickerDelegate et gestion des résultats

UIDocumentPickerDelegate reçoit les résultats de la sélection de fichiers via deux méthodes : didPickDocumentsAt en cas de succès et didPickDocumentsAt en cas d’annulation. iOS appelle automatiquement la méthode d’annulation si l’utilisateur ferme le picker sans effectuer de sélection.

La gestion des erreurs inclut la vérification de la disponibilité de l’URL. Si l’utilisateur a sélectionné un fichier depuis iCloud Drive mais que l’appareil est hors ligne, l’URL peut être indisponible. Il est recommandé de vérifier FileManager.default.isReadableFile avant la lecture et d’afficher à l’utilisateur un message d’erreur clair.

Pour iOS 14+, une nouvelle méthode documentPicker:didPickDocumentsAt avec un tableau d’URLs est disponible. L’ancienne méthode didPickDocumentAt (unique) est obsolète. Traitez toujours le tableau, même si allowsMultipleSelection est désactivé — Apple recommande d’utiliser un seul gestionnaire.

UIDocumentPickerViewController sur iPad

iPad nécessite une configuration spéciale de UIDocumentPickerViewController. Sur iPad, le picker s’affiche comme un popover et doit spécifier un sourceView pour un positionnement correct. Sans sourceView, le contrôleur peut planter avec une exception sur iPadOS.

Pour le popover, la propriété popoverPresentationController est utilisée. Spécifiez sourceView et sourceRect pour l’ancrer à un bouton ou une cellule de tableau. Sur iPhone, ce code n’a aucun effet — iOS affiche automatiquement le picker en plein écran. Depuis iPadOS 16, le contrôleur prend en charge la sidebar et la vue fractionnée pour une navigation améliorée.

Le design adaptatif de UIDocumentPickerViewController bascule automatiquement entre plein écran (iPhone) et popover (iPad). Le développeur n’a pas besoin d’implémenter des contrôleurs séparés pour différents appareils — il suffit de configurer correctement le popoverPresentationController pour iPad.