UIDocumentPickerViewController — यह क्या है, iOS दस्तावेज़ों के साथ कार्य

UIDocumentPickerViewController क्या है?

UIDocumentPickerViewController एक UIKit कंट्रोलर है जो दस्तावेज़ चुनने के लिए एक सिस्टम इंटरफ़ेस प्रदान करता है। यह UIKit फ़्रेमवर्क का हिस्सा है और iOS 8 से उपलब्ध है। कंट्रोलर एक फ़ाइल ब्राउज़र प्रदर्शित करता है जिसमें स्थानीय स्टोरेज, iCloud Drive और पंजीकृत तीसरे पक्ष के क्लाउड सेवाएं शामिल हैं।

कंट्रोलर असिंक्रोनस रूप से कार्य करता है: present कॉल करने के बाद, उपयोगकर्ता एक सिस्टम डायलॉग देखता है, एक फ़ाइल चुनता है, और परिणाम डिलीगेट के माध्यम से लौटाया जाता है। ऐप को चुनी गई फ़ाइल तक पहुंचने के लिए विशेष अनुमति की आवश्यकता नहीं है — सिस्टम पिकर स्वचालित रूप से URI तक अस्थायी पहुंच प्रदान करता है।

UIDocumentPickerViewController UIPopoverPresentationController के माध्यम से iPad का समर्थन करता है और iPhone के लिए एडाप्टिव इंटरफ़ेस प्रदान करता है। iOS 14 से, कंट्रोलर को अपडेटेड डिजाइन और iPadOS में sidebar नेविगेशन समर्थन मिला है।

कार्य विधियां: 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 से, कंट्रोलर बेहतर नेविगेशन के लिए sidebar और split view का समर्थन करता है।

UIDocumentPickerViewController का एडाप्टिव डिजाइन स्वचालित रूप से फ़ुल-स्क्रीन (iPhone) और popover (iPad) के बीच स्विच करता है। डिवलपर को विभिन्न डिवाइसों के लिए अलग कंट्रोलर लागू करने की आवश्यकता नहीं है — iPad के लिए popoverPresentationController को सही ढंग से कॉन्फ़िगर करना पर्याप्त है।