UIDocumentPickerViewController — praca z dokumentami w iOS

Czym jest UIDocumentPickerViewController?

UIDocumentPickerViewController — to kontroler UIKit zapewniający systemowy interfejs do wyboru dokumentów. Należy do frameworka UIKit i jest dostępny od iOS 8. Kontroler wyświetla przeglądarkę plików, która obejmuje magazyn lokalny, iCloud Drive i zarejestrowane zewnętrzne usługi chmurowe.

Kontroler działa asynchronicznie: po wywołaniu present użytkownik widzi systemowy dialog, wybiera plik, a wynik jest zwracany przez delegata. Aplikacja nie wymaga specjalnych uprawnień dostępu do wybranego pliku — systemowy picker automatycznie udostępnia tymczasowy dostęp do URI.

UIDocumentPickerViewController obsługuje iPad przez UIPopoverPresentationController i adaptacyjny interfejs dla iPhone. Od iOS 14 kontroler otrzymał zaktualizowany design i obsługę nawigacji sidebar w iPadOS.

Tryby pracy: import i export

UIDocumentPickerViewController działa w dwóch głównych trybach, z których każdy określa, w jaki sposób aplikacja uzyskuje dostęp do pliku. Tryb jest ustawiany przez parametr forOpeningContentTypes lub forExporting w zależności od zadania.

Tryb import (forOpeningContentTypes) kopiuje wybrany plik do piaskownicy aplikacji. Aplikacja otrzymuje URL do własnej kopii pliku, dostępnej tylko dla niej. Jest to bezpieczny tryb: plik innej aplikacji nie jest modyfikowany, a kopia jest w pełni kontrolowana przez bieżącą aplikację.

Tryb export (forExporting) udostępnia URL do oryginalnego pliku bez kopiowania. Aplikacja może czytać plik pod linkiem, ale zmiany nie są zapisywane. Ten tryb jest używany, gdy trzeba przekazać plik innej aplikacji lub wysłać go pocztą. Do zapisywania zmian używany jest tryb open z zakresem security-scoped URL.

Konfiguracja pickera i filtrowanie według UTI

UTI (Uniform Type Identifier) — to system identyfikacji typów treści w ekosystemie Apple. UIDocumentPickerViewController filtruje wyświetlane pliki według tablicy UTI przekazanej przez forOpeningContentTypes. Jeśli UTI nie jest określony, picker pokazuje wszystkie typy plików.

• PDF — com.adobe.pdf. Picker pokazuje tylko dokumenty PDF.
• Obrazy — public.image. Obejmuje JPEG, PNG, HEIC i inne formaty.
• Tekst — public.plain-text. Wyświetla .txt, .csv i inne pliki tekstowe.
• Audio — public.audio. Obejmuje MP3, AAC, WAV i formaty Lossless.
• Wideo — public.movie. Pokazuje MP4, MOV, AVI i inne formaty wideo.

Do wyboru wielu typów przekazywana jest tablica [UTType.pdf, UTType.image]. Od iOS 14 Apple zaleca używanie UTType zamiast stałych łańcuchowych. UIDocumentPickerViewController automatycznie aktualizuje listę wyświetlanych typów przy zmianie wybranego dostawcy.

Przykład kodu: wybór dokumentu w Swift

Implementacja UIDocumentPickerViewController w Swift jest minimalna: utwórz instancję kontrolera z typami UTI, ustaw delegata i wywołaj present. Po wyborze pliku delegat otrzymuje tablicę URL w metodzie didPickDocumentsAt. Każdy URL to security-scoped link wymagający wywołania 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() }
    // odczytaj plik z adresu URL
}

Zasoby security-scoped

Security-scoped URL wymaga wywołania startAccessingSecurityScopedResource przed odczytem. Ta metoda informuje system, że aplikacja uzyskuje tymczasowy dostęp do pliku poza piaskownicą. Po zakończeniu pracy koniecznie wywołaj stopAccessingSecurityScopedResource, w przeciwnym razie system może zablokować dostęp.

UIDocumentPickerDelegate i obsługa wyników

UIDocumentPickerDelegate otrzymuje wyniki wyboru pliku przez dwie metody: didPickDocumentsAt przy sukcesie i didPickDocumentsAt przy anulowaniu. iOS automatycznie wywołuje metodę anulowania, jeśli użytkownik zamknął picker bez wyboru.

Obsługa błędów obejmuje sprawdzanie dostępności URL. Jeśli użytkownik wybrał plik z iCloud Drive, ale urządzenie jest offline, URL może być niedostępny. Zaleca się sprawdzanie FileManager.default.isReadableFile przed odczytem i wyświetlanie użytkownikowi zrozumiałego komunikatu błędu.

Dla iOS 14+ dostępna jest nowa metoda documentPicker:didPickDocumentsAt z tablicą URL. Stara metoda didPickDocumentAt (pojedyncza) jest deprecated. Zawsze obsługuj tablicę, nawet jeśli allowsMultipleSelection jest wyłączone — Apple zaleca używanie jednolitego handlera.

UIDocumentPickerViewController na iPad

iPad wymaga specjalnej konfiguracji UIDocumentPickerViewController. Na iPadzie picker wyświetla się jako popover i wymaga określenia sourceView dla prawidłowego pozycjonowania. Bez sourceView kontroler może spaść z exception na iPadOS.

Dla popover używana jest właściwość popoverPresentationController. Określ sourceView i sourceRect dla przypięcia do przycisku lub komórki tabeli. Na iPhone ten kod nie ma wpływu — iOS automatycznie pokazuje picker na pełnym ekranie. Od iPadOS 16 kontroler obsługuje sidebar i split view dla ulepszonej nawigacji.

Adaptacyjny design UIDocumentPickerViewController automatycznie przełącza się między full-screen (iPhone) a popover (iPad). Deweloper nie musi implementować oddzielnych kontrolerów dla różnych urządzeń — wystarczy poprawnie skonfigurować popoverPresentationController dla iPada.