File Provider Extension: що це таке та як працює файловий провайдер iOS

Що таке File Provider Extension в iOS

File Provider Extension — це розширення додатку, яке додає в додаток Файли нові джерела документів. Хмарний сервіс — Google Drive, Dropbox, OneDrive або корпоративне сховище — може відображати свою файлову структуру прямо в системному інтерфейсі, без відкриття окремого додатку.

Користувач працює з віддаленими файлами так само, як із збереженими на пристрої: переглядає вміст папок, перетягує документи, відкриває їх у будь-яких сумісних додатках і зберігає зміни назад у хмару. За даними WWDC 2025, File Provider Extension підтримує до 1000 одночасних операцій синхронізації та адаптується до швидкості мережі через динамічне управління пріоритетами.

Розширення працює у фоновому режимі — iOS запускає його при необхідності синхронізації та може примусово завершити при нестачі ресурсів. Всі операції повинні бути ідемпотентними та підтримувати відновлення з контрольної точки.

Архітектура та механізм синхронізації файлів

File Provider Extension має трирівневу архітектуру: системний процес Files.app, розширення-провайдер і віддалений сервер. Система запитує дані у розширення, розширення перетворює запити у виклики API хмарного сервісу та повертає результати через NSFileProviderItem.

Інкрементальна синхронізація

Замість завантаження повної файлової структури при кожному оновленні розширення передає лише змінені елементи. NSFileProviderManager надає методи для відправки інкрементальних оновлень — «додано файл A», «змінено файл B», «видалено папку C». Це радикально знижує трафік і прискорює відображення змін.

За даними Apple Engineering, інкрементальна синхронізація скорочує обсяг переданих даних на 60–80% порівняно з повним перезавантаженням. Рекомендується використовувати NSFileProviderSyncAnchor для позначки стану синхронізації та мінімізації дублюючих запитів.

Кешування на пристрої

File Provider Extension може кешувати файли локально для офлайн-доступу. При відкритті файлу система робить запит до розширення, розширення вирішує — завантажити вміст із сервера чи повернути вже закешовану версію. NSFileProviderItem вказує рівень кешування через поля isDownloaded та isUploaded.

Apple рекомендує налаштовувати політику кешування залежно від розміру файлів: для зображень і документів — повне кешування, для відео — лише прев'ю, для архівів — на запит користувача.

NSFileProviderManager: управління файловим провайдером

NSFileProviderManager — центральний клас, через який розширення взаємодіє з системою. Він надає методи для сповіщення системи про зміни, створення нових елементів, управління завантаженнями та обробки помилок. Кожен екземпляр NSFileProviderManager прив'язаний до конкретного домену.

Ключові методи

signalEnumerator(for:) — сповіщає систему, що вміст папки змінився і потрібно перечитати список. reimportItem(_:) — повторно імпортує вказаний елемент після зміни на сервері. registerURLSessionTask:forItemWithIdentifier: — пов'язує фонове завантаження з конкретним файлом для відстеження прогресу.

Важливе обмеження: NSFileProviderManager працює тільки в процесі розширення. Основний додаток не може безпосередньо викликати його методи для управління файловою структурою — синхронізація повинна ініціюватися розширенням або системою.

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

Управління завантаженнями

Для завантаження файлів у фоновому режимі NSFileProviderManager використовує URLSession з фоновою конфігурацією. Розширення створює задачу завантаження та реєструє її в менеджері, який прив'язує її до відповідного елемента. Система автоматично відстежує прогрес і пріоритети завантажень залежно від активності користувача.

Реалізація File Provider Extension

Створення File Provider Extension починається з додавання нового target в Xcode з шаблоном File Provider Extension. Xcode автоматично генерує клас, що наслідує від NSFileProviderExtension, і мінімальний набір методів для роботи з елементами.

NSFileProviderItem та метадані

Кожен елемент файлової структури — файл або папка — реалізує протокол NSFileProviderItem. Протокол визначає обов'язкові поля: itemIdentifier, parentItemIdentifier, filename, typeIdentifier та capabilities. Додатково можна вказати розмір, дату модифікації та прапорці завантаження.

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

Обробка запитів перерахування

Метод enumerator(for:) повертає об'єкт, що реалізує NSFileProviderEnumerator, який надає вміст папки на запит системи. iOS може запитувати перерахування для кореневої папки, для підпапок і для робочого набору — останній використовується для відображення нещодавніх або вибраних файлів.

Apple рекомендує використовувати асинхронні методи перерахування з пагінацією через NSFileProviderPage, щоб не завантажувати тисячі елементів одночасно. Сторінки по 50–100 елементів оптимальні для продуктивності.

Домени та мультиакаунтна архітектура

NSFileProviderDomain — механізм розділення різних облікових записів в межах одного розширення. Якщо користувач авторизував у додатку кілька акаунтів — особистий та корпоративний Google Drive — кожен акаунт створює окремий домен, який відображається як окреме джерело в додатку Файли.

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

За даними Apple, рекомендується не створювати більше 10 доменів на одне розширення — надмірна кількість уповільнює запуск додатку Файли та збільшує споживання пам'яті. Для сервісів з великою кількістю акаунтів варто агрегувати їх в один домен з перемиканням профілів всередині розширення.

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