File Provider Extension: این چیست و چگونه فراه‌کننده فایل iOS کار می‌کند

File Provider Extension چیست در iOS

File Provider Extension — این یک افزونه برنامه است که منابع جدیدی از اسناد را به برنامه فایل‌ها اضافه می‌کند. یک خدمت ابری — Google Drive، Dropbox، OneDrive یا یک ذخیره سازمانی — می‌تواند ساختار فایلی خود را مستقیماً در رابط سیستمی، بدون باز کردن یک برنامه جداگانه، نمایش دهد.

کاربر با فایل‌های دورامد دقیقاً مانند فایل‌های ذخیره‌شده در دستگاه کار می‌کند: محتوای پوشه‌ها را مرور می‌کند، اسناد را کشیده و رها می‌کند، آن‌ها را در هر برنامه مناسبی باز می‌کند و تغییرات را به ابر برمی‌گرداند. به گزارش WWDC 2025، File Provider Extension از تا 1000 عملیات همگام‌سازی همزمان پشتیبانی کرده و از طریق مدیریت پویای اولویت‌ها خود را با سرعت شبکه سازگار می‌کند.

افزونه در پشزمینه کار می‌کند — iOS آن را در زمان نیاز به همگام‌سازی راه‌اندازی کرده و در صورت کمبود منابع می‌تواند آن را به زور پایان دهد. همه عملیات باید idempotent بوده و از نقطه بازرسی ادامه را پشتیبانی کنند.

معماری و مکانیزم همگام‌سازی فایل

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)")
    }
}