File Provider Extension: co to jest i jak działa dostawca plików iOS

Co to jest File Provider Extension w iOS

File Provider Extension to rozszerzenie aplikacji, które dodaje do aplikacji Pliki nowe źródła dokumentów. Usługa w chmurze — Google Drive, Dropbox, OneDrive lub firmowe repozytorium — może wyświetlać swoją strukturę plików bezpośrednio w systemowym interfejsie, bez otwierania osobnej aplikacji.

Użytkownik pracuje z zdalnymi plikami dokładnie tak samo, jak z zapisanymi na urządzeniu: przegląda zawartość folderów, przeciąga dokumenty, otwiera je w dowolnych kompatybilnych aplikacjach i zapisuje zmiany z powrotem w chmurze. Według WWDC 2025, File Provider Extension obsługuje do 1000 jednoczesnych operacji synchronizacji i dostosowuje się do prędkości sieci poprzez dynamiczne zarządzanie priorytetami.

Rozszerzenie działa w tle — iOS uruchamia je w razie potrzeby synchronizacji i może je wymusić zakończyć przy braku zasobów. Wszystkie operacje muszą być idempotentne i obsługiwać wznawianie od punktu kontrolnego.

Architektura i mechanizm synchronizacji plików

File Provider Extension ma trójpoziomową architekturę: proces systemowy Files.app, rozszerzenie-dostawcę i zdalny serwer. System żąda danych od rozszerzenia, rozszerzenie przekształca zapytania w wywołania API usługi w chmurze i zwraca wyniki przez NSFileProviderItem.

Synchronizacja przyrostowa

Zamiast ładowania pełnej struktury plików przy każdej aktualizacji, rozszerzenie przesyła tylko zmienione elementy. NSFileProviderManager dostarcza metody do wysyłania przyrostowych aktualizacji — „dodano plik A“, „zmieniono plik B“, „usunięto folder C“. To radykalnie zmniejsza ruch i przyspiesza wyświetlanie zmian.

Według Apple Engineering, synchronizacja przyrostowa zmniejsza objętość przesyłanych danych o 60–80% w porównaniu z pełnym przeładowaniem. Zaleca się używanie NSFileProviderSyncAnchor do oznaczania stanu synchronizacji i minimalizowania duplikujących się zapytań.

Cache na urządzeniu

File Provider Extension może cache’ować pliki lokalnie do dostępu offline. Przy otwieraniu pliku system wysyła zapytanie do rozszerzenia, rozszerzenie decyduje — pobrać zawartość z serwera czy zwrócić już zcache’owaną wersję. NSFileProviderItem wskazuje poziom cache’owania przez pola isDownloaded i isUploaded.

Apple zaleca konfigurowanie polityki cache’owania w zależności od rozmiaru plików: dla obrazów i dokumentów — pełne cache’owanie, dla wideo — tylko podgląd, dla archiwów — na żądanie użytkownika.

NSFileProviderManager: zarządzanie dostawcą plików

NSFileProviderManager to centralna klasa, przez którą rozszerzenie komunikuje się z systemem. Udostępnia metody do powiadamiania systemu o zmianach, tworzenia nowych elementów, zarządzania pobieraniem i obsługi błędów. Każda instancja NSFileProviderManager jest powiązana z konkretną domeną.

Kluczowe metody

signalEnumerator(for:) — powiadamia system, że zawartość folderu się zmieniła i należy ponownie odczytać listę. reimportItem(_:) — ponownie importuje wskazany element po zmianie na serwerze. registerURLSessionTask:forItemWithIdentifier: — wiąże pobieranie w tle z konkretnym plikiem w celu śledzenia postępu.

Ważne ograniczenie: NSFileProviderManager działa tylko w procesie rozszerzenia. Główna aplikacja nie może bezpośrednio wywoływać jego metod do zarządzania strukturą plików — synchronizacja musi być inicjowana przez rozszerzenie lub system.

let manager = NSFileProviderManager.default()
manager.signalEnumerator(for: workingSet) { error in
    if let error = error {
        print("Signal failed: \(error)")
    }
}

Zarządzanie pobieraniem

Do pobierania plików w tle NSFileProviderManager używa URLSession z konfiguracją w tle. Rozszerzenie tworzy zadanie pobierania i rejestruje je w menedżerze, który wiąże je z odpowiednim elementem. System automatycznie śledzi postęp i priorytety pobierania w zależności od aktywności użytkownika.

Implementacja File Provider Extension

Tworzenie File Provider Extension rozpoczyna się od dodania nowego targetu w Xcode z szablonem File Provider Extension. Xcode automatycznie generuje klasę dziedziczącą po NSFileProviderExtension oraz minimalny zestaw metod do pracy z elementami.

NSFileProviderItem i metadane

Każdy element struktury plików — plik lub folder — implementuje protokół NSFileProviderItem. Protokół określa obowiązkowe pola: itemIdentifier, parentItemIdentifier, filename, typeIdentifier i capabilities. Opcjonalnie można podać rozmiar, datę modyfikacji i flagi pobierania.

struct CloudItem: NSFileProviderItem {
    let itemIdentifier: NSFileProviderItemIdentifier
    let parentItemIdentifier: NSFileProviderItemIdentifier
    let filename: String
    let typeIdentifier: String
    let capabilities: NSFileProviderItemCapabilities
    let documentSize: NSNumber?
}

Obsługa zapytań o wyliczenie

Metoda enumerator(for:) zwraca obiekt implementujący NSFileProviderEnumerator, który dostarcza zawartość folderu na żądanie systemu. iOS może żądać wyliczenia dla folderu głównego, podfolderów i zestawu roboczego — ten ostatni służy do wyświetlania ostatnich lub ulubionych plików.

Apple zaleca używanie asynchronicznych metod wyliczania z paginacją przez NSFileProviderPage, aby nie ładować tysięcy elementów jednocześnie. Strony po 50–100 elementów są optymalne dla wydajności.

Domeny i architektura wielokontowa

NSFileProviderDomain — mechanizm rozdzielania różnych kont w obrębie jednego rozszerzenia. Jeśli użytkownik autoryzował w aplikacji kilka kont — osobiste i firmowe Google Drive — każde konto tworzy osobną domenę, która wyświetla się jako osobne źródło w aplikacji Pliki.

Każda domena ma unikalny identyfikator, nazwę wyświetlaną i stan. Użytkownik może tymczasowo wyłączać domeny lub usuwać je bez wpływu na inne konta. System uruchamia osobny proces rozszerzenia dla każdej aktywnej domeny, co zapewnia izolację danych między kontami.

Według Apple, zaleca się nie tworzyć więcej niż 10 domen na jedno rozszerzenie — nadmierna liczba spowalnia uruchamianie aplikacji Pliki i zwiększa zużycie pamięci. Dla usług z dużą liczbą kont warto agregować je w jedną domenę z przełączaniem profili w obrębie rozszerzenia.

let domain = NSFileProviderDomain(
    identifier: "work",
    displayName: "Corporate Drive"
)
NSFileProviderManager.add(domain) { error in
    if let error = error {
        print("Failed to add domain: \(error)")
    }
}