UIDocumentInteractionController — co to jest, Open In i dokumenty

Czym jest UIDocumentInteractionController?

UIDocumentInteractionController — to klasa UIKit udostępniająca systemowy interfejs do pracy z dokumentami. W przeciwieństwie do UIDocumentPickerViewController, który wybiera pliki, ten kontroler pracuje z już istniejącym plikiem aplikacji i oferuje użytkownikowi akcje: podgląd, otwarcie w innej aplikacji, drukowanie lub wysłanie.

Kontroler nie jest ViewController — nie wywołuje się go przez present. Zamiast tego wyświetla systemowe menu akcji za pomocą metody presentOptionsMenu lub presentPreview. Menu pokazuje wszystkie aplikacje zarejestrowane do obsługi danego typu pliku.

UIDocumentInteractionController jest dostępny od iOS 2.0 i jest jednym z najstarszych API do pracy z dokumentami. Mimo wieku pozostaje aktualny do implementacji funkcji Open In i wbudowanego podglądu bez korzystania z zewnętrznych bibliotek.

Tryb Preview: wbudowany podgląd dokumentów

Preview — to wbudowana przeglądarka dokumentów udostępniana przez UIDocumentInteractionController. Obsługuje PDF, obrazy, pliki tekstowe i dokumenty biurowe (w tym .doc, .xls, .ppt). Preview wyświetla się z animacją przejścia, podobną do standardowego Quick Look.

Aby uruchomić Preview, wywołaj metodę presentPreview. Kontroler wymaga delegata z implementacją metody previewControllerForDocumentInteractionController, która zwraca UIViewController do wyświetlenia dokumentu. Zazwyczaj zwraca się self lub kontroler nawigacyjny.

Wbudowany Preview nie wymaga dodatkowych frameworków ani licencji. Działa z dowolnym plikiem, którego URL został przekazany do właściwości url. Użytkownik może przewijać strony PDF, skalować obrazy i kopiować tekst z dokumentów.

Tryb Open In: przesyłanie plików między aplikacjami

Open In — kluczowa funkcja UIDocumentInteractionController. Wyświetla listę aplikacji, które mogą otworzyć dany typ pliku. Użytkownik wybiera docelową aplikację, a iOS kopiuje plik do jej piaskownicy, uruchamiając aplikację do pracy z dokumentem.

Lista aplikacji jest tworzona automatycznie na podstawie zarejestrowanych Document Type w Info.plist innych aplikacji. Jeśli aplikacja zarejestrowała obsługę PDF, pojawi się w menu Open In dla plików PDF. System pokazuje również standardowe akcje: drukowanie, wysyłanie pocztą, zapisywanie w Plikach.

Open In kopiuje plik — docelowa aplikacja otrzymuje własną kopię, więc zmiany nie są zapisywane z powrotem w oryginalnej aplikacji. Jeśli wymagana jest edycja z zapisem, użyj UIDocumentPickerViewController w trybie export z security-scoped URL.

Konfiguracja UIActivityViewController jako alternatywa

Od iOS 6 dostępny jest UIActivityViewController, który również obsługuje wysyłanie plików. W przeciwieństwie do UIDocumentInteractionController, UIActivityViewController wyświetla systemowy arkusz akcji z obsługą AirDrop, poczty, wiadomości i niestandardowych UIActivity. Do prostego wysyłania plików zaleca się UIActivityViewController jako bardziej nowoczesne API.

Przykład kodu: Open In w Swift

Implementacja Open In przez UIDocumentInteractionController wymaga zaledwie kilku linii kodu: utworzenia instancji, ustawienia URL i delegata, wywołania presentOptionsMenu. Kontroler automatycznie zbiera listę dostępnych aplikacji na podstawie typu pliku.

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

Uruchamianie Preview zamiast menu

Aby wyświetlić wbudowaną przeglądarkę zamiast menu Open In, użyj metody presentPreview. Kontroler pokaże dokument na pełnym ekranie z możliwością przewijania. Delegat musi zaimplementować metodę previewControllerForDocumentInteractionController, zwracającą UIViewController do wyświetlenia.

UIDocumentInteractionControllerDelegate i cykl życia

UIDocumentInteractionControllerDelegate zarządza wyświetlaniem i ukrywaniem menu oraz Preview. Delegat implementuje opcjonalne metody: documentInteractionControllerWillPresentOpenInMenu do animacji pojawiania się, documentInteractionControllerDidDismissOpenInMenu do czyszczenia zasobów po zamknięciu menu.

Ważna metoda dla Preview — previewControllerForDocumentInteractionController, która musi zwrócić UIViewController do wyświetlenia dokumentu. Jeśli metoda nie jest zaimplementowana lub zwraca nil, Preview nie uruchomi się. Zazwyczaj zwraca się self lub UINavigationController zawierający self.

Kontroler obsługuje również metodę documentInteractionController:didEndSendingToApplication, która jest wywoływana po pomyślnym przesłaniu pliku do innej aplikacji. Pozwala to na oczyszczenie pliku tymczasowego lub aktualizację interfejsu po powrocie do aplikacji.

Różnice względem UIDocumentPickerViewController

UIDocumentInteractionController i UIDocumentPickerViewController rozwiązują różne zadania, choć oba pracują z dokumentami. Główna różnica: UIDocumentInteractionController przesyła istniejący plik do innej aplikacji, a UIDocumentPickerViewController wybiera plik z zewnętrznego źródła dla bieżącej aplikacji.

UIDocumentInteractionController nie wymaga delegata do podstawowej pracy — menu wyświetli się nawet bez implementacji metod. UIDocumentPickerViewController bez delegata jest bezużyteczny — wynik wyboru nie zostanie przetworzony. Wybór API zależy od scenariusza: wysłanie pliku → UIDocumentInteractionController, otrzymanie pliku → UIDocumentPickerViewController.