UIDocumentPickerViewController — ما هو، العمل مع المستندات في iOS

ما هو UIDocumentPickerViewController؟

UIDocumentPickerViewController هو واحد تحكم UIKit يوفر واجهة نظامية لاختيار المستندات. هو جزء من إطار UIKit ومتاح منذ iOS 8. يعرض واحد تحكم متصفح ملفات يشمل التخزين المحلي، iCloud Drive وخدمات سحابية تابعة لجهات ثالثة مسجلة.

يعمل واحد تحكم بشكل غير متزامن: بعد استدعاء present، يرى المستخدم حوار نظامي، يختار ملفاً، وتعاد النتيجة عبر المفوض. لا تتطلب التطبيق أذونات خاصة للوصول إلى الملف المحدد — يوفر المنتقي النظامي تلقائياً وصولاً مؤقتاً إلى URI.

يدعم UIDocumentPickerViewController iPad عبر UIPopoverPresentationController وواجهة متكيفة لـ iPhone. منذ iOS 14، تلقى واحد تحكم تصميماً محدثاً ودعم تنقل sidebar في iPadOS.

أنماط العمل: import و export

UIDocumentPickerViewController يعمل بوضعين رئيسيين، كل منهما يحدد كيفية وصول التطبيق إلى الملف. يتم تعيين الوضع عبر المعلمة forOpeningContentTypes أو forExporting حسب المهمة.

Import mode (forOpeningContentTypes) ينسخ الملف المحدد إلى صندوق التطبيق. يتلقى التطبيق URL لنسخته الخاصة من الملف، والتي لا يمكن الوصول إليها إلا له. هذا وضع آمن: لا يتم تعديل ملف تطبيق آخر، والنسخة تحت السيطرة الكاملة للتطبيق الحالي.

Export mode (forExporting) يوفر URL للملف الأصلي دون نسخ. يمكن للتطبيق قراءة الملف عبر الرابط، ولكن التغييرات لا تحفظ. يستخدم هذا الوضع عند الحاجة لنقل ملف إلى تطبيق آخر أو إرساله بالبريد. لكتابة التغييرات يستخدم الوضع open مع scoped security-scoped URL.

إعداد المنتقي والتصفية حسب 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، تعيين المفوض واستدعاء present. بعد اختيار الملف، يتلقى المفوض مصفوفة من URLs في الطريقة 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 قبل القراءة. يخبر هذا الملف واحد تحكم النظام بأن التطبيق يحصل على وصول مؤقت إلى ملف خارج صندوق التطبيق. بعد الانتهاء، استدع دائماً stopAccessingSecurityScopedResource، وإلا قد يحظر النظام الوصول.

UIDocumentPickerDelegate ومعالجة النتائج

UIDocumentPickerDelegate يتلقى نتائج اختيار الملف عبر طريقتين: didPickDocumentsAt عند النجاح و didPickDocumentsAt عند الإلغاء. iOS تستدعي تلقائياً طريقة الإلغاء إذا أغلق المستخدم المنتقي دون اختيار.

يشمل معالجة الأخطاء التحقق من توفر URL. إذا اختار المستخدم ملفاً من iCloud Drive ولكن الجهاز غير متصل، قد لا يكون URL متاحاً. يوصى بالتحقق من FileManager.default.isReadableFile قبل القراءة وعرض رسالة خطأ واضحة للمستخدم.

لـ iOS 14+، تتوفر طريقة جديدة documentPicker:didPickDocumentsAt مع مصفوفة من URLs. الطريقة القديمة didPickDocumentAt (مفردة) مهملة. تعامل دائماً مع المصفوفة، حتى لو كان تحديد عدة اختيارات معطلاً — توصي Apple باستخدام معالج واحد.

UIDocumentPickerViewController على iPad

iPad يتطلب تكويناً خاصاً لـ UIDocumentPickerViewController. على iPad، يتم عرض المنتقي كـ popover، ويحتاج إلى تحديد sourceView للوضع الصحيح. بدون sourceView، قد يتعطل واحد تحكم باستثناء على iPadOS.

للتنبيقة المنبثقة، يتم استخدام الخاصية popoverPresentationController. حدد sourceView و sourceRect لربطه بزر أو خلية جدول. على iPhone، ليس لهذا الكود تأثير — iOS يعرض المنتقي بشكل كامل الشاشة تلقائياً. منذ iPadOS 16، يدعم واحد تحكم sidebar و split view لتحسين التنقل.

يتبدل التصميم المتكيف لـ UIDocumentPickerViewController تلقائياً بين ملء الشاشة (iPhone) و popover (iPad). لا يحتاج المطور إلى تنفيذ واحدات تحكم منفصلة لأجهزة مختلفة — يكفي تكوين popoverPresentationController بشكل صحيح لـ iPad.