UIDocumentInteractionController — Open In e documentos

O que é UIDocumentInteractionController?

UIDocumentInteractionController é uma classe UIKit que fornece uma interface de sistema para trabalhar com documentos. Ao contrário do UIDocumentPickerViewController, que seleciona ficheiros, este controlador trabalha com um ficheiro existente da aplicação e oferece ao utilizador ações: pré-visualizar, abrir noutra aplicação, imprimir ou enviar.

O controlador não é um ViewController — não é chamado através de present. Em vez disso, exibe um menu de ações do sistema através do método presentOptionsMenu ou presentPreview. O menu mostra todas as aplicações registadas para lidar com o tipo de ficheiro fornecido.

O UIDocumentInteractionController está disponível desde o iOS 2.0 e é uma das APIs mais antigas para trabalhar com documentos. Apesar da idade, continua relevante para implementar a funcionalidade Open In e a pré-visualização incorporada sem bibliotecas de terceiros.

Modo Preview: Visualizador de documentos incorporado

Preview é um visualizador de documentos incorporado fornecido pelo UIDocumentInteractionController. Suporta PDFs, imagens, ficheiros de texto e documentos de escritório (incluindo .doc, .xls, .ppt). A pré-visualização é exibida com uma animação de transição semelhante ao Quick Look padrão.

Para iniciar a Pré-visualização, chame o método presentPreview. O controlador requer um delegado que implemente o método previewControllerForDocumentInteractionController, que retorna um UIViewController para exibir o documento. Normalmente, retorna-se self ou um controlador de navegação.

A Pré-visualização incorporada não requer estruturas ou licenças adicionais. Funciona com qualquer ficheiro cujo URL seja passado para a propriedade url. Os utilizadores podem percorrer páginas PDF, ampliar imagens e copiar texto de documentos.

Modo Open In: Transferência de ficheiros entre aplicações

Open In é a funcionalidade principal do UIDocumentInteractionController. Exibe uma lista de aplicações que podem abrir o tipo de ficheiro fornecido. O utilizador seleciona uma aplicação de destino, e o iOS copia o ficheiro para a sua sandbox, iniciando a aplicação para trabalhar com o documento.

A lista de aplicações é gerada automaticamente com base nas entradas Document Type registadas no Info.plist de outras aplicações. Se uma aplicação registou suporte para PDF, aparecerá no menu Open In para ficheiros PDF. O sistema também mostra ações padrão: imprimir, enviar por email, guardar em Ficheiros.

O Open In copia o ficheiro — a aplicação de destino recebe a sua própria cópia, pelo que as alterações não são guardadas na aplicação original. Se precisar de edição com gravação, use o UIDocumentPickerViewController no modo de exportação com um URL de âmbito de segurança.

UIActivityViewController como alternativa

Desde o iOS 6, está disponível o UIActivityViewController, que também suporta a partilha de ficheiros. Ao contrário do UIDocumentInteractionController, o UIActivityViewController mostra uma folha de atividades do sistema com suporte para AirDrop, email, mensagens e UIActivity personalizados. Para partilha simples de ficheiros, recomenda-se o UIActivityViewController como uma API mais moderna.

Exemplo de código: Open In em Swift

A implementação do Open In através do UIDocumentInteractionController requer apenas algumas linhas de código: criar uma instância, definir o URL e o delegado, chamar presentOptionsMenu. O controlador recolhe automaticamente a lista de aplicações disponíveis com base no tipo de ficheiro.

class DocumentViewController: UIViewController {

    lazy var interactionController = UIDocumentInteractionController()

    func shareFile(url: URL) {
        interactionController.url = url
        interactionController.uti = url.utiType()
        interactionController.delegate = self
        interactionController.presentOptionsMenu(
            from: self.view.bounds,
            in: self.view,
            animated: true
        )
    }
}

Iniciar a Pré-visualização em vez do menu

Para exibir o visualizador incorporado em vez do menu Open In, use o método presentPreview. O controlador mostrará o documento em ecrã inteiro com capacidade de deslocamento. O delegado deve implementar o método previewControllerForDocumentInteractionController, retornando um UIViewController para exibição.

UIDocumentInteractionControllerDelegate e ciclo de vida

UIDocumentInteractionControllerDelegate gere a exibição e o fecho do menu e da Pré-visualização. O delegado implementa métodos opcionais: documentInteractionControllerWillPresentOpenInMenu para a animação de aparecimento, documentInteractionControllerDidDismissOpenInMenu para limpeza de recursos após o fecho do menu.

Um método importante para a Pré-visualização é previewControllerForDocumentInteractionController, que deve retornar um UIViewController para exibir o documento. Se o método não for implementado ou retornar nil, a Pré-visualização não será iniciada. Normalmente, retorna-se self ou um UINavigationController contendo self.

O controlador também suporta o método documentInteractionController:didEndSendingToApplication, que é chamado após o envio bem-sucedido do ficheiro para outra aplicação. Isto permite limpar ficheiros temporários ou atualizar a interface após regressar à aplicação.

Diferenças do UIDocumentPickerViewController

UIDocumentInteractionController e UIDocumentPickerViewController resolvem tarefas diferentes, embora ambos trabalhem com documentos. A principal diferença: o UIDocumentInteractionController transfere um ficheiro existente para outra aplicação, enquanto o UIDocumentPickerViewController seleciona um ficheiro de uma fonte externa para a aplicação atual.

O UIDocumentInteractionController não requer um delegado para funcionamento básico — o menu será exibido mesmo sem implementar métodos. O UIDocumentPickerViewController sem delegado é inútil — o resultado da seleção não será processado. A escolha da API depende do cenário: enviar um ficheiro → UIDocumentInteractionController, receber um ficheiro → UIDocumentPickerViewController.