Documents Directory: co to jest, przeznaczenie i dostęp do plików

Czym jest Documents Directory w iOS?

Documents Directory „ to katalog wewnątrz piaskownicy aplikacji iOS przeznaczony do przechowywania danych użytkownika, które powinny być zachowywane między uruchomieniami i dostępne dla użytkownika. Każda aplikacja otrzymuje własną izolowaną piaskownicę, a Documents jest jednym z kluczowych katalogów obok Caches, tmp i Library.

iOS używa ścisłej piaskownicy (sandbox): aplikacja nie ma dostępu do systemu plików innych aplikacji ani do katalogów systemowych bez specjalnych uprawnień. Documents Directory „ jedyny katalog, którego zawartość użytkownik może przeglądać przez iTunes File Sharing (po włączeniu odpowiedniego klucza UIFileSharingEnabled w Info.plist).

Według danych Apple WWDC 2023 ponad 85% aplikacji w App Store używa Documents Directory do przechowywania co najmniej jednego typu danych użytkownika „ od wyeksportowanych PDF po zapisane pliki gier i wyeksportowane obrazy.

Programista musi zrozumieć: pliki w Documents są automatycznie uwzględniane w kopii zapasowej iCloud i iTunes. Jeśli aplikacja przechowuje w Documents duże ilości danych, które można przywrócić (na przykład pamięć podręczną obrazów lub pliki tymczasowe), doprowadzi to do nieuzasadnionego zużycia miejsca w magazynie iCloud użytkownika.

Jak uzyskać ścieżkę do Documents Directory

W Swift ścieżkę do Documents Directory uzyskuje się przez FileManager. Apple zaleca używanie API opartego na URL zamiast string-based dla lepszej zgodności z nowoczesnymi możliwościami iOS.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Utwórz plik w Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C używa NSSearchPathForDirectoriesInDomains „ starszego, ale wciąż obsługiwane podejścia, które zwraca ścieżkę jako ciąg znaków zamiast URL.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

Nowoczesne projekty w Swift powinny używać FileManager.urls, ponieważ ta metoda zwraca URL, a nie ciąg znaków, co zmniejsza ryzyko błędów z kodowaniem ścieżek i czyni kod bardziej bezpiecznym typowo.

Jakie dane przechowywać w Documents

Documents Directory jest przeznaczona dla danych utworzonych przez użytkownika lub potrzebnych użytkownikowi w jawnej formie. Apple wyróżnia kilka kategorii, które warto umieszczać w tym katalogu.

Dokumenty i pliki użytkownika

Pliki, które użytkownik tworzy lub importuje „ dokumenty tekstowe, PDF, obrazy, wyeksportowane raporty, pliki kopii zapasowych. Te dane mają bezpośrednią wartość dla użytkownika, a ich utrata byłaby krytyczna.

Zapisane stany gier i stan aplikacji

Sejwy gier, pliki stanu aplikacji, wyeksportowane projekty „ wszystko, co użytkownik oczekuje przywrócić po ponownej instalacji aplikacji. Jednak w przypadku krytycznych danych zaleca się dodatkowo używać iCloud Key-Value Storage lub Core Data z synchronizacją iCloud.

Kluczowe kryterium: jeśli dane mogą zostać przywrócone z sieci lub ponownie utworzone „ ich miejsce jest w Caches, a nie w Documents. Każdy gigabajt w Documents to gigabajt w kopii zapasowej iCloud użytkownika.

Kopia zapasowa i synchronizacja

iOS automatycznie uwzględnia zawartość Documents Directory w kopii zapasowej podczas podłączenia urządzenia do iTunes lub synchronizacji z iCloud. Tego zachowania nie można wyłączyć na poziomie katalogu „ tylko dla poszczególnych plików przez atrybut NSURLIsExcludedFromBackupKey.

Począwszy od iOS 5.0 Apple zaczęło odrzucać aplikacje, które przechowują w Documents duże ilości danych podlegających przywróceniu. Zalecenie Apple: pliki, które można ponownie pobrać, powinny być przechowywane w Caches Directory z flagą wyłączenia z kopii zapasowej.

import Foundation

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

// Wyłącz plik z kopii zapasowej iCloud
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

Synchronizacja iCloud działa przez NSUbiquitousContainer, jeśli aplikacja używa iCloud Documents. W takim przypadku pliki z Documents Directory są automatycznie synchronizowane między urządzeniami użytkownika. Dla aplikacji bez iCloud synchronizacja jest ograniczona do kopii zapasowej.

Documents Directory vs Caches Directory

Różnica między Documents a Caches „ jedno z najczęstszych nieporozumień wśród początkujących programistów iOS. Główna różnica: system może w każdej chwili usunąć pliki z Caches, aby zwolnić miejsce, ale nigdy nie rusza Documents bez wiedzy użytkownika.

Według Apple Developer Documentation (2024) nieprawidłowe używanie Documents Directory „ jedna z częstych przyczyn odrzucenia aplikacji podczas recenzji: jeśli aplikacja przechowuje w Documents więcej niż kilka megabajtów danych, które można przywrócić, Apple zaleca przeniesienie ich do Caches lub zastosowanie NSURLIsExcludedFromBackupKey.

Praktyczna zasada: jeśli użytkownik będzie zmartwiony utratą pliku „ przechowuj w Documents. Jeśli plik można ponownie pobrać lub wygenerować „ przechowuj w Caches.

Najlepsze praktyki pracy z Documents

Doświadczeni programiści iOS wypracowali kilka zasad, które pomagają uniknąć problemów z Documents Directory na wszystkich etapach cyklu życia aplikacji „ od rozwoju do publikacji w App Store.

Monitorowanie rozmiaru katalogu

Regularnie sprawdzaj rozmiar Documents Directory przez FileManager.enumerator(at:includingPropertiesForKeys:). Jeśli rozmiar przekracza 100 MB dla danych niebędących danymi użytkownika „ to powód do przemyślenia architektury przechowywania.

Wyłączanie przywracalnych plików z kopii zapasowej

Dla wszystkich plików, które można ponownie pobrać z sieci, ustaw isExcludedFromBackup = true. Zmniejsza to obciążenie magazynu iCloud użytkownika i zmniejsza ryzyko odrzucenia aplikacji przez App Review.

Migracja przy aktualizacji

Przy zmianie formatu danych w Documents przewidz migrację: nie usuwaj starych plików, dopóki nie upewnisz się, że nowe zostały poprawnie utworzone. Używaj podkatalogów specyficznych dla wersji.

import Foundation

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

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Przestrzeganie tych praktyk zmniejsza ryzyko utraty danych użytkownika, redukuje rozmiar kopii zapasowej iCloud i ułatwia przejście recenzji w App Store.