FileManager — co to jest, praca z systemem plików iOS

Co to jest FileManager

FileManager — klasa singletonowa z frameworka Foundation, zapewniająca ujednolicone API do interakcji z systemem plików na wszystkich platformach Apple. Jest dostępny przez FileManager.default lub przez utworzenie instancji z niestandardowym delegatem.

Główne możliwości klasy obejmują: sprawdzanie istnienia pliku (fileExists), tworzenie katalogów (createDirectory), kopiowanie i przenoszenie (copyItem, moveItem), usuwanie (removeItem), pobieranie atrybutów (attributesOfItem) i zawartości katalogów (contentsOfDirectory). FileManager jest ściśle powiązany z NSData, String i JSONEncoder/Decoder do serializacji danych.

FileManager jest thread-safe: Apple gwarantuje bezpieczeństwo wywoływania metod z różnych wątków. Jednak operacje na systemie plików mogą być wolne w przypadku dużych plików, dlatego Apple zaleca wykonywanie ich w kolejce tła (DispatchQueue.global) i wywoływanie metod FileManagerDelegate w celu informowania o postępie.

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

let fileURL = documentsURL.appendingPathComponent("data.plist")

if fileManager.fileExists(atPath: fileURL.path) {
    print("File exists at \(fileURL.path)")
}

Główne katalogi aplikacji iOS

Każda aplikacja iOS ma trzy główne katalogi dostępne przez FileManager w ramach Sandbox: Documents, Library i tmp. Każdy ma swoje przeznaczenie i zasady tworzenia kopii zapasowych, których przestrzeganie jest kluczowe dla przejścia recenzji w App Store.

Documents — dla danych użytkownika, które powinny być zachowywane między uruchomieniami i kopiowane do iCloud. Library — dla plików aplikacji: pamięci podręcznych (Caches), ustawień (Preferences), baz danych (Application Support). tmp — dla plików tymczasowych, które mogą zostać usunięte przez system w dowolnym momencie między uruchomieniami aplikacji.

Zasada Apple: jeśli plik można przywrócić z internetu lub odtworzyć — powinien być przechowywany w Caches (bez kopii zapasowej). Jeśli plik zawiera dane użytkownika — Documents (z kopią zapasową). Nieprawidłowe umieszczanie plików to jedna z częstych przyczyn odrzucenia aplikacji, ponieważ Apple sprawdza zgodność z wytycznymi Storage & iCloud Backup Guidelines.

Odczyt i zapis plików

FileManager sam nie udostępnia metod do odczytu zawartości plików — służą do tego NSData(contentsOf), String(contentsOf) lub metody FileHandle. FileManager odpowiada za zarządzanie plikami: sprawdzanie istnienia, przenoszenie, kopiowanie, usuwanie.

Do zapisu danych używana jest metoda createFile(atPath:contents:attributes:) lub wysokopoziomowe API — data.write(to:), JSONEncoder.encode i PropertyListEncoder. FileManager udostępnia również FileHandle do strumieniowego odczytu i zapisu dużych plików, który nie ładuje całego pliku do pamięci.

struct UserSettings: Codable {
    let username: String
    let isDarkMode: Bool
    let fontSize: Int
}

let settings = UserSettings(
    username: "developer",
    isDarkMode: true,
    fontSize: 16
)

// Zapisz JSON do Documents
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
let data = try encoder.encode(settings)
let url = documentsURL.appendingPathComponent("settings.json")
try data.write(to: url, options: .atomic)

// Odczytaj JSON
let loadedData = try Data(contentsOf: url)
let loadedSettings = try JSONDecoder()
    .decode(UserSettings.self, from: loadedData)

Podczas zapisu używaj options: .atomic — gwarantuje to, że plik nie zostanie uszkodzony w przypadku awarii zapisu: dane są najpierw zapisywane do pliku tymczasowego, a następnie atomowo przenoszone do docelowej ścieżki. Do odczytu dużych plików używaj FileHandle z .readingMode i czytaj dane porcjami, kontrolując zużycie pamięci.

Zarządzanie katalogami

