UIDocumentPickerViewController — εργασία με έγγραφα στο iOS

Τι είναι το UIDocumentPickerViewController;

UIDocumentPickerViewController — είναι ένας ελεγκτής UIKit που παρέχει διεπαφή συστήματος για την επιλογή εγγράφων. Αποτελεί μέρος του πλαισίου UIKit και είναι διαθέσιμο από το iOS 8. Ο ελεγκτής εμφανίζει ένα πρόγραμμα περιήγησης αρχείων που περιλαμβάνει τοπικό αποθηκευτικό χώρο, iCloud Drive και εγγεγραμμένες τρίτες υπηρεσίες cloud.

Ο ελεγκτής λειτουργεί ασύγχρονα: μετά την κλήση του present, ο χρήστης βλέπει έναν διάλογο συστήματος, επιλέγει το αρχείο και το αποτέλεσμα επιστρέφεται μέσω του delegate. Η εφαρμογή δεν απαιτεί ειδικές άδειες για πρόσβαση στο επιλεγμένο αρχείο — ο επιλογέας συστήματος παρέχει αυτόματα προσωρινή πρόσβαση στο URI.

Το UIDocumentPickerViewController υποστηρίζει iPad μέσω UIPopoverPresentationController και προσαρμοστική διεπαφή για iPhone. Από το iOS 14, ο ελεγκτής έλαβε ανανεωμένο σχεδιασμό και υποστήριξη πλοήγησης sidebar στο iPadOS.

Τρόποι λειτουργίας: import και export

UIDocumentPickerViewController λειτουργεί σε δύο κύριες λειτουργίες, καθεμία από τις οποίες καθορίζει πώς η εφαρμογή αποκτά πρόσβαση στο αρχείο. Η λειτουργία ορίζεται μέσω της παραμέτρου forOpeningContentTypes ή forExporting ανάλογα με την εργασία.

Λειτουργία Import (forOpeningContentTypes) αντιγράφει το επιλεγμένο αρχείο στο sandbox της εφαρμογής. Η εφαρμογή λαμβάνει το URL του δικού της αντιγράφου του αρχείου, προσβάσιμο μόνο σε αυτήν. Αυτή είναι μια ασφαλής λειτουργία: το αρχείο άλλης εφαρμογής δεν τροποποιείται και το αντίγραφο ελέγχεται πλήρως από την τρέχουσα εφαρμογή.

Λειτουργία Export (forExporting) παρέχει URL στο πρωτότυπο αρχείο χωρίς αντιγραφή. Η εφαρμογή μπορεί να διαβάσει το αρχείο μέσω του συνδέσμου, αλλά οι αλλαγές δεν αποθηκεύονται. Αυτή η λειτουργία χρησιμοποιείται όταν χρειάζεται να μεταφέρετε ένα αρχείο σε άλλη εφαρμογή ή να το στείλετε μέσω email. Για την εγγραφή αλλαγών χρησιμοποιείται η λειτουργία open με security-scoped URL.

Ρύθμιση του picker και φιλτράρισμα κατά 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, ορίστε τον delegate και καλέστε το present. Μετά την επιλογή αρχείου, ο delegate λαμβάνει έναν πίνακα URL στη μέθοδο 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

Το security-scoped URL απαιτεί κλήση του startAccessingSecurityScopedResource πριν από την ανάγνωση. Αυτή η μέθοδος ειδοποιεί το σύστημα ότι η εφαρμογή αποκτά προσωρινή πρόσβαση σε ένα αρχείο εκτός του sandbox. Μετά την ολοκλήρωση, φροντίστε να καλέσετε το stopAccessingSecurityScopedResource, διαφορετικά το σύστημα μπορεί να αποκλείσει την πρόσβαση.

UIDocumentPickerDelegate και χειρισμός αποτελεσμάτων

UIDocumentPickerDelegate λαμβάνει τα αποτελέσματα επιλογής αρχείου μέσω δύο μεθόδων: didPickDocumentsAt σε επιτυχία και didPickDocumentsAt σε ακύρωση. Το iOS καλεί αυτόματα τη μέθοδο ακύρωσης εάν ο χρήστης έκλεισε τον επιλογέα χωρίς επιλογή.

Ο χειρισμός σφαλμάτων περιλαμβάνει έλεγχο διαθεσιμότητας του URL. Εάν ο χρήστης επέλεξε αρχείο από το iCloud Drive αλλά η συσκευή είναι εκτός σύνδεσης, το URL ενδέχεται να μην είναι διαθέσιμο. Συνιστάται ο έλεγχος του FileManager.default.isReadableFile πριν από την ανάγνωση και η εμφάνιση ενός κατανοητού μηνύματος σφάλματος.

Για iOS 14+ είναι διαθέσιμη η νέα μέθοδος documentPicker:didPickDocumentsAt με πίνακα URL. Η παλιά μέθοδος didPickDocumentAt (μεμονωμένη) είναι deprecated. Χειριστείτε πάντα τον πίνακα, ακόμη και αν το allowsMultipleSelection είναι απενεργοποιημένο — η Apple συνιστά τη χρήση ενιαίου χειριστή.

UIDocumentPickerViewController στο iPad

iPad απαιτεί ειδική διαμόρφωση του UIDocumentPickerViewController. Στο iPad, ο επιλογέας εμφανίζεται ως popover και απαιτεί τον καθορισμό sourceView για σωστή τοποθέτηση. Χωρίς sourceView, ο ελεγκτής μπορεί να καταρρεύσει με εξαίρεση στο iPadOS.

Για το popover, χρησιμοποιείται η ιδιότητα popoverPresentationController. Καθορίστε sourceView και sourceRect για σύνδεση σε κουμπί ή κελί πίνακα. Στο iPhone, αυτός ο κώδικας δεν έχει καμία επίδραση — το iOS εμφανίζει αυτόματα τον επιλογέα σε πλήρη οθόνη. Από το iPadOS 16, ο ελεγκτής υποστηρίζει sidebar και split view για βελτιωμένη πλοήγηση.

Ο προσαρμοστικός σχεδιασμός του UIDocumentPickerViewController αλλάζει αυτόματα μεταξύ full-screen (iPhone) και popover (iPad). Ο προγραμματιστής δεν χρειάζεται να υλοποιήσει ξεχωριστούς ελεγκτές για διαφορετικές συσκευές — αρκεί η σωστή διαμόρφωση του popoverPresentationController για το iPad.