UIDocumentPickerViewController — یہ کیا ہے، iOS دستاویز کے ساتھ کام

UIDocumentPickerViewController کیا ہے؟

UIDocumentPickerViewController ایک UIKit کنٹرولر ہے جو دستاویز منتخب کرنے کے لیے ایک سسٹم انٹرفیس فراہم کرتا ہے۔ یہ UIKit فریم ورک کا ایک حصہ ہے اور iOS 8 سے دستیاب ہے۔ کنٹرولر ایک فائل براؤزر ظاہر کرتا ہے جس میں مقامی سٹوریج، iCloud Drive اور رجسٹر شدہ تیسرے فرق کی کلاؤڈ سروسس شامل ہیں۔

کنٹرولر غیر متضمن طور پر کام کرتا ہے: present کو کال کرنے کے بعد، صارف ایک سسٹم ڈائیلوگ دیکھتا ہے، ایک فائل منتخب کرتا ہے، اور نتیجہ ڈیلیگیٹ کے ذریعے واپس کیا جاتا ہے۔ ایپ کو منتخب کردہ فائل تک رسائی کے لیے خاص اجازت کی ضرورت نہیں ہے — سسٹم پکر خودکار طور پر URI تک عارضی رسائی فراہم کرتا ہے۔

UIDocumentPickerViewController UIPopoverPresentationController کے ذریعے iPad اور iPhone کے لیے ایک اڈاپٹو انٹرفیس کی حمایت کرتا ہے۔ iOS 14 سے، کنٹرولر نے ایک اپ ڈیٹ ڈیزائن اور iPadOS میں سائیڈبار نیویگیشن کی حمایت حاصل کی ہے۔

کام کے طریقے: import اور export

UIDocumentPickerViewController دو اہم موڈ میں کام کرتا ہے، ہر ایک یہ طے کرتا ہے کہ ایپ فائل تک کیسے رسائی حاصل کرتا ہے۔ موڈ کام کے مطابق forOpeningContentTypes یا forExporting پیرامیٹر کے ذریعے مقرر کیا جاتا ہے۔

Import mode (forOpeningContentTypes) منتخب کردہ فائل کو ایپ سینڈباکس میں کاپی کرتا ہے۔ ایپ فائل کی اپنی کاپی کا URL وصول کرتا ہے، جس تک صرف اسی رسائی ہو سکتی ہے۔ یہ ایک محفوظ موڈ ہے: دوسرے ایپ کی فائل میں ترمیم نہیں ہوتی، اور کاپی مکمل طور پر موجودہ ایپ کے اختیار میں ہوتی ہے۔

Export mode (forExporting) کاپی کیئے بغیر اصل فائل کا URL فراہم کرتا ہے۔ ایپ لنک کے ذریعے فائل پڑھ سکتا ہے، لیکن تبدیلیاں محفوظ نہیں ہوتیں۔ یہ موڈ اس وقت استعمال ہوتا ہے جب کسی دوسرے ایپ کو فائل منتقل کرنے یا ای میل کے ذریعے بھیجنے کی ضرورت ہو—۔ تبدیلیاں لکھنے کے لیے، scoped security-scoped URL کے ساتھ open موڈ استعمال ہوتا ہے۔

پکر کی ترتیب اور UTI فلٹرنگ

UTI (Uniform Type Identifier) Apple ایکوسسٹم میں مواد کی قسم کی شناخت کا نظام ہے۔ UIDocumentPickerViewController forOpeningContentTypes کے ذریعے پاس کی گئی UTI ایرے کے مطابق ظاہر کردہ فائلوں کو فلٹر کرتا ہے۔ اگر کوئی 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 میں دستاویز کا انتخاب

نفاذ Swift میں UIDocumentPickerViewController کھام ہے: UTI اقسام کے ساتھ ایک کنٹرولر اینسٹنس تیار کریں، ڈیلیگیٹ مقرر کریں اور present کو کال کریں۔ فائل منتخب ہونے کے بعد، ڈیلیگیٹ didPickDocumentsAt میتھڈ میں URLs کی ایک ایرے وصول کرتا ہے۔ ہر 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 وسائل

ایک security-scoped URL کو پڑھنے سے پہلے startAccessingSecurityScopedResource کو کال کرنے کی ضرورت ہے۔ یہ میتھڈ سسٹم کو آگاہ کرتا ہے کہ ایپ سینڈباکس کے باہر کی ایک فائل تک عارضی رسائی حاصل کر رہا ہے۔ مکمل کرنے کے بعد، ہمیشہ stopAccessingSecurityScopedResource کو کال کریں، ورنہ سسٹم رسائی کو مسدود کر سکتا ہے۔

UIDocumentPickerDelegate اور نتائج کی پروسیسنگ

UIDocumentPickerDelegate دو میتھڈ کے ذریعے فائل منتخب کرنے کے نتائج وصول کرتا ہے: کامیابی پر didPickDocumentsAt اور منسوخی پر didPickDocumentsAt۔ iOS خودکار طور پر منسوخی کے میتھڈ کو کال کرتا ہے اگر صارف بغیر انتخاب کیئے پکر کو بند کرتا ہے۔

غلطی کی پروسیسنگ میں URL کی دستیابی کی جانچ شامل ہے۔ اگر صارف نے iCloud Drive سے ایک فائل منتخب کی لیکن آلا آفلائن ہے، تو URL دستیاب نہیں ہو سکتا ہے۔ پڑھنے سے پہلے FileManager.default.isReadableFile کی جانچ کرنے اور صارف کو ایک واضح غلطی کا پیغام دکھانے کی سفارش کی جاتی ہے۔

iOS 14+ کے لیے، URLs کی ایک ایرے کے ساتھ ایک نیا میتھڈ documentPicker:didPickDocumentsAt دستیاب ہے۔ پرانا میتھڈ didPickDocumentAt (ایکل) فرسودہ ہے۔ ہمیشہ ایرے کو ہینڈل کریں، چاہے allowsMultipleSelection نااکتیو ہو — Apple ایک ہینڈلر استعمال کرنے کی سفارش کرتا ہے۔

iPad پر UIDocumentPickerViewController

iPad کو UIDocumentPickerViewController کی خاص ترتیب کی ضرورت ہے۔ iPad پر، پکر ایک popover کے طور پر ظاہر ہوتا ہے اور مناسب مقام کے لیے sourceView متعین کرنا ضروری ہے۔ sourceView کے بغیر، کنٹرولر iPadOS پر ایک استثناء کے ساتھ کراش کر سکتا ہے۔

popover کے لیے، popoverPresentationController کی خاصیت استعمال ہوتی ہے۔ اسے ایک بٹن یا ٹیبل سیل سے منسوخ کرنے کے لیے sourceView اور sourceRect متعین کریں۔ iPhone پر، اس کوڈ کا کوئی اثر نہیں ہے — iOS خودکار طور پر پکر کو فل سکرین دکھاتا ہے۔ iPadOS 16 سے، کنٹرولر بہتر نیویگیشن کے لیے سائیڈبار اور سپلٹ ویو کی حمایت کرتا ہے۔

UIDocumentPickerViewController کا اڈاپٹو ڈیزائن خودکار طور پر فل سکرین (iPhone) اور popover (iPad) کے درمیان سوئچ کرتا ہے۔ ڈیولپر کو مختلف آلات کے لیے علیحدہ کنٹرولرز نفاذ کرنے کی ضرورت نہیں ہے — iPad کے لیے popoverPresentationController کو صحیح طور پر ترتیب دینا کافی ہے۔