UIDocumentPickerViewController — کار با اسناد در iOS

UIDocumentPickerViewController چیست؟

UIDocumentPickerViewController — یک کنترلر UIKit است که رابط سیستمی برای انتخاب اسناد فراهم می‌کند. این کنترلر بخشی از فریمورک UIKit است و از iOS 8 در دسترس می‌باشد. کنترلر یک مرورگر فایل را نمایش می‌دهد که شامل ذخیره‌ساز محلی، iCloud Drive و سرویس‌های ابری شخص ثالث ثبت شده است.

کنترلر به صورت ناهمزمان کار می‌کند: پس از فراخوانی present، کاربر دیالوگ سیستمی را می‌بیند، فایل را انتخاب می‌کند و نتیجه از طریق delegate بازگردانده می‌شود. برنامه برای دسترسی به فایل انتخاب شده نیاز به مجوز خاصی ندارد — پیکر سیستمی به طور خودکار دسترسی موقت به URI را فراهم می‌کند.

UIDocumentPickerViewController از iPad از طریق UIPopoverPresentationController و رابط تطبیقی برای iPhone پشتیبانی می‌کند. از iOS 14، کنترلر طراحی به‌روز شده و پشتیبانی از ناوبری sidebar در iPadOS دریافت کرده است.

حالت‌های کار: import و export

UIDocumentPickerViewController در دو حالت اصلی کار می‌کند که هر کدام مشخص می‌کند برنامه چگونه به فایل دسترسی پیدا می‌کند. حالت از طریق پارامتر forOpeningContentTypes یا forExporting بسته به وظیفه تنظیم می‌شود.

حالت Import (forOpeningContentTypes) فایل انتخاب شده را به sandbox برنامه کپی می‌کند. برنامه URL مربوط به کپی اختصاصی خود از فایل را دریافت می‌کند که فقط برای آن قابل دسترسی است. این یک حالت امن است: فایل برنامه دیگر تغییر نمی‌کند و کپی کاملاً توسط برنامه جاری کنترل می‌شود.

حالت Export (forExporting) بدون کپی کردن، URL فایل اصلی را فراهم می‌کند. برنامه می‌تواند فایل را از طریق لینک بخواند، اما تغییرات ذخیره نمی‌شوند. این حالت زمانی استفاده می‌شود که نیاز به ارسال فایل به برنامه دیگر یا ارسال آن از طریق ایمیل باشد. برای نوشتن تغییرات از حالت open با URL امنیتی محدوده‌دار (security-scoped) استفاده می‌شود.

تنظیم پیکر و فیلتر کردن بر اساس UTI

UTI (Uniform Type Identifier) — یک سیستم شناسایی انواع محتوا در اکوسیستم Apple است. UIDocumentPickerViewController فایل‌های نمایش داده شده را بر اساس آرایه UTI ارسال شده از طریق forOpeningContentTypes فیلتر می‌کند. اگر UTI مشخص نشود، پیکر همه انواع فایل را نشان می‌دهد.

• PDF — com.adobe.pdf. پیکر فقط اسناد PDF را نشان می‌دهد.
• تصاویر — public.image. شامل JPEG، PNG، HEIC و سایر فرمت‌ها.
• متن — public.plain-text. فایل‌های .txt، .csv و سایر فایل‌های متنی را نمایش می‌دهد.
• صدا — public.audio. شامل MP3، AAC، WAV و فرمت‌های Lossless.
• ویدئو — public.movie. MP4، MOV، AVI و سایر فرمت‌های ویدئویی را نشان می‌دهد.

برای انتخاب چند نوع، آرایه [UTType.pdf, UTType.image] ارسال می‌شود. از iOS 14، Apple استفاده از UTType را به جای ثابت‌های رشت‌ای توصیه می‌کند. UIDocumentPickerViewController هنگام تغییر ارائه‌دهنده انتخاب شده، لیست انواع نمایش داده شده را به طور خودکار به‌روز می‌کند.

