iOS Document Interaction 編程指南

關於 DocumentInteraction

iOS支持在你的app中用其餘app預覽和顯示文檔。iOS還支持文件關聯，容許其餘app經過你的程序打開文件。這些技術包括了UIKit中提供的UIDocumentInteractionController類（ UIDocumentInteractionController Class Reference)，以及Quick Look框架（Quick Look Framework Reference)。

從iOS4.2開始，Quick Look框架提供了內置的文件打印支持。若是你要定製本身的打印和拷貝行爲，你能夠本身實現documentinteraction controller委託方法來提供支持。UIDocumentInteractionController和QLPreviewController類的示例代碼，請參考DocInteraction示例工程.

預覽文檔和呈現選項菜單

若是你的app須要打開它不支持的文件，請使用UIDocumentInteractionController。一個documentinteraction controller經過Quick Look框架判斷文檔是否能被另外一個app打開和預覽。也就是說，你的app經過documentinteraction controller提供給用戶一些可選的操做。

要使用一個document interaction controller，須要如下步驟：

1.    針對每一個你想打開的文件，建立相應的UIDocumentInteractionController實例。

2.     在app的UI中提供一個表明這個文件的圖像化表示（通常，你應該顯示文件名或者圖標）。

3.    若是用戶和這個對象發生交互，例如觸摸了這個控件，則調用document interaction controller顯示一個以下的界面：

o   預覽文件的內容。

o   一個包含預覽和打開操做的菜單。你能夠經過實現某些委託方法，向菜單中加入其餘操做，好比複製、打印。

o   一個菜單，僅包含「以其它方式打開」操做。

documentinteraction controller內置了一些手勢，你能夠直接實現它們的action。

如何須要與文件交互的app均可以使用document interaction controller。這些程序絕大部分都須要從網絡下載文件。例如，email程序須要打開和預覽郵件附件。

即便是從不下載文件的app，也須要document interaction controller。 例如 ，你的app須要支持文件共享（參考「File-Sharing Support」 in iOS Technology Overview 以及DocInteraction 示例工程), 你能夠對同步到app Documents/Shared目錄下的文件使用documentinteraction controller。

建立DocumentInteraction Controller

要建立一個document interaction controller實例，用你想要打開的文件實例化它，並設置它的delegate屬性。delegate對象負責告訴document  interaction controller呈現視圖時須要的信息，以及當視圖顯示和用戶交互時要執行的動做。

如如下代碼所示。注意方法的調用者必須retain返回對象。

- (UIDocumentInteractionController *) setupControllerWithURL: (NSURL) fileURL
    usingDelegate: (id <UIDocumentInteractionControllerDelegate>) interactionDelegate {
 
    UIDocumentInteractionController *interactionController =
        [UIDocumentInteractionController interactionControllerWithURL: fileURL];
    interactionController.delegate = interactionDelegate;
 
    return interactionController;
}

建立好document interaction controller以後，能夠經過它的屬性來讀取與之關聯的文件信息，包括文件名、類型和 URL。該controllerｙ還有一個　icons 屬性，其中包含了多個 UIImage 對象,本別用於表示該文檔的多個大小的圖標。這些信息可用於UI。 

若是你想讓用戶用在其餘程序中打開這個文件，可使用controller的 annotation 屬性，將該程序所需的附加信息放在其中。固然信息的格式必須可以被該應用程序識別。例如，該屬性將被某個應用程序套件中的單個程序所用。當這個程序想與套件中的其餘程序進行交互時，就可使用annotation 屬性。當調用應用程序打開一個文件時，option 字典中會包含 annotation 的值，可使用UIApplicationLaunchOptionsAnnotationKey 做爲鍵在option字典中檢索它。

呈現 Document InteractionController

經過 Documentinteraction controller ，用戶能夠預覽該文件，或者經過彈出菜單讓用戶選擇相應的動做。

o   模式化顯示文件預覽窗口，調用 presentPreviewAnimated: 方法。

o  經過彈出菜單提示用戶選擇相應動做，調用presentOptionsMenuFromRect:inView:animated: 或者presentOptionsMenuFromBarButtonItem:animated: 方法。

o  提示用戶用其餘程序打開該文件，調用presentOpenInMenuFromRect:inView:animated: 方法或者presentOpenInMenuFromBarButtonItem:animated: 方法。

