UIDocumentInteractionController — Open In e documenti

Cos'è UIDocumentInteractionController?

UIDocumentInteractionController è una classe UIKit che fornisce un'interfaccia di sistema per lavorare con i documenti. A differenza di UIDocumentPickerViewController, che seleziona file, questo controller lavora con un file esistente dell'app e offre all'utente azioni: anteprima, apertura in un'altra app, stampa o invio.

Il controller non è un ViewController — non viene chiamato tramite present. Invece, mostra un menu di azioni di sistema tramite il metodo presentOptionsMenu o presentPreview. Il menu mostra tutte le app registrate per gestire il tipo di file specificato.

UIDocumentInteractionController è disponibile da iOS 2.0 ed è una delle API più antiche per lavorare con i documenti. Nonostante l'età, rimane rilevante per implementare la funzione Open In e l'anteprima integrata senza librerie di terze parti.

Modalità Preview: Visualizzatore documenti integrato

Preview è un visualizzatore di documenti integrato fornito da UIDocumentInteractionController. Supporta PDF, immagini, file di testo e documenti Office (inclusi .doc, .xls, .ppt). L'anteprima viene visualizzata con un'animazione di transizione simile a Quick Look standard.

Per avviare l'anteprima, chiama il metodo presentPreview. Il controller richiede un delegato che implementi il metodo previewControllerForDocumentInteractionController, che restituisce un UIViewController per visualizzare il documento. Di solito viene restituito self o un controller di navigazione.

L'anteprima integrata non richiede framework o licenze aggiuntive. Funziona con qualsiasi file il cui URL viene passato alla proprietà url. Gli utenti possono scorrere le pagine PDF, ingrandire le immagini e copiare testo dai documenti.

Modalità Open In: Trasferimento file tra app

Open In è la funzione chiave di UIDocumentInteractionController. Mostra un elenco di app che possono aprire il tipo di file specificato. L'utente seleziona un'app di destinazione e iOS copia il file nella sua sandbox, avviando l'app per lavorare con il documento.

L'elenco delle app viene generato automaticamente in base alle voci Document Type registrate in Info.plist di altre app. Se un'app ha registrato il supporto PDF, apparirà nel menu Open In per i file PDF. Il sistema mostra anche azioni standard: stampa, invio via email, salvataggio in File.

Open In copia il file — l'app di destinazione riceve una propria copia, quindi le modifiche non vengono salvate nell'app originale. Se hai bisogno di modifica con salvataggio, usa UIDocumentPickerViewController in modalità esportazione con un URL con ambito di sicurezza.

UIActivityViewController come alternativa

Da iOS 6, è disponibile UIActivityViewController, che supporta anche la condivisione di file. A differenza di UIDocumentInteractionController, UIActivityViewController mostra un foglio di attività di sistema con supporto per AirDrop, email, messaggi e UIActivity personalizzati. Per la condivisione semplice di file, si consiglia UIActivityViewController come API più moderna.

Esempio di codice: Open In in Swift

L'implementazione di Open In tramite UIDocumentInteractionController richiede solo poche righe di codice: creare un'istanza, impostare URL e delegato, chiamare presentOptionsMenu. Il controller raccoglie automaticamente l'elenco delle app disponibili in base al tipo di file.

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
        )
    }
}

Avviare l'anteprima invece del menu

Per visualizzare il visualizzatore integrato invece del menu Open In, usa il metodo presentPreview. Il controller mostrerà il documento a schermo intero con possibilità di scorrimento. Il delegato deve implementare il metodo previewControllerForDocumentInteractionController, restituendo un UIViewController per la visualizzazione.

UIDocumentInteractionControllerDelegate e ciclo di vita

UIDocumentInteractionControllerDelegate gestisce la visualizzazione e la chiusura del menu e dell'anteprima. Il delegato implementa metodi opzionali: documentInteractionControllerWillPresentOpenInMenu per l'animazione di comparsa, documentInteractionControllerDidDismissOpenInMenu per la pulizia delle risorse dopo la chiusura del menu.

Un metodo importante per l'anteprima è previewControllerForDocumentInteractionController, che deve restituire un UIViewController per visualizzare il documento. Se il metodo non è implementato o restituisce nil, l'anteprima non si avvierà. Di solito viene restituito self o un UINavigationController contenente self.

Il controller supporta anche il metodo documentInteractionController:didEndSendingToApplication, che viene chiamato dopo l'invio riuscito del file a un'altra app. Ciò consente di pulire i file temporanei o aggiornare l'interfaccia dopo il ritorno all'app.

Differenze con UIDocumentPickerViewController

UIDocumentInteractionController e UIDocumentPickerViewController risolvono compiti diversi, sebbene entrambi lavorino con i documenti. La differenza principale: UIDocumentInteractionController trasferisce un file esistente a un'altra app, mentre UIDocumentPickerViewController seleziona un file da una fonte esterna per l'app corrente.

UIDocumentInteractionController non richiede un delegato per il funzionamento di base — il menu verrà visualizzato anche senza implementare metodi. UIDocumentPickerViewController senza delegato è inutile — il risultato della selezione non verrà elaborato. La scelta dell'API dipende dallo scenario: inviare un file → UIDocumentInteractionController, ricevere un file → UIDocumentPickerViewController.