Директорія документів у мобільному застосунку — що це, призначення та як організувати зберігання

Що таке директорія документів застосунку?

Директорія документів — це спеціалізоване сховище всередині пісочниці застосунку, призначене для постійного зберігання файлів користувача. На відміну від кешу, файли в цій директорії вважаються важливими для користувача: вони не видаляються системою при нестачі місця, зберігаються під час оновлення застосунку та резервуються при синхронізації пристрою. На iOS директорія Documents є частиною Sandbox-контейнера і автоматично включається в резервне копіювання iCloud. На Android прямого аналога немає — еквівалентом слугує context.filesDir, який також призначений для постійних файлів, але не має вбудованого механізму резервного копіювання.

Різниця між директорією документів і внутрішнім сховищем (Internal Storage) на Android мінімальна: обидва розташовані в пісочниці застосунку, обидва видаляються при деінсталяції, обидва недоступні іншим застосункам. Основна відмінність — семантична: Documents Directory передбачає, що файли створені або імпортовані користувачем, тоді як Internal Storage може містити внутрішні файли застосунку (бази даних, конфігурації). На iOS різниця більш суттєва: Documents автоматично резервується, а Library/Application Support — ні. Це впливає на стратегію зберігання: у Documents розміщуйте лише те, що користувач хоче відновити на новому пристрої, а в Application Support — внутрішні дані, які застосунок може відтворити.

Архітектура пісочниці гарантує, що інші застосунки не мають доступу до директорії документів вашого застосунку. На iOS доступ до Documents інших застосунків неможливий без jailbreak. На Android root-доступ дозволяє читати filesDir будь-якого застосунку, тому конфіденційні дані (токени, ключі шифрування) необхідно додатково захищати за допомогою EncryptedSharedPreferences або EncryptedFile з бібліотеки AndroidX Security.

Які дані зберігають у директорії документів

У директорію документів слід розміщувати дані, які становлять цінність для користувача та мають бути доступні після перезапуску застосунку або відновлення пристрою. Не всі файли підходять для зберігання в цій директорії — вибір залежить від типу даних і сценарію використання.

Користувацькі документи та файли

Користувацькі файли — основний вміст директорії документів. Це можуть бути текстові документи, створені в редакторі, зображення, зняті камерою застосунку, експортовані PDF-звіти, аудіозаписи, нотатки. Кожен такий файл створено користувачем або на його запит і має бути доступний у будь-який момент. На iOS файли з Documents відображаються в системному застосунку Files, що дозволяє користувачеві керувати ними через стандартний файловий менеджер. На Android аналогічного відображення немає — застосунок самостійно має надати інтерфейс для перегляду збережених файлів.

Бази даних та налаштування застосунку

Бази даних SQLite та файли налаштувань зазвичай зберігаються поруч із директорією документів, але не в ній самій. На iOS бази даних розміщують у Library/Application Support, оскільки вони не повинні відображатися в застосунку Files і резервуватися окремо. На Android бази даних за замовчуванням створюються в /data/data/<package>/databases/ через Room або SQLiteOpenHelper. Якщо база даних містить користувацький вміст (нотатки, щоденник, фінансові записи), можна розмістити її в filesDir, щоб забезпечити резервування через систему. Room дозволяє вказати кастомну директорію для зберігання бази даних через callback RoomDatabase.Builder.

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

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

Експортовані та імпортовані дані

Файли, які користувач імпортує з інших застосунків або експортує з вашого застосунку, також мають зберігатися в директорії документів. На iOS імпорт через UIDocumentPickerViewController автоматично розміщує копію файлу в Documents при використанні параметра asCopy: true. На Android імпорт через SAF-діалог також створює копію файлу в пісочниці застосунку. При експорті даних (наприклад, створення CSV-файлу з контактами) зберігайте файл спочатку в Documents/filesDir, а потім пропонуйте користувачеві поділитися ним через Share Sheet. Це гарантує, що навіть якщо користувач забуде зберегти файл після надсилання, копія залишиться в застосунку для подальшого використання.

Як працювати з директорією документів на Android

На Android функції директорії документів виконує context.filesDir. Додатково доступна директорія context.externalFilesDir на SD-картці, але вона не гарантує збереження даних. Розглянемо основні прийоми роботи з цими директоріями.

Доступ та керування файлами через filesDir

filesDir — основна директорія для постійних файлів застосунку на Android. Вона знаходиться в пісочниці застосунку та повністю видаляється при деінсталяції. Для отримання екземпляра File використовуйте context.filesDir, який повертає шлях до каталогу /data/data/<package>/files/. Для створення та читання файлів використовуйте стандартні Java/Kotlin File-операції або Context-методи openFileInput() та openFileOutput(), які приймають ім'я файлу та повертають FileInputStream/FileOutputStream. Метод openFileOutput() автоматично створює файл у filesDir, якщо він ще не існує, і дозволяє вказати режим доступу: MODE_PRIVATE (тільки поточний застосунок), MODE_APPEND (дозапис) або MODE_WORLD_READABLE (застарілий, не використовується з 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()
}