這些方法都會顯示一個視圖——要麼是預覽窗口，要麼是彈出菜單。任何一個方法的調用，都要檢查返回值。返回值爲 NO，表示這個視圖沒有任何內容，將不能顯示。例如，presentOpenInMenuFromRect:inView:animated:方法返回NO,代表已安裝的程序中沒有任何程序可以打開該文檔。

若是你要顯示預覽窗口，委託對象必須實現 documentInteractionControllerViewControllerForPreview: 方法。預覽窗口以模式窗口的形式顯示，所以須要在該方法中返回一個view controller ，做爲預覽窗口的父窗口。若是你不實現該方法，或者在該方法中返回 nil，或者你返回的 view controller 沒法呈現模式窗口，則該預覽窗口不會顯示。

document interactioncontroller 會自動解散它呈現出來的窗口。固然你也能夠調用 dismissMenuAnimated: 或dismissPreviewAnimated: 方法手動解散它 。

在示例項目 DocInteraction 中，演示瞭如何呈現一個document interaction controller（使用了手勢識別）。

 

註冊應用程序支持的文檔類型

若是你的程序能夠打開某種特定的文件類型，則你能夠經過Info.pllist 文件註冊程序所能打開的文檔類型。當其餘程序向系統詢問哪些程序能夠識別該類型的文件時，你的程序將會被列到選項菜單中，供用戶選擇。

相關章節: 「註冊應用程序支持的文件類型」

註冊應用程序支持的文件類型

若是你的程序可以打開某種文件，你能夠向系統進行註冊。這會運行其餘程序經過 iOS 的 document interaction 技術提供給用戶一個選擇，從而調用你的程序處理這些文件。

這須要在程序的Info.plist 文件中包含 CFBundleDocumentTypes 鍵 (查看 「CoreFoundation Keys」) 。系統將該鍵中包含的內容進行登記，這樣其餘程序就能夠經過 document interaction controller 訪問到這些信息。

CFBundleDocumentTypes 鍵是一個dictionary數組，一個dictionary表示了一個指定的文檔類型。一個文檔類型一般與某種文件類型是一一對應的。可是，若是你的程序對多個文件類型採用一樣的處理方式，你也能夠把這些類型都分紅一個組，統一視做一個文檔類型。例如，你的程序中使用到的本地文檔類型，有一個是舊格式的，還有一個新格式（彷佛是影射微軟office文檔），則你能夠將兩者分紅一組，都放到同一個文檔類型下。這樣，舊格式和新格式的文件都將顯示爲同一個文檔類型，並以一樣的方式打開。

CFBundleDocumentTypes 數組中的每一個dictionary 可能包含如下鍵：

o        CFBundleTypeName 指定文檔類型名稱。

o       CFBundleTypeIconFiles 是一個數組，包含多個圖片文件名，用於做爲該文檔的圖標。

o       LSItemContentTypes 是一個數組，包含多個 UTI 類型的字符串。UTI 類型是本文檔類型（組）所包含的文件類型。

o       LSHandlerRank 表示應用程序是「擁有」仍是僅僅是「打開」這種類型而已。

在應用程序的角度而言，一個文檔類型其實就是一種文件類型（或者多個文件類型），該程序將一個文檔類型的文件都視做一樣的東西對待。例如，一個圖片處理程序可能將各類圖片文件都當作不一樣的文檔類型，這樣便於根據每一個類型進行相應的優化。可是，對於字處理程序來講，它並不關心真正的圖形格式，它把全部的圖片格式都做爲一個文檔類型對待。

下表列出了Info.plist 中的一個 CFBundleTypeName 示例。

LSItemContentTypes 表示與文件格式對應的 UTI，CFBundleTypeIconFiles 指定了該類型所用的圖標資源。

表 1  自定義文件格式的文檔類型

<dict>
   <key>CFBundleTypeName</key>
   <string>My File Format</string>
   <key>CFBundleTypeIconFiles</key>
       <array>
           <string>MySmallIcon.png</string>
           <string>MyLargeIcon.png</string>
       </array>
   <key>LSItemContentTypes</key>
       <array>
           <string>com.example.myformat</string>
       </array>
   <key>LSHandlerRank</key>
   <string>Owner</string>
</dict>

 關於CFBundleDocumentTypes 鍵的更多信息, 可參考 InfoPlist 鍵參考。

在其餘應用程序中打開文件

