Répertoire de documents dans une application mobile — définition, objectif et comment organiser le stockage

Qu'est-ce que le répertoire de documents de l'application ?

Le répertoire de documents est un stockage spécialisé à l'intérieur du sandbox de l'application, conçu pour le stockage permanent des fichiers utilisateur. Contrairement au cache, les fichiers dans ce répertoire sont considérés comme importants pour l'utilisateur : ils ne sont pas supprimés par le système en cas de manque d'espace, sont conservés lors des mises à jour de l'application et sont sauvegardés lors de la synchronisation de l'appareil. Sur iOS, le répertoire Documents fait partie du conteneur Sandbox et est automatiquement inclus dans la sauvegarde iCloud. Sur Android, il n'existe pas d'équivalent direct — l'équivalent est context.filesDir, qui est également destiné aux fichiers permanents mais ne dispose pas de mécanisme de sauvegarde intégré.

La différence entre le répertoire de documents et le stockage interne sur Android est minime : les deux se trouvent dans le sandbox de l'application, les deux sont supprimés lors de la désinstallation, les deux sont inaccessibles aux autres applications. La principale différence est sémantique : le répertoire Documents suppose que les fichiers sont créés ou importés par l'utilisateur, tandis que le stockage interne peut contenir des fichiers internes de l'application (bases de données, configurations). Sur iOS, la différence est plus substantielle : Documents est automatiquement sauvegardé, tandis que Library/Application Support ne l'est pas. Cela affecte la stratégie de stockage : placez uniquement ce que l'utilisateur souhaiterait restaurer sur un nouvel appareil dans Documents, et les données internes que l'application peut recréer dans Application Support.

L'architecture sandbox garantit que les autres applications ne peuvent pas accéder au répertoire de documents de votre application. Sur iOS, l'accès aux Documents d'autres applications est impossible sans jailbreak. Sur Android, l'accès root permet de lire le filesDir de n'importe quelle application, donc les données sensibles (jetons, clés de chiffrement) doivent être protégées supplémentairement avec EncryptedSharedPreferences ou EncryptedFile de la bibliothèque AndroidX Security.

Quelles données sont stockées dans le répertoire de documents

Le répertoire de documents doit stocker les données qui ont de la valeur pour l'utilisateur et doivent être accessibles après le redémarrage de l'application ou la restauration de l'appareil. Tous les fichiers ne conviennent pas au stockage dans ce répertoire — le choix dépend du type de données et du scénario d'utilisation.

Documents et fichiers utilisateur

Les fichiers utilisateur sont le contenu principal du répertoire de documents. Il peut s'agir de documents texte créés dans un éditeur, d'images prises avec l'appareil photo de l'application, de rapports PDF exportés, d'enregistrements audio, de notes. Chacun de ces fichiers est créé par l'utilisateur ou à sa demande et doit être accessible à tout moment. Sur iOS, les fichiers de Documents sont affichés dans l'application Fichiers du système, permettant à l'utilisateur de les gérer via le gestionnaire de fichiers standard. Sur Android, il n'y a pas d'affichage similaire — l'application doit elle-même fournir une interface pour visualiser les fichiers enregistrés.

Bases de données et paramètres de l'application

Les bases de données SQLite et les fichiers de paramètres sont généralement stockés près du répertoire de documents, mais pas à l'intérieur. Sur iOS, les bases de données sont placées dans Library/Application Support, car elles ne doivent pas apparaître dans l'application Fichiers ni être sauvegardées séparément. Sur Android, les bases de données sont créées par défaut dans /data/data/<package>/databases/ via Room ou SQLiteOpenHelper. Si la base de données contient du contenu utilisateur (notes, journal, relevés financiers), elle peut être placée dans filesDir pour garantir la sauvegarde système. Room permet de spécifier un répertoire de stockage personnalisé pour la base de données via le callback RoomDatabase.Builder.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

Données exportées et importées

Les fichiers que l'utilisateur importe depuis d'autres applications ou exporte depuis votre application doivent également être enregistrés dans le répertoire de documents. Sur iOS, l'import via UIDocumentPickerViewController place automatiquement une copie du fichier dans Documents lors de l'utilisation du paramètre asCopy : true. Sur Android, l'import via la boîte de dialogue SAF crée également une copie du fichier dans le sandbox de l'application. Lors de l'export de données (par exemple, la création d'un fichier CSV avec des contacts), enregistrez d'abord le fichier dans Documents/filesDir, puis proposez à l'utilisateur de le partager via Share Sheet. Cela garantit que même si l'utilisateur oublie d'enregistrer le fichier après l'envoi, une copie reste dans l'application pour une utilisation ultérieure.

Comment travailler avec le répertoire de documents sur Android

Sur Android, la fonction du répertoire de documents est assurée par context.filesDir. De plus, le répertoire context.externalFilesDir sur la carte SD est disponible, mais il ne garantit pas l'intégrité des données. Examinons les principales techniques pour travailler avec ces répertoires.

Accéder et gérer les fichiers via filesDir

filesDir est le répertoire principal pour les fichiers permanents de l'application sur Android. Il se trouve dans le sandbox de l'application et est complètement supprimé lors de la désinstallation. Pour obtenir une instance File, utilisez context.filesDir, qui renvoie le chemin vers /data/data/<package>/files/. Pour créer et lire des fichiers, utilisez les opérations Java/Kotlin File standard ou les méthodes Context openFileInput() et openFileOutput(), qui prennent un nom de fichier et retournent FileInputStream/FileOutputStream. La méthode openFileOutput() crée automatiquement le fichier dans filesDir s'il n'existe pas encore et permet de spécifier le mode d'accès : MODE_PRIVATE (application actuelle uniquement), MODE_APPEND (ajout) ou MODE_WORLD_READABLE (obsolète, non utilisé depuis API 24+).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

