UIDocumentInteractionController — چیست، Open In و اسناد

UIDocumentInteractionController چیست؟

UIDocumentInteractionController — یک کلاس UIKit است که رابط سیستمی برای کار با اسناد ارائه می‌دهد. بر خلاف UIDocumentPickerViewController که فایل‌ها را انتخاب می‌کند، این کنترل‌کننده با فایل موجود برنامه کار می‌کند و به کاربر اقداماتی را پیشنهاد می‌دهد: پیش‌نمایش، باز کردن در برنامه دیگر، چاپ یا ارسال.

این کنترل‌کننده ViewController نیست — از طریق present فراخوانی نمی‌شود. در عوض، منوی سیستم را از طریق متد presentOptionsMenu یا presentPreview نمایش می‌دهد. منو تمام برنامه‌هایی را که برای پردازش این نوع فایل ثبت شده‌اند نشان می‌دهد.

UIDocumentInteractionController از iOS 2.0 در دسترس است و یکی از قدیمی‌ترین API‌ها برای کار با اسناد است. با وجود قدمت، برای پیاده‌سازی عملکرد Open In و پیش‌نمایش داخلی بدون استفاده از کتابخانه‌های شخص ثالث همچنان مناسب است.

حالت Preview: نمایش داخلی اسناد

Preview — نمایش‌دهنده داخلی اسناد است که توسط UIDocumentInteractionController ارائه می‌شود. از PDF، تصاویر، فایل‌های متنی و اسناد اداری (شامل .doc، .xls، .ppt) پشتیبانی می‌کند. Preview با انیمیشن انتقال مشابه Quick Look استاندارد نمایش داده می‌شود.

برای راه‌اندازی Preview، متد presentPreview را فراخوانی کنید. کنترل‌کننده به یک delegate با پیاده‌سازی متد previewControllerForDocumentInteractionController نیاز دارد که UIViewController را برای نمایش سند برمی‌گرداند. معمولاً self یا کنترل‌کننده ناوبری برگردانده می‌شود.

Preview داخلی نیازی به فریمورک‌ها یا مجوزهای اضافی ندارد. با هر فایلی که URL آن به ویژگی url منتقل شده است کار می‌کند. کاربر می‌تواند صفحات PDF را ورق بزند، تصاویر را بزرگ‌نمایی کند و متن را از اسناد کپی کند.

حالت Open In: انتقال فایل بین برنامه‌ها

Open In — عملکرد کلیدی UIDocumentInteractionController است. لیست برنامه‌هایی را که می‌توانند این نوع فایل را باز کنند نمایش می‌دهد. کاربر برنامه مقصد را انتخاب می‌کند و iOS فایل را به sandbox آن کپی کرده و برنامه را برای کار با سند راه‌اندازی می‌کند.

لیست برنامه‌ها به طور خودکار بر اساس Document Type ثبت شده در Info.plist سایر برنامه‌ها تشکیل می‌شود. اگر برنامه‌ای پشتیبانی از PDF را ثبت کرده باشد، در منوی Open In برای فایل‌های PDF ظاهر خواهد شد. سیستم همچنین اقدامات استاندارد را نمایش می‌دهد: چاپ، ارسال با ایمیل، ذخیره در Files.

Open In فایل را کپی می‌کند — برنامه مقصد نسخه خود را دریافت می‌کند، بنابراین تغییرات به برنامه اصلی بازگردانده نمی‌شوند. اگر ویرایش با ذخیره‌سازی مورد نیاز است، از UIDocumentPickerViewController در حالت export با URL امن استفاده کنید.

پیکربندی UIActivityViewController به عنوان جایگزین

از iOS 6، UIActivityViewController در دسترس است که همچنین از ارسال فایل‌ها پشتیبانی می‌کند. بر خلاف UIDocumentInteractionController، UIActivityViewController برگه اقدامات سیستم را با پشتیبانی از AirDrop، ایمیل، پیام‌ها و UIActivity سفارشی نمایش می‌دهد. برای ارسال ساده فایل‌ها، UIActivityViewController به عنوان API مدرن‌تر توصیه می‌شود.

نمونه کد: Open In در Swift

پیاده‌سازی Open In از طریق UIDocumentInteractionController فقط به چند خط کد نیاز دارد: ایجاد نمونه، تنظیم URL و delegate، فراخوانی presentOptionsMenu. کنترل‌کننده به طور خودکار لیست برنامه‌های موجود را بر اساس نوع فایل جمع‌آوری می‌کند.

class DocumentViewController: UIViewController {

    lazy var interactionController = UIDocumentInteractionController()

    func shareFile(url: URL) {
        interactionController.url = url
        interactionController.uti = url.utiType()
        interactionController.delegate = self
        interactionController.presentOptionsMenu(
            from: self.view.bounds,
            in: self.view,
            animated: true
        )
    }
}

راه‌اندازی Preview به جای منو

برای نمایش نمایش‌دهنده داخلی به جای منوی Open In، از متد presentPreview استفاده کنید. کنترل‌کننده سند را در تمام صفحه با قابلیت ورق زدن نمایش می‌دهد. Delegate باید متد previewControllerForDocumentInteractionController را پیاده‌سازی کند که UIViewController را برای نمایش برمی‌گرداند.

UIDocumentInteractionControllerDelegate و چرخه حیات

UIDocumentInteractionControllerDelegate نمایش و پنهان‌سازی منو و Preview را مدیریت می‌کند. Delegate متدهای اختیاری را پیاده‌سازی می‌کند: documentInteractionControllerWillPresentOpenInMenu برای انیمیشن ظاهر شدن، documentInteractionControllerDidDismissOpenInMenu برای پاکسازی منابع پس از بسته شدن منو.

متد مهم برای Preview — previewControllerForDocumentInteractionController که باید UIViewController را برای نمایش سند برگرداند. اگر متد پیاده‌سازی نشده باشد یا nil برگرداند، Preview راه‌اندازی نخواهد شد. معمولاً self یا UINavigationController حاوی self برگردانده می‌شود.

کنترل‌کننده همچنین از متد documentInteractionController:didEndSendingToApplication پشتیبانی می‌کند که پس از انتقال موفق فایل به برنامه دیگر فراخوانی می‌شود. این امکان پاکسازی فایل موقت یا به‌روزرسانی رابط را پس از بازگشت به برنامه فراهم می‌کند.

تفاوت با UIDocumentPickerViewController

UIDocumentInteractionController و UIDocumentPickerViewController وظایف متفاوتی را حل می‌کنند، اگرچه هر دو با اسناد کار می‌کنند. تفاوت اصلی: UIDocumentInteractionController فایل موجود را به برنامه دیگر منتقل می‌کند، در حالی که UIDocumentPickerViewController فایل را از منبع خارجی برای برنامه جاری انتخاب می‌کند.

UIDocumentInteractionController نیازی به delegate برای کار پایه ندارد — منو حتی بدون پیاده‌سازی متدها نمایش داده می‌شود. UIDocumentPickerViewController بدون delegate بی‌فایده است — نتیجه انتخاب پردازش نخواهد شد. انتخاب API به سناریو بستگی دارد: ارسال فایل → UIDocumentInteractionController، دریافت فایل → UIDocumentPickerViewController.