系統可能會請求某個程序打開某種文件，並呈現打開選項菜單給用戶。最爲常見的狀況是，某個應用程序遇到了你的程序註冊了支持的文件類型。這樣，系統會將文件的 URL 傳遞給你的應用程序，並將它放入前臺。

相關章節: 「打開支持的文件類型」

打開支持的文件類型

系統可能會請求某個程序打開某種文件，並呈現給用戶。一般這發生在某個應用程序調用 document interaction controller 去處理某個文件的時候。你能夠在應用程序委託的

 application:didFinishLaunchingWithOptions: 方法中得到該文件的信息。若是你的程序要處理某些自定義的文件類型，你必須實現這個委託方法（而不是applicationDidFinishLaunching:  方法) 並用這個方法啓動應用程序。

 

application:didFinishLaunchingWithOptions: 方法的 option 參數包含了要打開的文件的相關信息。尤爲須要在程序中關心下列鍵：

o        UIApplicationLaunchOptionsURLKey 包含了該文件的NSURL.

o       UIApplicationLaunchOptionsSourceApplicationKey 包含了發送請求的應用程序的 Bundle ID。

o        UIApplicationLaunchOptionsSourceApplicationKey 包含了源程序向目標程序傳遞的與該文件相關的屬性列表對象。

若是 UIApplicationLaunchOptionsURLKey 鍵存在，你的程序應當當即用該 URL 打開該文件並將內容呈現給用戶。其餘鍵可用於收集與打開的文件相關的參數和信息。

 

Quick Look Previews 中的預覽及打印

要想得到更多的文件預覽功能，你能夠直接使用 Quick Look 框架。你能夠選擇呈現預覽窗口時的動畫風格，並能夠想預覽單個文件同樣預覽多個文件。QuickLook preview controller 還內置了所支持的文件類型的 AirPrint 打印。

相關章節: 「使用 Quick Look 框架」

使用 Quick Look 框架

 

Quick Look 框架提供了加強的預覽功能。該框架主要提供了 QLPreviewController 類。該類依賴於委託對象響應預覽動做，以及一個用於提供預覽文件的數據源。

從 iOS 4.2 開始，QuickLook preview controller 提供了包含了一個 action 按鈕（即打印按鈕）的預覽視圖。對於 controller 能預覽的文件，action按鈕可以打印該文檔。從而不須要你編寫任何打印代碼。

經過如下方式顯示一個Quick Look preview controller:

o        經過導航控制器，將預覽窗口以「push 方式」顯示。

o        經過 UIViewController 的 presentModalViewController:animated:方法以模態窗口的方式顯示。

o       顯示一個document interaction controller(如 「預覽及打開文件」 中所述）。用戶能夠從document interaction controller 的選項菜單中選擇「Quick Look」，便可打開一個 QuickLook preview controller。

顯示 Quick Lookpreview controller 時，請選擇適合於你的應用程序的外觀和導航方式。若是你的程序未使用導航條，使用一個全屏的模態的 Quick Lookpreview controller 是合適的。若是你的程序使用了「iPhone 式」的導航，則採用 push 方式呈現預覽窗口是合適的。

預覽窗口中會包括一個標題，顯示文件 URL 的最後一段路徑。若是要重載標題，能夠定製PreviewItem 類，並實現QLPreviewItem 協議中的 previewItemTitle方法。

Quick Look previewcontroller 可以預覽下列文件：

o        iWork 文檔

o        Microsoft Office 文檔(Office ‘97 之後版本)

o        Rich Text Format (RTF) 文檔

o        PDF 文檔

o        圖片

o       文本文件，其 uniform type identifier (UTI)  在 public.text 文件中定義 (查看UniformType Identifiers 參考)

o        Comma-separated value (csv) 文件

使用 QuickLook preview controller，必須指定數據源對象（即實現 QLPreviewControllerDataSource 協議，請查看QLPreviewControllerDataSource協議參考）。數據源爲 Quick Look preview controller 提供預覽對象（preivew item），及指明它們的數量以便在一個預覽導航列表中包含它們。在這個列表中包含多個對象，在模態預覽窗口（全屏顯示）顯示了導航箭頭，以便用戶在多個預覽對象間切換。對於用導航控制器「push方式」顯示的QuickLook preview controller，你能夠在導航條上提供按鈕以便在預覽對象列表見切換。

Quick Look framework 的具體介紹，見 iOSQuick Look 框架手冊