UIDocumentPickerViewController — dokumentumok kezelése iOS-ben

Mi az a UIDocumentPickerViewController?

UIDocumentPickerViewController — egy UIKit vezérlő, amely rendszerfelületet biztosít dokumentumok kiválasztásához. A UIKit keretrendszer része, és iOS 8 óta érhető el. A vezérlő egy fájlböngészőt jelenít meg, amely magában foglalja a helyi tárhelyet, iCloud Drive-ot és a regisztrált külső felhőszolgáltatásokat.

A vezérlő aszinkron módon működik: a present meghívása után a felhasználó egy rendszerpárbeszédablakot lát, kiválasztja a fájlt, és az eredmény a delegate-en keresztül kerül visszaadásra. Az alkalmazásnak nincs szüksége különleges engedélyekre a kiválasztott fájl eléréséhez — a rendszerválasztó automatikusan ideiglenes hozzáférést biztosít az URI-hoz.

A UIDocumentPickerViewController támogatja az iPad-et a UIPopoverPresentationController-en keresztül és adaptív felületet iPhone-hoz. iOS 14-től kezdve a vezérlő frissített dizájnt és oldalsáv navigációt kapott iPadOS-ben.

Munkamódok: import és export

UIDocumentPickerViewController két fő módban működik, amelyek mindegyike meghatározza, hogy az alkalmazás hogyan fér hozzá a fájlhoz. A mód a forOpeningContentTypes vagy forExporting paraméteren keresztül állítható be a feladattól függően.

Import mód (forOpeningContentTypes) a kiválasztott fájlt az alkalmazás homokozójába másolja. Az alkalmazás megkapja a fájl saját másolatának URL-jét, amely csak számára elérhető. Ez egy biztonságos mód: más alkalmazás fájlja nem módosul, és a másolatot teljes mértékben az aktuális alkalmazás irányítja.

Export mód (forExporting) másolás nélkül biztosít URL-t az eredeti fájlhoz. Az alkalmazás olvashatja a fájlt a linken keresztül, de a változtatások nem kerülnek visszamentésre. Ezt a módot akkor használjuk, amikor egy fájlt másik alkalmazásba kell átvinni vagy e-mailben elküldeni. A változtatások írásához az open módot használjuk security-scoped URL-lel.

A picker konfigurálása és szűrés UTI szerint

UTI (Uniform Type Identifier) — a tartalomtípusok azonosítására szolgáló rendszer az Apple ökoszisztémájában. A UIDocumentPickerViewController a megjelenített fájlokat a forOpeningContentTypes segítségével átadott UTI tömb alapján szűri. Ha nincs UTI megadva, a picker minden fájltípust megjelenít.

• PDF — com.adobe.pdf. A picker csak PDF dokumentumokat jelenít meg.
• Képek — public.image. Tartalmazza a JPEG, PNG, HEIC és más formátumokat.
• Szöveg — public.plain-text. .txt, .csv és más szövegfájlokat jelenít meg.
• Audió — public.audio. Tartalmazza az MP3, AAC, WAV és Lossless formátumokat.
• Videó — public.movie. MP4, MOV, AVI és más videoformátumokat jelenít meg.

Több típus kiválasztásához a [UTType.pdf, UTType.image] tömb kerül átadásra. iOS 14-től kezdve az Apple a UTType használatát javasolja a karakterlánc-konstansok helyett. A UIDocumentPickerViewController automatikusan frissíti a megjelenített típusok listáját a kiválasztott szolgáltató változásakor.

Kódpélda: dokumentum kiválasztása Swift-ben

Implementáció A UIDocumentPickerViewController implementációja Swift-ben minimális: hozz létre egy vezérlőpéldányt UTI típusokkal, állítsd be a delegate-et és hívd meg a present-et. A fájl kiválasztása után a delegate egy URL tömböt kap a didPickDocumentsAt metódusban. Minden URL egy security-scoped link, amely a startAccessingSecurityScopedResource meghívását igényli.

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() }
    // fájl olvasása url-ből
}

Security-scoped erőforrások

A security-scoped URL megköveteli a startAccessingSecurityScopedResource meghívását olvasás előtt. Ez a metódus értesíti a rendszert, hogy az alkalmazás ideiglenes hozzáférést szerez egy fájlhoz a homokozón kívül. A munka befejezése után feltétlenül hívd meg a stopAccessingSecurityScopedResource-t, különben a rendszer blokkolhatja a hozzáférést.

UIDocumentPickerDelegate és az eredmények kezelése

UIDocumentPickerDelegate két metóduson keresztül kapja meg a fájlkiválasztás eredményeit: didPickDocumentsAt siker esetén és didPickDocumentsAt megszakításkor. Az iOS automatikusan meghívja a megszakítás metódust, ha a felhasználó kiválasztás nélkül zárta be a pickert.

A hibakezelés magában foglalja az URL elérhetőségének ellenőrzését. Ha a felhasználó iCloud Drive-ból választott fájlt, de az eszköz offline, az URL nem biztos, hogy elérhető. Javasolt a FileManager.default.isReadableFile ellenőrzése olvasás előtt, és egy érthető hibaüzenet megjelenítése a felhasználónak.

iOS 14+ esetén elérhető az új documentPicker:didPickDocumentsAt metódus URL tömbökkel. A régi didPickDocumentAt (egyetlen) metódus elavult. Mindig a tömböt kezeld, még akkor is, ha az allowsMultipleSelection ki van kapcsolva — az Apple egységes handler használatát javasolja.

UIDocumentPickerViewController iPad-en

iPad speciális konfigurációt igényel a UIDocumentPickerViewController számára. iPad-en a picker popoverként jelenik meg, és meg kell adni a sourceView-t a megfelelő pozicionáláshoz. SourceView nélkül a vezérlő összeomolhat kivétellel iPadOS-en.

A popoverhez a popoverPresentationController tulajdonságot használjuk. Add meg a sourceView-t és sourceRect-t a gombhoz vagy táblázatcellához rögzítéshez. iPhone-on ennek a kódnak nincs hatása — az iOS automatikusan teljes képernyőn jeleníti meg a pickert. iPadOS 16-tól kezdve a vezérlő támogatja az oldalsávot és a split view-t a jobb navigáció érdekében.

A UIDocumentPickerViewController adaptív dizájnja automatikusan vált a full-screen (iPhone) és popover (iPad) között. A fejlesztőnek nem kell külön vezérlőket implementálnia különböző eszközökhöz — elég a popoverPresentationController helyes konfigurálása iPad-hez.