نمونه کد: انتخاب سند در Swift

پیاده‌سازی UIDocumentPickerViewController در Swift حداقل است: یک نمونه از کنترلر با انواع UTI ایجاد کنید، delegate را تنظیم کنید و present را فراخوانی کنید. پس از انتخاب فایل، delegate یک آرایه از URLها را در متد didPickDocumentsAt دریافت می‌کند. هر URL یک لینک امنیتی محدوده‌دار (security-scoped) است که نیاز به فراخوانی startAccessingSecurityScopedResource دارد.

let picker = UIDocumentPickerViewController(
    forOpeningContentTypes: [.pdf, .image],
    asCopy: true
)
picker.delegate = self
picker.allowsMultipleSelection = false
present(picker, animated: true)

// MARK: - UIDocumentPickerDelegate
func documentPicker(
    _ controller: UIDocumentPickerViewController,
    didPickDocumentsAt urls: [URL]
) {
    guard let url = urls.first else { return }
    url.startAccessingSecurityScopedResource()
    defer { url.stopAccessingSecurityScopedResource() }
    // خواندن فایل از url
}

منابع security-scoped

URL امنیتی محدوده‌دار نیاز به فراخوانی startAccessingSecurityScopedResource قبل از خواندن دارد. این متد به سیستم اطلاع می‌دهد که برنامه به طور موقت به فایلی خارج از sandbox دسترسی پیدا می‌کند. پس از اتمام کار حتماً stopAccessingSecurityScopedResource را فراخوانی کنید، در غیر این صورت سیستم ممکن است دسترسی را مسدود کند.

UIDocumentPickerDelegate و مدیریت نتایج

UIDocumentPickerDelegate نتایج انتخاب فایل را از طریق دو متد دریافت می‌کند: didPickDocumentsAt در صورت موفقیت و didPickDocumentsAt در صورت لغو. iOS به طور خودکار متد لغو را فراخوانی می‌کند اگر کاربر پیکر را بدون انتخاب ببندد.

مدیریت خطا شامل بررسی در دسترس بودن URL است. اگر کاربر فایلی را از iCloud Drive انتخاب کرده باشد اما دستگاه آفلاین باشد، URL ممکن است در دسترس نباشد. توصیه می‌شود قبل از خواندن FileManager.default.isReadableFile را بررسی کرده و پیام خطای قابل فهمی به کاربر نشان دهید.

برای iOS 14+ متد جدید documentPicker:didPickDocumentsAt با آرایه‌ای از URLها در دسترس است. متد قدیمی didPickDocumentAt (تکی) منسوخ شده است. همیشه آرایه را مدیریت کنید، حتی اگر allowsMultipleSelection غیرفعال باشد — Apple استفاده از یک handler یکپارچه را توصیه می‌کند.

UIDocumentPickerViewController در iPad

iPad نیاز به پیکربندی ویژه UIDocumentPickerViewController دارد. در iPad، پیکر به صورت popover نمایش داده می‌شود و برای موقعیت‌یابی صحیح نیاز به تعیین sourceView دارد. بدون sourceView، کنترلر ممکن است در iPadOS با exception از کار بیفتد.

برای popover از ویژگی popoverPresentationController استفاده می‌شود. sourceView و sourceRect را برای اتصال به دکمه یا سلول جدول مشخص کنید. در iPhone این کد تأثیری ندارد — iOS به طور خودکار پیکر را در تمام صفحه نمایش می‌دهد. از iPadOS 16، کنترلر از sidebar و split view برای ناوبری بهبود یافته پشتیبانی می‌کند.

طراحی تطبیقی UIDocumentPickerViewController به طور خودکار بین full-screen (iPhone) و popover (iPad) جابجا می‌شود. توسعه‌دهنده نیازی به پیاده‌سازی کنترلرهای جداگانه برای دستگاه‌های مختلف ندارد — کافی است popoverPresentationController را برای iPad به درستی پیکربندی کند.