UIDocumentPickerViewController — práce s dokumenty v iOS

Co je UIDocumentPickerViewController?

UIDocumentPickerViewController — je ovladač UIKit poskytující systémové rozhraní pro výběr dokumentů. Je součástí frameworku UIKit a je k dispozici od iOS 8. Ovladač zobrazuje prohlížeč souborů, který zahrnuje místní úložiště, iCloud Drive a registrované cloudové služby třetích stran.

Ovladač pracuje asynchronně: po volání present uživatel uvidí systémový dialog, vybere soubor a výsledek je vrácen prostřednictvím delegáta. Aplikace nevyžaduje zvláštní oprávnění pro přístup k vybranému souboru — systémový picker automaticky poskytuje dočasný přístup k URI.

UIDocumentPickerViewController podporuje iPad prostřednictvím UIPopoverPresentationController a adaptivní rozhraní pro iPhone. Od iOS 14 získal ovladač aktualizovaný design a podporu navigace postranním panelem v iPadOS.

Režimy práce: import a export

UIDocumentPickerViewController pracuje ve dvou hlavních režimech, z nichž každý určuje, jak aplikace přistupuje k souboru. Režim se nastavuje pomocí parametru forOpeningContentTypes nebo forExporting v závislosti na úkolu.

Režim Import (forOpeningContentTypes) kopíruje vybraný soubor do sandboxu aplikace. Aplikace obdrží URL vlastní kopie souboru, přístupné pouze jí. Toto je bezpečný režim: soubor jiné aplikace není změněn a kopie je plně pod kontrolou aktuální aplikace.

Režim Export (forExporting) poskytuje URL původního souboru bez kopírování. Aplikace může soubor číst pomocí odkazu, ale změny se neukládají zpět. Tento režim se používá, když je třeba přenést soubor do jiné aplikace nebo jej odeslat e-mailem. Pro zápis změn se používá režim open s security-scoped URL.

Konfigurace pickeru a filtrování podle UTI

UTI (Uniform Type Identifier) — je systém identifikace typů obsahu v ekosystému Apple. UIDocumentPickerViewController filtruje zobrazené soubory podle pole UTI předaného prostřednictvím forOpeningContentTypes. Pokud není UTI zadáno, picker zobrazuje všechny typy souborů.

• PDF — com.adobe.pdf. Picker zobrazuje pouze dokumenty PDF.
• Obrázky — public.image. Zahrnuje JPEG, PNG, HEIC a další formáty.
• Text — public.plain-text. Zobrazuje .txt, .csv a další textové soubory.
• Audio — public.audio. Zahrnuje MP3, AAC, WAV a formáty Lossless.
• Video — public.movie. Zobrazuje MP4, MOV, AVI a další video formáty.

Pro výběr více typů se předává pole [UTType.pdf, UTType.image]. Od iOS 14 Apple doporučuje používat UTType místo řetězcových konstant. UIDocumentPickerViewController automaticky aktualizuje seznam zobrazených typů při změně vybraného poskytovatele.

Příklad kódu: výběr dokumentu ve Swiftu

Implementace UIDocumentPickerViewController ve Swiftu je minimální: vytvořte instanci ovladače s typy UTI, nastavte delegáta a zavolejte present. Po výběru souboru delegát obdrží pole URL v metodě didPickDocumentsAt. Každé URL je odkaz se zvýšeným zabezpečením (security-scoped), který vyžaduje volání 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() }
    // číst soubor z url
}

Zdroje se zvýšeným zabezpečením

URL se zvýšeným zabezpečením vyžaduje volání startAccessingSecurityScopedResource před čtením. Tato metoda informuje systém, že aplikace získává dočasný přístup k souboru mimo sandbox. Po dokončení nezapomeňte zavolat stopAccessingSecurityScopedResource, jinak může systém přístup zablokovat.

UIDocumentPickerDelegate a zpracování výsledků

UIDocumentPickerDelegate přijímá výsledky výběru souboru prostřednictvím dvou metod: didPickDocumentsAt při úspěchu a didPickDocumentsAt při zrušení. iOS automaticky volá metodu zrušení, pokud uživatel zavřel picker bez výběru.

Zpracování chyb zahrnuje kontrolu dostupnosti URL. Pokud uživatel vybral soubor z iCloud Drive, ale zařízení je offline, URL nemusí být dostupné. Doporučuje se zkontrolovat FileManager.default.isReadableFile před čtením a zobrazit uživateli srozumitelnou chybovou zprávu.

Pro iOS 14+ je k dispozici nová metoda documentPicker:didPickDocumentsAt s polem URL. Stará metoda didPickDocumentAt (jednotlivá) je zastaralá. Vždy zpracovávejte pole, i když je allowsMultipleSelection vypnuto — Apple doporučuje používat jednotný handler.

UIDocumentPickerViewController na iPadu

iPad vyžaduje speciální konfiguraci UIDocumentPickerViewController. Na iPadu se picker zobrazuje jako popover a pro správné umístění je třeba zadat sourceView. Bez sourceView může ovladač spadnout s výjimkou na iPadOS.

Pro popover se používá vlastnost popoverPresentationController. Zadejte sourceView a sourceRect pro ukotvení k tlačítku nebo buňce tabulky. Na iPhone tento kód nemá žádný vliv — iOS automaticky zobrazí picker na celou obrazovku. Od iPadOS 16 ovladač podporuje postranní panel a split view pro lepší navigaci.

Adaptivní design UIDocumentPickerViewController automaticky přepíná mezi full-screen (iPhone) a popover (iPad). Vývojář nemusí implementovat samostatné ovladače pro různá zařízení — stačí správně nakonfigurovat popoverPresentationController pro iPad.