UIDocumentPickerViewController — arbeta med dokument i iOS

Vad är UIDocumentPickerViewController?

UIDocumentPickerViewController — är en UIKit-kontroll som tillhandahåller ett systemgränssnitt för att välja dokument. Den är en del av UIKit-ramverket och är tillgänglig sedan iOS 8. Kontrollen visar en filbläddrare som inkluderar lokal lagring, iCloud Drive och registrerade molntjänster från tredje part.

Kontrollen fungerar asynkront: efter att present anropats ser användaren en systemdialog, väljer filen och resultatet returneras via delegaten. Appen kräver inga speciella behörigheter för att komma åt den valda filen — systemväljaren ger automatiskt tillfällig åtkomst till URI:n.

UIDocumentPickerViewController stöder iPad via UIPopoverPresentationController och ett anpassningsbart gränssnitt för iPhone. Från och med iOS 14 har kontrollen fått en uppdaterad design och stöd för sidopanelsnavigering i iPadOS.

Arbetslägen: import och export

UIDocumentPickerViewController fungerar i två huvudlägen, som var och en bestämmer hur appen får åtkomst till filen. Läget ställs in via parametern forOpeningContentTypes eller forExporting beroende på uppgiften.

Importläge (forOpeningContentTypes) kopierar den valda filen till appens sandlåda. Appen får URL:en till sin egen kopia av filen, som endast är tillgänglig för den. Detta är ett säkert läge: filen från en annan app ändras inte, och kopian kontrolleras helt av den aktuella appen.

Exportläge (forExporting) tillhandahåller URL:en till originalfilen utan kopiering. Appen kan läsa filen via länken, men ändringarna sparas inte tillbaka. Detta läge används när du behöver överföra en fil till en annan app eller skicka den via e-post. För att skriva ändringar används open-läge med en security-scoped URL.

Konfigurera pickern och filtrera efter UTI

UTI (Uniform Type Identifier) — är ett system för att identifiera innehållstyper i Apples ekosystem. UIDocumentPickerViewController filtrerar visade filer baserat på en UTI-array som skickas via forOpeningContentTypes. Om ingen UTI anges visar pickern alla filtyper.

• PDF — com.adobe.pdf. Pickern visar endast PDF-dokument.
• Bilder — public.image. Inkluderar JPEG, PNG, HEIC och andra format.
• Text — public.plain-text. Visar .txt, .csv och andra textfiler.
• Ljud — public.audio. Inkluderar MP3, AAC, WAV och förlustfria format.
• Video — public.movie. Visar MP4, MOV, AVI och andra videoformat.

För att välja flera typer skickas arrayen [UTType.pdf, UTType.image]. Från och med iOS 14 rekommenderar Apple att använda UTType istället för strängkonstanter. UIDocumentPickerViewController uppdaterar automatiskt listan över visade typer när den valda leverantören ändras.

Kodexempel: välj dokument i Swift

Implementering av UIDocumentPickerViewController i Swift är minimal: skapa en instans av kontrollen med UTI-typer, ställ in delegaten och anropa present. Efter att filen har valts får delegaten en array med URL:er i metoden didPickDocumentsAt. Varje URL är en security-scoped-länk som kräver anrop av 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() }
    // läs fil från url
}

Security-scoped-resurser

En security-scoped URL kräver anrop av startAccessingSecurityScopedResource före läsning. Denna metod meddelar systemet att appen får tillfällig åtkomst till en fil utanför sandlådan. Efter slutfört arbete, se till att anropa stopAccessingSecurityScopedResource, annars kan systemet blockera åtkomsten.

UIDocumentPickerDelegate och hantering av resultat

UIDocumentPickerDelegate tar emot resultaten av filvalet via två metoder: didPickDocumentsAt vid framgång och didPickDocumentsAt vid avbrytande. iOS anropar automatiskt avbrytningsmetoden om användaren stängde pickern utan att göra ett val.

Felhantering inkluderar kontroll av URL:ens tillgänglighet. Om användaren valde en fil från iCloud Drive men enheten är offline, kanske URL:en inte är tillgänglig. Det rekommenderas att kontrollera FileManager.default.isReadableFile före läsning och visa ett begripligt felmeddelande för användaren.

För iOS 14+ är den nya metoden documentPicker:didPickDocumentsAt med en array av URL:er tillgänglig. Den gamla metoden didPickDocumentAt (enkel) är föråldrad. Hantera alltid arrayen, även om allowsMultipleSelection är inaktiverat — Apple rekommenderar att använda en enhetlig hanterare.

UIDocumentPickerViewController på iPad

iPad kräver en speciell konfiguration av UIDocumentPickerViewController. På iPad visas pickern som en popover och måste ange sourceView för korrekt positionering. Utan sourceView kan kontrollen krascha med ett undantag på iPadOS.

För popover används egenskapen popoverPresentationController. Ange sourceView och sourceRect för förankring till en knapp eller tabellcell. På iPhone har denna kod ingen effekt — iOS visar automatiskt pickern i helskärm. Från och med iPadOS 16 stöder kontrollen sidopanel och delad vy för förbättrad navigering.

Den adaptiva designen av UIDocumentPickerViewController växlar automatiskt mellan helskärm (iPhone) och popover (iPad). Utvecklaren behöver inte implementera separata kontroller för olika enheter — det räcker med att korrekt konfigurera popoverPresentationController för iPad.