FileManager udostępnia metody do pełnego zarządzania katalogami: createDirectory (tworzenie wszystkich pośrednich folderów przez withIntermediateDirectories), contentsOfDirectory (pobieranie listy plików), enumeratorAt (rekurencyjne przechodzenie) i subpathsOfDirectory (wszystkie ścieżki wewnątrz katalogu).

Metoda enumeratorAt zwraca DirectoryEnumerator, który umożliwia efektywne przeglądanie dużych katalogów bez ładowania całej zawartości do pamięci. Obsługuje filtrowanie przez skipDescendants i udostępnia atrybuty każdego elementu bez dodatkowego zapytania do systemu plików.

// Rekurencyjne przechodzenie katalogów
if let enumerator = fileManager.enumerator(
    at: documentsURL,
    includingPropertiesForKeys: [.fileSizeKey, .isDirectoryKey]
) {
    for case let fileURL as URL in enumerator {
        let attrs = try fileURL.resourceValues(
            for: [.fileSizeKey, .isDirectoryKey]
        )
        if attrs.isDirectory == false {
            let size = attrs.fileSize ?? 0
            print("File: \(fileURL.lastPathComponent), Size: \(size) bytes")
        }
    }
}

Do usuwania katalogu używaj removeItem(at:). Uwaga: usunięcie katalogu w iOS jest nieodwracalne — pliki nie trafiają do kosza, jak na macOS. Przed usunięciem upewnij się, że nie używasz już plików z tego katalogu, i wykonaj operację w wątku tła, ponieważ usunięcie dużej liczby plików może zablokować UI.

FileManager i iCloud

FileManager integruje się z iCloud Drive przez metodę URLForUbiquityContainerIdentifier, która zwraca URL katalogu iCloud dla aplikacji. Do działania wymaga włączenia iCloud capability w projekcie i dodania odpowiedniego entitlement.

Pliki iCloud są synchronizowane automatycznie, ale FileManager udostępnia metody do ręcznej kontroli: startDownloadingUbiquitousItem wymusza rozpoczęcie pobierania, evictUbiquitousItem usuwa lokalną kopię, a urlOfItem(at:) zwraca lokalny URL dla pliku iCloud. NSMetadataQuery jest używane do wyszukiwania plików w iCloud.

Krytyczne ograniczenie: iCloud Drive nie jest obsługiwany dla plików w katalogu Documents — tylko dla plików w ubiquityContainer. Nie próbuj synchronizować Documents przez iCloud; do tego celu używaj NSUbiquitousKeyValueStore dla małych ilości danych lub Core Data z CloudKit dla złożonych struktur.

Wydajność FileManager

Operacje na FileManager mogą być kosztowne, szczególnie na urządzeniach z wolną pamięcią flash. Główne zalecenia Apple obejmują wykonywanie wszystkich operacji plikowych w kolejkach tła, minimalizację liczby wywołań fileExistsAtPath i używanie buforowania wyników.

Metoda fileExists wykonuje wywołanie systemowe stat(), które jest stosunkowo wolne. Jeśli sprawdzasz istnienie pliku przed jego odczytem, lepiej od razu spróbować go odczytać i obsłużyć błąd — to wykonuje ten sam stat, ale eliminuje podwójne wywołanie systemowe. Do masowych sprawdzeń używaj enumeratorAt z resourceValues.

Do optymalizacji pracy z dużymi ilościami danych:

• Używaj FileHandle do strumieniowego przetwarzania dużych plików
• Buforuj wyniki fileManager.urls dla często używanych katalogów
• Wykonuj operacje wsadowe w kolejce ziarnistej, unikając blokowania main thread
• Używaj CoordinatedFileManager do bezpiecznego dostępu z wielu wątków

Apple Instruments udostępnia szablon File Activity do profilowania operacji plikowych. Używaj go do identyfikacji wąskich gardeł — na przykład częstych wywołań fileExists w pętli lub operacji zapisu na main thread. Najczęstsze problemy z wydajnością są związane z synchronicznym zapisem dużych plików podczas zwijania aplikacji.