iOS Document Interaction 編程指南

原文：http://developer.apple.com/library/ios/#documentation/FileManagement/Conceptual/DocumentInteraction_TopicsForIOS/Introduction/Introduction.html

關於 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 ，使用者可以預覽該檔案，或者通過快顯功能表讓使用者選擇相應的動作。

·      模式化顯示檔案預覽視窗，調用 presentPreviewAnimated: 方法。

·      通過快顯功能表提示使用者選擇相應動作，調用presentOptionsMenuFromRect:inView:animated: 或者presentOptionsMenuFromBarButtonItem:animated: 方法。

·      提示使用者用其他程式開啟該檔案，調用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 可能包含以下鍵：

·      CFBundleTypeName 指定文件類型名稱。

·      CFBundleTypeIconFiles 是一個數組，包含多個圖片檔案名稱，用於作為該文檔的表徵圖。

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

·      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 參數包含了要開啟的檔案的相關資訊。尤其需要在程式中關心下列鍵：

·      UIApplicationLaunchOptionsURLKey 包含了該檔案的NSURL.

·      UIApplicationLaunchOptionsSourceApplicationKey 包含了發送請求的應用程式的 Bundle ID。

·      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:

·      通過導航控制器，將預覽視窗以“push 方式”顯示。

·      通過 UIViewController 的 presentModalViewController:animated:方法以模態視窗的方式顯示。

·      顯示一個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 能夠預覽下列檔案：

·      iWork 文檔

·      Microsoft Office 文檔(Office ‘97 以後版本)

·      Rich Text Format (RTF) 文檔

·      PDF 文檔

·      圖片

·      文字檔，其 uniform type identifier (UTI)  在 public.text 檔案中定義 (查看UniformType Identifiers 參考)

·      Comma-separated value (csv) 檔案

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

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