UIDocumentPickerViewController — werken met documenten in iOS

Wat is UIDocumentPickerViewController?

UIDocumentPickerViewController — is een UIKit-controller die een systeeminterface biedt voor het selecteren van documenten. Het maakt deel uit van het UIKit-framework en is beschikbaar sinds iOS 8. De controller toont een bestandsbrowser die lokale opslag, iCloud Drive en geregistreerde externe clouddiensten omvat.

De controller werkt asynchroon: na het aanroepen van present ziet de gebruiker een systeemdialoog, selecteert het bestand en het resultaat wordt via de delegate geretourneerd. De app heeft geen speciale machtigingen nodig voor toegang tot het geselecteerde bestand — de systeempicker verleent automatisch tijdelijke toegang tot de URI.

UIDocumentPickerViewController ondersteunt iPad via UIPopoverPresentationController en een adaptieve interface voor iPhone. Vanaf iOS 14 heeft de controller een bijgewerkt ontwerp en ondersteuning voor sidebarnavigatie in iPadOS.

Werkmodi: import en export

UIDocumentPickerViewController werkt in twee hoofdmodi, die elk bepalen hoe de app toegang krijgt tot het bestand. De modus wordt ingesteld via de parameter forOpeningContentTypes of forExporting, afhankelijk van de taak.

Importmodus (forOpeningContentTypes) kopieert het geselecteerde bestand naar de sandbox van de app. De app ontvangt een URL van zijn eigen kopie van het bestand, die alleen voor hem toegankelijk is. Dit is een veilige modus: het bestand van een andere app wordt niet gewijzigd en de kopie wordt volledig gecontroleerd door de huidige app.

Exportmodus (forExporting) biedt een URL naar het originele bestand zonder kopiëren. De app kan het bestand via de link lezen, maar wijzigingen worden niet teruggeschreven. Deze modus wordt gebruikt wanneer u een bestand naar een andere app moet overbrengen of per e-mail moet verzenden. Voor het schrijven van wijzigingen wordt de open-modus gebruikt met een security-scoped URL.

De picker configureren en filteren op UTI

UTI (Uniform Type Identifier) — is een systeem voor het identificeren van inhoudstypen in het Apple-ecosysteem. UIDocumentPickerViewController filtert de weergegeven bestanden op basis van een UTI-array die via forOpeningContentTypes wordt doorgegeven. Als er geen UTI is opgegeven, toont de picker alle bestandstypen.

• PDF — com.adobe.pdf. De picker toont alleen PDF-documenten.
• Afbeeldingen — public.image. Omvat JPEG, PNG, HEIC en andere formaten.
• Tekst — public.plain-text. Toont .txt, .csv en andere tekstbestanden.
• Audio — public.audio. Omvat MP3, AAC, WAV en Lossless-formaten.
• Video — public.movie. Toont MP4, MOV, AVI en andere videoformaten.

Voor het selecteren van meerdere typen wordt de array [UTType.pdf, UTType.image] doorgegeven. Vanaf iOS 14 raadt Apple aan om UTType te gebruiken in plaats van tekenreeksconstanten. UIDocumentPickerViewController werkt de lijst met weergegeven typen automatisch bij wanneer de geselecteerde provider verandert.

Codevoorbeeld: document selecteren in Swift

Implementatie van UIDocumentPickerViewController in Swift is minimaal: maak een instantie van de controller met UTI-typen, stel de delegate in en roep present aan. Na het selecteren van het bestand ontvangt de delegate een array van URL's in de methode didPickDocumentsAt. Elke URL is een security-scoped link die een aanroep van startAccessingSecurityScopedResource vereist.

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() }
    // lees bestand van url
}

Security-scoped bronnen

Een security-scoped URL vereist een aanroep van startAccessingSecurityScopedResource vóór het lezen. Deze methode meldt het systeem dat de app tijdelijke toegang krijgt tot een bestand buiten de sandbox. Roep na het voltooien altijd stopAccessingSecurityScopedResource aan, anders kan het systeem de toegang blokkeren.

UIDocumentPickerDelegate en resultaten verwerken

UIDocumentPickerDelegate ontvangt de resultaten van de bestandsselectie via twee methoden: didPickDocumentsAt bij succes en didPickDocumentsAt bij annulering. iOS roept automatisch de annuleringsmethode aan als de gebruiker de picker zonder selectie heeft gesloten.

Foutafhandeling omvat het controleren van de beschikbaarheid van de URL. Als de gebruiker een bestand heeft geselecteerd uit iCloud Drive maar het apparaat is offline, is de URL mogelijk niet beschikbaar. Het wordt aanbevolen om FileManager.default.isReadableFile te controleren vóór het lezen en de gebruiker een begrijpelijke foutmelding te tonen.

Voor iOS 14+ is de nieuwe methode documentPicker:didPickDocumentsAt met een array van URL's beschikbaar. De oude methode didPickDocumentAt (enkelvoudig) is deprecated. Verwerk altijd de array, zelfs als allowsMultipleSelection is uitgeschakeld — Apple raadt aan om één uniforme handler te gebruiken.

UIDocumentPickerViewController op iPad

iPad vereist een speciale configuratie van UIDocumentPickerViewController. Op de iPad wordt de picker weergegeven als een popover en moet sourceView worden opgegeven voor een correcte positionering. Zonder sourceView kan de controller crashen met een uitzondering op iPadOS.

Voor de popover wordt de eigenschap popoverPresentationController gebruikt. Geef sourceView en sourceRect op voor verankering aan een knop of tabelcel. Op de iPhone heeft deze code geen effect — iOS toont de picker automatisch op volledig scherm. Vanaf iPadOS 16 ondersteunt de controller sidebar en split view voor verbeterde navigatie.

Het adaptieve ontwerp van UIDocumentPickerViewController schakelt automatisch tussen full-screen (iPhone) en popover (iPad). De ontwikkelaar hoeft geen aparte controllers voor verschillende apparaten te implementeren — het is voldoende om popoverPresentationController correct te configureren voor de iPad.