UIDocumentInteractionController — Open In والمستندات

ما هو UIDocumentInteractionController؟

UIDocumentInteractionController هو فئة من UIKit توفر واجهة نظام للعمل مع المستندات. على عكس UIDocumentPickerViewController الذي يختار الملفات، تعمل وحدة التحكم هذه مع ملف موجود بالفعل في التطبيق وتقدم للمستخدم إجراءات: المعاينة، الفتح في تطبيق آخر، الطباعة أو الإرسال.

وحدة التحكم ليست ViewController — لا يتم استدعاؤها عبر present. بدلاً من ذلك، تعرض قائمة إجراءات النظام من خلال طريقة presentOptionsMenu أو presentPreview. تعرض القائمة جميع التطبيقات المسجلة لمعالجة نوع الملف المحدد.

UIDocumentInteractionController متاح منذ iOS 2.0 وهو من أقدم الـAPIs للعمل مع المستندات. على الرغم من عمره، لا يزال مناسباً لتنفيذ ميزة Open In والمعاينة المدمجة دون مكتبات طرف ثالث.

وضع Preview: عارض المستندات المدمج

Preview هو عارض مستندات مدمج توفره UIDocumentInteractionController. يدعم PDF والصور والملفات النصية ومستندات المكتب (بما في ذلك .doc و .xls و .ppt). يتم عرض المعاينة مع رسوم متحركة انتقالية مشابهة لـ Quick Look القياسي.

لتشغيل المعاينة، قم باستدعاء طريقة presentPreview. تتطلب وحدة التحكم مفوضاً ينفذ طريقة previewControllerForDocumentInteractionController، والتي تعيد UIViewController لعرض المستند. عادةً ما يتم إرجاع self أو وحدة تحكم التنقل.

المعاينة المدمجة لا تتطلب أطر عمل أو تراخيص إضافية. تعمل مع أي ملف يتم تمرير عنوان URL الخاص به إلى الخاصية url. يمكن للمستخدمين التمرير عبر صفحات PDF، وتكبير الصور، ونسخ النص من المستندات.

وضع Open In: نقل الملفات بين التطبيقات

Open In هي الميزة الرئيسية لـ UIDocumentInteractionController. تعرض قائمة بالتطبيقات التي يمكنها فتح نوع الملف المحدد. يختار المستخدم التطبيق الهدف، وتقوم iOS بنسخ الملف إلى صندوق الحماية الخاص به، وتشغيل التطبيق للعمل مع المستند.

يتم إنشاء قائمة التطبيقات تلقائياً بناءً على إدخالات Document Type المسجلة في Info.plist للتطبيقات الأخرى. إذا سجل تطبيق دعم PDF، فسيظهر في قائمة Open In لملفات PDF. يعرض النظام أيضاً إجراءات قياسية: الطباعة، الإرسال بالبريد الإلكتروني، الحفظ في الملفات.

Open In ينسخ الملف — يتلقى التطبيق الهدف نسخته الخاصة، لذلك لا يتم حفظ التغييرات مرة أخرى في التطبيق الأصلي. إذا كنت بحاجة إلى تحرير مع الحفظ، استخدم UIDocumentPickerViewController في وضع التصدير مع URL آمن النطاق.

UIActivityViewController كبديل

منذ iOS 6، أصبح UIActivityViewController متاحاً، وهو يدعم أيضاً مشاركة الملفات. على عكس UIDocumentInteractionController، يعرض UIActivityViewController ورقة أنشطة النظام مع دعم AirDrop والبريد الإلكتروني والرسائل و UIActivity المخصصة. لمشاركة الملفات البسيطة، يوصى باستخدام UIActivityViewController كـ API أكثر حداثة.

مثال كود: Open In في Swift

تنفيذ Open In عبر UIDocumentInteractionController يتطلب بضعة أسطر فقط من الكود: إنشاء مثيل، تعيين URL والمفوض، استدعاء 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. ستعرض وحدة التحكم المستند بملء الشاشة مع إمكانية التمرير. يجب على المفوض تنفيذ طريقة previewControllerForDocumentInteractionController، وإرجاع UIViewController للعرض.

UIDocumentInteractionControllerDelegate ودورة الحياة

UIDocumentInteractionControllerDelegate يدير عرض وإخفاء القائمة والمعاينة. ينفذ المفوض طرقاً اختيارية: documentInteractionControllerWillPresentOpenInMenu لرسوم الظهور المتحركة، documentInteractionControllerDidDismissOpenInMenu لتنظيف الموارد بعد إخفاء القائمة.

طريقة مهمة للمعاينة هي previewControllerForDocumentInteractionController، والتي يجب أن تعيد UIViewController لعرض المستند. إذا لم يتم تنفيذ الطريقة أو أعادت nil، فلن تبدأ المعاينة. عادةً ما يتم إرجاع self أو UINavigationController يحتوي على self.

تدعم وحدة التحكم أيضاً طريقة documentInteractionController:didEndSendingToApplication، التي يتم استدعاؤها بعد إرسال الملف بنجاح إلى تطبيق آخر. يتيح ذلك تنظيف الملفات المؤقتة أو تحديث الواجهة بعد العودة إلى التطبيق.

الاختلافات عن UIDocumentPickerViewController

UIDocumentInteractionController و UIDocumentPickerViewController يحلان مهاماً مختلفة، على الرغم من أن كلاهما يعمل مع المستندات. الفرق الرئيسي: UIDocumentInteractionController ينقل ملفاً موجوداً إلى تطبيق آخر، بينما UIDocumentPickerViewController يختار ملفاً من مصدر خارجي للتطبيق الحالي.

UIDocumentInteractionController لا يتطلب مفوضاً للتشغيل الأساسي — ستظهر القائمة حتى بدون تنفيذ الطرق. UIDocumentPickerViewController بدون مفوض عديم الفائدة — لن تتم معالجة نتيجة الاختيار. يعتمد اختيار API على السيناريو: إرسال ملف → UIDocumentInteractionController، استلام ملف → UIDocumentPickerViewController.