Особливості зберігання на Android 10+

На Android 10+ модель Scoped Storage не впливає на filesDir — доступ до власної пісочниці застосунку залишається повним. Усі операції читання та запису всередині filesDir не потребують додаткових дозволів. Однак при спробі доступу до файлів іншого застосунку через filesDir ви отримаєте виняток. Для обміну файлами використовуйте FileProvider, який створює тимчасовий content URI для передачі файлу іншому застосунку. FileProvider оголошується в AndroidManifest.xml через тег <provider> та конфігурується в XML-файлі шляхів. Це стандартний механізм для передачі файлів між застосунками, що використовується, наприклад, при надсиланні зображення через Intent з ACTION_SEND.

Як працювати з директорією документів на iOS

На iOS Documents Directory — це частина Sandbox-контейнера застосунку з особливим статусом. Файли з цієї директорії автоматично включаються в резервне копіювання iCloud, відображаються в застосунку Files та зберігаються під час оновлення застосунку через App Store.

Директорія документів та резервне копіювання

Автоматичне резервування Documents — ключова перевага iOS. Коли користувач підключає пристрій до iTunes або вмикає iCloud Backup, усі файли з Documents/ копіюються в резервну копію. При відновленні на новому пристрої користувач отримує всі свої файли без додаткових дій. Однак ця перевага стає недоліком, якщо застосунок зберігає в Documents великі обсяги даних: час резервного копіювання збільшується, а обсяг iCloud-сховища може швидко закінчитися. Тому в Documents слід зберігати лише ті файли, які дійсно потрібні користувачеві при відновленні. Тимчасові файли, кеш та відтворювані дані мають знаходитися в Caches або Library/Application Support. Apple рекомендує виключати з резервного копіювання файли, які можна повторно завантажити з інтернету, через атрибут isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Вміст нотатки"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive та синхронізація між пристроями

iCloud Drive дозволяє синхронізувати файли з Documents між пристроями одного користувача. Для включення синхронізації застосунок має використовувати API NSDocument або UIDocument, які автоматично керують версіонуванням та вирішенням конфліктів. Альтернативний підхід — використання iCloud за допомогою CloudKit, який надає більш гнучкий контроль над синхронізацією, але вимагає налаштування на CloudKit Dashboard. При використанні iCloud Drive переконайтеся, що ви коректно обробляєте конфлікти редагування (merge або last-write-wins) та інформуєте користувача про стан синхронізації через інтерфейс застосунку. iCloud не гарантує миттєву синхронізацію — затримка може становити від кількох секунд до кількох хвилин залежно від розміру файлу та якості з'єднання. Для критично важливих даних використовуйте транзакційний запис та версіонування, щоб при конфлікті можна було відновити попередню версію файлу.

Відмінності від Cache Directory та найкращі практики

Правильний вибір між Documents Directory та Cache Directory визначає надійність зберігання даних користувача. Помилка у виборі призводить або до втрати даних (якщо важливі файли зберігаються в кеші), або до переповнення резервної копії (якщо тимчасові файли зберігаються в Documents).

Найкращі практики використання директорії документів включають кілька ключових правил. По-перше, завжди запитуйте підтвердження користувача перед видаленням файлів із цієї директорії. На відміну від кешу, видалення документа може призвести до безповоротної втрати користувацького вмісту. По-друге, реалізуйте версіонування файлів: при перезаписуванні існуючого файлу зберігайте попередню версію з суфіксом _backup або використовуйте Snapshot-механізми. По-третє, надайте користувачеві інтерфейс для перегляду, перейменування, видалення та експорту файлів із директорії документів. На iOS файли з Documents автоматично відображаються в Files, на Android необхідно реалізувати власний файловий менеджер або використовувати сторонні бібліотеки.

Окрему увагу приділіть міграції даних при оновленні застосунку. Якщо нова версія змінює структуру зберігання файлів (наприклад, переносить дані з однієї піддиректорії в іншу або змінює формат файлів), реалізуйте одноразову міграцію при першому запуску після оновлення. Зберігайте номер версії схеми даних у SharedPreferences і при неспівпадінні запускайте міграцію. Не видаляйте старі файли до завершення міграції — у разі збою користувач не повинен втратити дані. Якщо міграція включає перетворення формату (наприклад, перехід з JSON на SQLite), зберігайте вихідні файли як резервну копію в окремій директорії з датою міграції. Користувач має мати можливість відкотити зміни через налаштування застосунку протягом перших 30 днів після оновлення, як рекомендує Apple Human Interface Guidelines.