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 框架手册