UIDocumentPickerViewController — qué es, trabajo con documentos en iOS

¿Qué es UIDocumentPickerViewController?

UIDocumentPickerViewController es un controlador UIKit que proporciona una interfaz de sistema para seleccionar documentos. Forma parte del framework UIKit y está disponible desde iOS 8. El controlador muestra un navegador de archivos que incluye almacenamiento local, iCloud Drive y servicios en la nube de terceros registrados.

El controlador funciona de forma asincrónica: después de llamar a present, el usuario ve un diálogo del sistema, selecciona un archivo y el resultado se devuelve a través del delegado. La aplicación no requiere permisos especiales para acceder al archivo seleccionado — el selector del sistema proporciona automáticamente acceso temporal a la URI.

UIDocumentPickerViewController admite iPad a través de UIPopoverPresentationController y una interfaz adaptable para iPhone. Desde iOS 14, el controlador ha recibido un diseño actualizado y soporte de navegación con sidebar en iPadOS.

Modos de funcionamiento: import y export

UIDocumentPickerViewController funciona en dos modos principales, cada uno determina cómo la aplicación accede al archivo. El modo se establece mediante el parámetro forOpeningContentTypes o forExporting según la tarea.

Import mode (forOpeningContentTypes) copia el archivo seleccionado al sandbox de la aplicación. La aplicación recibe una URL a su propia copia del archivo, accesible solo para ella. Este es un modo seguro: el archivo de otra aplicación no se modifica y la copia está completamente controlada por la aplicación actual.

Export mode (forExporting) proporciona una URL al archivo original sin copiarlo. La aplicación puede leer el archivo mediante el enlace, pero los cambios no se guardan. Este modo se usa cuando se necesita transferir un archivo a otra aplicación o enviarlo por correo. Para escribir cambios se usa el modo open con scoped security-scoped URL.

Configuración del picker y filtrado por UTI

UTI (Uniform Type Identifier) es un sistema de identificación de tipos de contenido en el ecosistema Apple. UIDocumentPickerViewController filtra los archivos mostrados según el array de UTI pasado mediante forOpeningContentTypes. Si no se especifica UTI, el selector muestra todos los tipos de archivos.

• PDF — com.adobe.pdf. El selector muestra solo documentos PDF.
• Imágenes — public.image. Incluye JPEG, PNG, HEIC y otros formatos.
• Texto — public.plain-text. Muestra archivos .txt, .csv y otros.
• Audio — public.audio. Incluye MP3, AAC, WAV y formatos Lossless.
• Video — public.movie. Muestra MP4, MOV, AVI y otros formatos de video.

Para seleccionar varios tipos se pasa un array [UTType.pdf, UTType.image]. Desde iOS 14, Apple recomienda usar UTType en lugar de constantes de cadena. UIDocumentPickerViewController actualiza automáticamente la lista de tipos mostrados al cambiar el proveedor seleccionado.

Ejemplo de código: selección de documento en Swift

Implementación de UIDocumentPickerViewController en Swift es mínima: crear una instancia del controlador con tipos UTI, establecer el delegado y llamar a present. Después de seleccionar el archivo, el delegado recibe un array de URLs en el método didPickDocumentsAt. Cada URL es una referencia security-scoped que requiere llamar a 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() }
    // leer archivo desde url
}

Recursos Security-Scoped

Una URL security-scoped requiere llamar a startAccessingSecurityScopedResource antes de leer. Este método indica al sistema que la aplicación obtiene acceso temporal a un archivo fuera del sandbox. Al finalizar, siempre llame a stopAccessingSecurityScopedResource, de lo contrario el sistema podría bloquear el acceso.

UIDocumentPickerDelegate y manejo de resultados

UIDocumentPickerDelegate recibe los resultados de selección de archivos a través de dos métodos: didPickDocumentsAt en caso de éxito y didPickDocumentsAt en caso de cancelación. iOS llama automáticamente al método de cancelación si el usuario cierra el selector sin hacer una selección.

El manejo de errores incluye verificar la disponibilidad de la URL. Si el usuario seleccionó un archivo de iCloud Drive pero el dispositivo está desconectado, la URL puede no estar disponible. Se recomienda verificar FileManager.default.isReadableFile antes de leer y mostrar al usuario un mensaje de error claro.

Para iOS 14+ está disponible un nuevo método documentPicker:didPickDocumentsAt con un array de URLs. El método antiguo didPickDocumentAt (individual) está obsoleto. Siempre maneje el array, incluso si allowsMultipleSelection está desactivado — Apple recomienda usar un solo manejador.

UIDocumentPickerViewController en iPad

iPad requiere una configuración especial de UIDocumentPickerViewController. En iPad, el selector se muestra como un popover y necesita especificar un sourceView para un posicionamiento correcto. Sin sourceView, el controlador puede fallar con una excepción en iPadOS.

Para el popover se usa la propiedad popoverPresentationController. Especifique sourceView y sourceRect para anclarlo a un botón o celda de tabla. En iPhone este código no tiene efecto — iOS muestra automáticamente el selector en pantalla completa. Desde iPadOS 16, el controlador admite sidebar y split view para una navegación mejorada.

El diseño adaptable de UIDocumentPickerViewController cambia automáticamente entre pantalla completa (iPhone) y popover (iPad). El desarrollador no necesita implementar controladores separados para diferentes dispositivos — basta con configurar correctamente el popoverPresentationController para iPad.