UIDocumentPickerViewController — was ist das, Arbeiten mit Dokumenten in iOS

Was ist UIDocumentPickerViewController?

UIDocumentPickerViewController ist ein UIKit-Controller, der eine Systemschnittstelle zum Auswählen von Dokumenten bereitstellt. Es ist Teil des UIKit-Frameworks und seit iOS 8 verfügbar. Der Controller zeigt einen Dateibrowser an, der lokalen Speicher, iCloud Drive und registrierte Cloud-Dienste von Drittanbietern umfasst.

Der Controller arbeitet asynchron: Nach dem Aufruf von present sieht der Benutzer einen Systemdialog, wählt eine Datei aus und das Ergebnis wird über den Delegaten zurückgegeben. Die App benötigt keine speziellen Berechtigungen für den Zugriff auf die ausgewählte Datei — der System-Picker gewährt automatisch temporären Zugriff auf die URI.

UIDocumentPickerViewController unterstützt iPad über UIPopoverPresentationController und eine adaptive Oberfläche für das iPhone. Seit iOS 14 hat der Controller ein aktualisiertes Design und Unterstützung für die Sidebar-Navigation in iPadOS erhalten.

Funktionsweisen: import und export

UIDocumentPickerViewController arbeitet in zwei Hauptmodi, die jeweils bestimmen, wie die App auf die Datei zugreift. Der Modus wird über den Parameter forOpeningContentTypes oder forExporting je nach Aufgabe festgelegt.

Import mode (forOpeningContentTypes) kopiert die ausgewählte Datei in das App-Sandbox. Die App erhält eine URL auf ihre eigene Kopie der Datei, die nur für sie zugänglich ist. Dies ist ein sicherer Modus: Die Datei einer anderen App wird nicht verändert und die Kopie wird vollständig von der aktuellen App kontrolliert.

Export mode (forExporting) stellt eine URL auf die Originaldatei ohne Kopieren bereit. Die App kann die Datei über den Link lesen, aber Änderungen werden nicht zurückgespeichert. Dieser Modus wird verwendet, wenn eine Datei an eine andere App übertragen oder per E-Mail gesendet werden muss. Zum Schreiben von Änderungen wird der open-Modus mit scoped security-scoped URL verwendet.

Picker-Einrichtung und UTI-Filterung

UTI (Uniform Type Identifier) ist ein System zur Identifizierung von Inhaltstypen im Apple-Ökosystem. UIDocumentPickerViewController filtert die angezeigten Dateien nach dem über forOpeningContentTypes übergebenen UTI-Array. Wenn keine UTI angegeben ist, zeigt der Picker alle Dateitypen an.

• PDF — com.adobe.pdf. Der Picker zeigt nur PDF-Dokumente an.
• Bilder — public.image. Enthält JPEG, PNG, HEIC und andere Formate.
• Text — public.plain-text. Zeigt .txt-, .csv- und andere Textdateien an.
• Audio — public.audio. Enthält MP3, AAC, WAV und Lossless-Formate.
• Video — public.movie. Zeigt MP4, MOV, AVI und andere Videoformate an.

Zur Auswahl mehrerer Typen wird ein Array [UTType.pdf, UTType.image] übergeben. Seit iOS 14 empfiehlt Apple die Verwendung von UTType anstelle von String-Konstanten. UIDocumentPickerViewController aktualisiert automatisch die Liste der angezeigten Typen, wenn der ausgewählte Anbieter wechselt.

Codebeispiel: Dokumentenauswahl in Swift

Implementierung von UIDocumentPickerViewController in Swift ist minimal: Erstellen Sie eine Controller-Instanz mit UTI-Typen, setzen Sie den Delegaten und rufen Sie present auf. Nach der Dateiauswahl erhält der Delegat ein Array von URLs in der Methode didPickDocumentsAt. Jede URL ist ein security-scoped Verweis, der den Aufruf von startAccessingSecurityScopedResource erfordert.

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() }
    // datei von url lesen
}

Security-Scoped Ressourcen

Eine security-scoped URL erfordert den Aufruf von startAccessingSecurityScopedResource vor dem Lesen. Diese Methode teilt dem System mit, dass die App temporären Zugriff auf eine Datei außerhalb der Sandbox erhält. Rufen Sie nach Abschluss immer stopAccessingSecurityScopedResource auf, da das System sonst den Zugriff blockieren kann.

UIDocumentPickerDelegate und Ergebnisverarbeitung

UIDocumentPickerDelegate erhält die Dateiauswahlergebnisse über zwei Methoden: didPickDocumentsAt bei Erfolg und didPickDocumentsAt bei Abbruch. iOS ruft automatisch die Abbruchmethode auf, wenn der Benutzer den Picker ohne Auswahl schließt.

Die Fehlerbehandlung umfasst die Überprüfung der URL-Verfügbarkeit. Wenn der Benutzer eine Datei aus iCloud Drive ausgewählt hat, das Gerät jedoch offline ist, ist die URL möglicherweise nicht verfügbar. Es wird empfohlen, vor dem Lesen FileManager.default.isReadableFile zu überprüfen und dem Benutzer eine klare Fehlermeldung anzuzeigen.

Für iOS 14+ ist eine neue Methode documentPicker:didPickDocumentsAt mit einem Array von URLs verfügbar. Die alte Methode didPickDocumentAt (einzeln) ist veraltet. Behandeln Sie immer das Array, auch wenn allowsMultipleSelection deaktiviert ist — Apple empfiehlt die Verwendung eines einzigen Handlers.

UIDocumentPickerViewController auf dem iPad

iPad erfordert eine spezielle Konfiguration von UIDocumentPickerViewController. Auf dem iPad wird der Picker als Popover angezeigt und muss eine sourceView für die korrekte Positionierung angeben. Ohne sourceView kann der Controller auf iPadOS mit einer Ausnahme abstürzen.

Für das Popover wird die Eigenschaft popoverPresentationController verwendet. Geben Sie sourceView und sourceRect an, um es an eine Schaltfläche oder Tabellenzelle zu binden. Auf dem iPhone hat dieser Code keine Auswirkung — iOS zeigt den Picker automatisch im Vollbildmodus an. Seit iPadOS 16 unterstützt der Controller Sidebar und Split View für verbesserte Navigation.

Das adaptive Design von UIDocumentPickerViewController wechselt automatisch zwischen Vollbild (iPhone) und Popover (iPad). Der Entwickler muss keine separaten Controller für verschiedene Geräte implementieren — es reicht aus, den popoverPresentationController für das iPad korrekt zu konfigurieren.