Fonctionnalités de stockage sur Android 10+

Sur Android 10+, le modèle Scoped Storage n'affecte pas filesDir — l'accès complet au propre sandbox de l'application reste possible. Toutes les opérations de lecture et d'écriture dans filesDir ne nécessitent pas d'autorisations supplémentaires. Cependant, si vous essayez d'accéder aux fichiers d'une autre application via filesDir, vous obtiendrez une exception. Pour partager des fichiers, utilisez FileProvider, qui crée un URI de contenu temporaire pour transférer un fichier vers une autre application. FileProvider est déclaré dans AndroidManifest.xml via la balise <provider> et configuré dans un fichier XML de chemins. Il s'agit du mécanisme standard pour transférer des fichiers entre applications, utilisé par exemple lors de l'envoi d'une image via Intent avec ACTION_SEND.

Comment travailler avec le répertoire de documents sur iOS

Sur iOS, le Documents Directory fait partie du conteneur Sandbox de l'application avec un statut particulier. Les fichiers de ce répertoire sont automatiquement inclus dans la sauvegarde iCloud, affichés dans l'application Fichiers et conservés lors des mises à jour de l'application via l'App Store.

Répertoire de documents et sauvegarde

La sauvegarde automatique de Documents est un avantage clé d'iOS. Lorsque l'utilisateur connecte l'appareil à iTunes ou active iCloud Backup, tous les fichiers de Documents/ sont copiés dans la sauvegarde. Lors de la restauration sur un nouvel appareil, l'utilisateur récupère tous ses fichiers sans actions supplémentaires. Cependant, cet avantage devient un inconvénient si l'application stocke de grandes quantités de données dans Documents : le temps de sauvegarde augmente et le stockage iCloud peut s'épuiser rapidement. Par conséquent, Documents ne doit stocker que les fichiers dont l'utilisateur a vraiment besoin lors de la restauration. Les fichiers temporaires, le cache et les données recréables doivent se trouver dans Caches ou Library/Application Support. Apple recommande d'exclure de la sauvegarde les fichiers qui peuvent être téléchargés à nouveau depuis Internet, via l'attribut isExcludedFromBackup.

let fm = FileManager.default
let docsURL = fm.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Contenu de la note"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive et synchronisation entre appareils

iCloud Drive permet de synchroniser les fichiers de Documents entre les appareils d'un même utilisateur. Pour activer la synchronisation, l'application doit utiliser les API NSDocument ou UIDocument, qui gèrent automatiquement le versionnage et la résolution de conflits. Une approche alternative consiste à utiliser iCloud avec CloudKit, qui offre un contrôle plus flexible sur la synchronisation mais nécessite une configuration sur CloudKit Dashboard. Lors de l'utilisation d'iCloud Drive, assurez-vous de gérer correctement les conflits d'édition (fusion ou last-write-wins) et d'informer l'utilisateur de l'état de la synchronisation via l'interface de l'application. iCloud ne garantit pas une synchronisation instantanée — le délai peut varier de quelques secondes à plusieurs minutes en fonction de la taille du fichier et de la qualité de la connexion. Pour les données critiques, utilisez l'écriture transactionnelle et le versionnage afin qu'en cas de conflit, la version précédente du fichier puisse être restaurée.

Différences avec le répertoire de cache et bonnes pratiques

Choisir correctement entre Documents Directory et Cache Directory détermine la fiabilité du stockage des données utilisateur. Une erreur de choix conduit soit à une perte de données (si les fichiers importants sont stockés dans le cache), soit à un débordement de la sauvegarde (si les fichiers temporaires sont stockés dans Documents).

Les bonnes pratiques pour l'utilisation du répertoire de documents incluent plusieurs règles clés. Premièrement, demandez toujours la confirmation de l'utilisateur avant de supprimer des fichiers de ce répertoire. Contrairement au cache, la suppression d'un document peut entraîner une perte irréversible de contenu utilisateur. Deuxièmement, implémentez le versionnage des fichiers : lors de l'écrasement d'un fichier existant, enregistrez la version précédente avec le suffixe _backup ou utilisez des mécanismes d'instantané. Troisièmement, fournissez à l'utilisateur une interface pour visualiser, renommer, supprimer et exporter les fichiers du répertoire de documents. Sur iOS, les fichiers de Documents sont automatiquement affichés dans Fichiers ; sur Android, vous devez implémenter votre propre gestionnaire de fichiers ou utiliser des bibliothèques tierces.

Accordez une attention particulière à la migration des données lors des mises à jour de l'application. Si la nouvelle version modifie la structure de stockage des fichiers (par exemple, déplace des données d'un sous-répertoire à un autre ou modifie le format de fichier), implémentez une migration unique au premier démarrage après la mise à jour. Stockez le numéro de version du schéma de données dans SharedPreferences et exécutez la migration s'ils ne correspondent pas. Ne supprimez pas les anciens fichiers avant la fin de la migration — en cas d'échec, l'utilisateur ne doit pas perdre de données. Si la migration implique une conversion de format (par exemple, le passage de JSON à SQLite), enregistrez les fichiers d'origine comme sauvegarde dans un répertoire séparé avec la date de migration. L'utilisateur doit pouvoir annuler les modifications via les réglages de l'application dans les 30 premiers jours suivant la mise à jour, comme recommandé par les Apple Human Interface Guidelines.