UIDocumentPickerViewController — o que é, trabalho com documentos no iOS

O que é UIDocumentPickerViewController?

UIDocumentPickerViewController é um controlador UIKit que fornece uma interface de sistema para selecionar documentos. Faz parte do framework UIKit e está disponível desde o iOS 8. O controlador exibe um navegador de arquivos que inclui armazenamento local, iCloud Drive e serviços de nuvem de terceiros registrados.

O controlador funciona de forma assíncrona: após chamar present, o usuário vê uma caixa de diálogo do sistema, seleciona um arquivo e o resultado é retornado através do delegate. O aplicativo não requer permissões especiais para acessar o arquivo selecionado — o seletor do sistema fornece automaticamente acesso temporário à URI.

UIDocumentPickerViewController suporta iPad através de UIPopoverPresentationController e uma interface adaptativa para iPhone. Desde o iOS 14, o controlador recebeu um design atualizado e suporte à navegação com sidebar no iPadOS.

Modos de operação: import e export

UIDocumentPickerViewController opera em dois modos principais, cada um determina como o aplicativo acessa o arquivo. O modo é definido através do parâmetro forOpeningContentTypes ou forExporting dependendo da tarefa.

Import mode (forOpeningContentTypes) copia o arquivo selecionado para o sandbox do aplicativo. O aplicativo recebe uma URL para sua própria cópia do arquivo, acessível apenas por ele. Este é um modo seguro: o arquivo de outro aplicativo não é modificado e a cópia é totalmente controlada pelo aplicativo atual.

Export mode (forExporting) fornece uma URL para o arquivo original sem copiá-lo. O aplicativo pode ler o arquivo através do link, mas as alterações não são salvas. Este modo é usado quando é necessário transferir um arquivo para outro aplicativo ou enviá-lo por e-mail. Para escrever alterações, é usado o modo open com scoped security-scoped URL.

Configuração do picker e filtragem por UTI

UTI (Uniform Type Identifier) é um sistema de identificação de tipos de conteúdo no ecossistema Apple. UIDocumentPickerViewController filtra os arquivos exibidos de acordo com o array de UTI passado através de forOpeningContentTypes. Se nenhuma UTI for especificada, o picker mostra todos os tipos de arquivos.

• PDF — com.adobe.pdf. O picker mostra apenas documentos PDF.
• Imagens — public.image. Inclui JPEG, PNG, HEIC e outros formatos.
• Texto — public.plain-text. Exibe arquivos .txt, .csv e outros.
• Áudio — public.audio. Inclui MP3, AAC, WAV e formatos Lossless.
• Vídeo — public.movie. Mostra MP4, MOV, AVI e outros formatos de vídeo.

Para selecionar vários tipos, passe um array [UTType.pdf, UTType.image]. Desde o iOS 14, a Apple recomenda usar UTType em vez de constantes de string. UIDocumentPickerViewController atualiza automaticamente a lista de tipos exibidos quando o provedor selecionado muda.

Exemplo de código: seleção de documento em Swift

Implementação do UIDocumentPickerViewController em Swift é mínima: criar uma instância do controlador com tipos UTI, definir o delegate e chamar present. Após a seleção do arquivo, o delegate recebe um array de URLs no método didPickDocumentsAt. Cada URL é uma referência security-scoped que requer chamar 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() }
    // ler arquivo da url
}

Recursos Security-Scoped

Uma URL security-scoped requer chamar startAccessingSecurityScopedResource antes da leitura. Este método informa ao sistema que o aplicativo está obtendo acesso temporário a um arquivo fora da sandbox. Após terminar, sempre chame stopAccessingSecurityScopedResource, caso contrário o sistema pode bloquear o acesso.

UIDocumentPickerDelegate e tratamento de resultados

UIDocumentPickerDelegate recebe os resultados da seleção de arquivos através de dois métodos: didPickDocumentsAt em caso de sucesso e didPickDocumentsAt em caso de cancelamento. O iOS chama automaticamente o método de cancelamento se o usuário fechar o picker sem fazer uma seleção.

O tratamento de erros inclui verificar a disponibilidade da URL. Se o usuário selecionou um arquivo do iCloud Drive mas o dispositivo está offline, a URL pode estar indisponível. Recomenda-se verificar FileManager.default.isReadableFile antes de ler e mostrar ao usuário uma mensagem de erro clara.

Para iOS 14+, um novo método documentPicker:didPickDocumentsAt com um array de URLs está disponível. O método antigo didPickDocumentAt (único) está obsoleto. Sempre trate o array, mesmo que allowsMultipleSelection esteja desativado — a Apple recomenda usar um único manipulador.

UIDocumentPickerViewController no iPad

iPad requer uma configuração especial do UIDocumentPickerViewController. No iPad, o picker é exibido como um popover e precisa especificar um sourceView para posicionamento correto. Sem sourceView, o controlador pode falhar com uma exceção no iPadOS.

Para o popover, a propriedade popoverPresentationController é usada. Especifique sourceView e sourceRect para ancorá-lo a um botão ou célula de tabela. No iPhone, este código não tem efeito — o iOS exibe automaticamente o picker em tela cheia. Desde o iPadOS 16, o controlador suporta sidebar e split view para navegação melhorada.

O design adaptativo do UIDocumentPickerViewController alterna automaticamente entre tela cheia (iPhone) e popover (iPad). O desenvolvedor não precisa implementar controladores separados para diferentes dispositivos — basta configurar corretamente o popoverPresentationController para iPad.