UIDocumentPickerViewController — 概要、iOSでのドキュメント操作

UIDocumentPickerViewController とは？

UIDocumentPickerViewController は、ドキュメントを選択するためのシステムインターフェースを提供するUIKitコントローラーです。UIKit フレームワークの一部であり、iOS 8 から利用可能です。このコントローラーは、ローカルストレージ、iCloud Drive、および登録されたサードパーティのクラウドサービスを含むファイルブラウザを表示します。

コントローラーは非同期で動作します：present を呼び出すと、ユーザーはシステムダイアログを表示し、ファイルを選択し、結果がデリゲートを通じて返されます。アプリは選択したファイルにアクセスするための特別な権限を必要としません — システムピッカーが自動的にURIへの一時的なアクセスを提供します。

UIDocumentPickerViewController はUIPopoverPresentationControllerを介して iPad をサポートし、iPhone用のアダプティブインターフェースを提供します。iOS 14 以降、コントローラーは更新されたデザインとiPadOSでのサイドバーナビゲーションのサポートを受けています。

動作モード：import と export

UIDocumentPickerViewController は2つの主要モードで動作し、それぞれアプリがファイルにアクセスする方法を決定します。モードはタスクに応じて forOpeningContentTypes または forExporting パラメータを通じて設定されます。

Import mode (forOpeningContentTypes) は選択したファイルをアプリのサンドボックスにコピーします。アプリはファイルの自身のコピーへのURLを受け取り、そのコピーはアプリのみがアクセスできます。これは安全なモードです：他のアプリのファイルは変更されず、コピーは現在のアプリによって完全に制御されます。

Export mode (forExporting) はコピーせずに元のファイルへのURLを提供します。アプリはリンクを介してファイルを読み取れますが、変更は保存されません。このモードは、ファイルを別のアプリに転送するか、メールで送信する必要がある場合に使用されます。変更を書き込むには、scoped security-scoped URL とともに open モードが使用されます。

ピッカーの設定とUTIフィルタリング

UTI（Uniform Type Identifier） はAppleエコシステムにおけるコンテンツタイプ識別システムです。UIDocumentPickerViewController は forOpeningContentTypes を通じて渡されたUTI配列に従って表示されるファイルをフィルタリングします。UTIが指定されていない場合、ピッカーはすべてのファイルタイプを表示します。

• PDF — com.adobe.pdf。ピッカーはPDFドキュメントのみを表示します。
• 画像 — public.image。JPEG、PNG、HEICおよびその他の形式を含みます。
• テキスト — public.plain-text。.txt、.csvおよびその他のテキストファイルを表示します。
• オーディオ — public.audio。MP3、AAC、WAVおよびLossless形式を含みます。
• ビデオ — public.movie。MP4、MOV、AVIおよびその他のビデオ形式を表示します。

複数のタイプを選択するには、配列 [UTType.pdf, UTType.image] を渡します。iOS 14 以降、Appleは文字列定数の代わりに UTType を使用することを推奨しています。UIDocumentPickerViewController は、選択されたプロバイダーが変更されると、表示されるタイプのリストを自動的に更新します。

コード例：Swiftでのドキュメント選択

実装 SwiftでのUIDocumentPickerViewController は最小限です：UTIタイプでコントローラインスタンスを作成し、デリゲートを設定してpresentを呼び出します。ファイルが選択されると、デリゲートは didPickDocumentsAt メソッドでURLの配列を受け取ります。各URLはセキュリティスコープの参照であり、startAccessingSecurityScopedResource を呼び出す必要があります。

let picker = UIDocumentPickerViewController(
    forOpeningContentTypes: [.pdf, .image],
    asCopy: true
)
picker.delegate = self
picker.allowsMultipleSelection = false
present(picker, animated: true)

// MARK: - UIDocumentPickerDelegate
func documentPicker(
    _ controller: UIDocumentPickerViewController,
    didPickDocumentsAt urls: [URL]
) {
    guard let url = urls.first else { return }
    url.startAccessingSecurityScopedResource()
    defer { url.stopAccessingSecurityScopedResource() }
    // urlからファイルを読み取る
}

Security-Scoped リソース

セキュリティスコープのURLは、読み取り前に startAccessingSecurityScopedResource を呼び出す必要があります。このメソッドは、アプリがサンドボックス外のファイルに一時的なアクセスを取得していることをシステムに通知します。終了後は必ず stopAccessingSecurityScopedResource を呼び出してください。そうしないと、システムがアクセスをブロックする可能性があります。

UIDocumentPickerDelegate と結果の処理

UIDocumentPickerDelegate は、2つのメソッドを通じてファイル選択結果を受け取ります：成功時の didPickDocumentsAt とキャンセル時の didPickDocumentsAt です。ユーザーが選択せずにピッカーを閉じた場合、iOSは自動的にキャンセルメソッドを呼び出します。

エラー処理にはURLの利用可能性の確認が含まれます。ユーザーがiCloud Driveからファイルを選択したがデバイスがオフラインの場合、URLが利用できない可能性があります。読み取り前に FileManager.default.isReadableFile を確認し、ユーザーに明確なエラーメッセージを表示することをお勧めします。

iOS 14+ では、URLの配列を持つ新しいメソッド documentPicker:didPickDocumentsAt が利用可能です。古いメソッド didPickDocumentAt（単一）は非推奨です。allowsMultipleSelection が無効でも常に配列を処理してください — Appleは単一のハンドラーを使用することを推奨しています。

iPadでのUIDocumentPickerViewController

iPad ではUIDocumentPickerViewController の特別な設定が必要です。iPadでは、ピッカーはポップオーバーとして表示され、正しい配置のためにsourceViewを指定する必要があります。sourceViewがないと、コントローラーはiPadOSで例外によりクラッシュする可能性があります。

ポップオーバーには、popoverPresentationController プロパティが使用されます。sourceViewとsourceRectを指定して、ボタンやテーブルセルにアンカーします。iPhoneでは、このコードは効果がありません — iOSは自動的にピッカーを全画面表示します。iPadOS 16 以降、コントローラーは改善されたナビゲーションのためにサイドバーと分割ビューをサポートしています。

UIDocumentPickerViewController のアダプティブデザインは、全画面（iPhone）とポップオーバー（iPad）を自動的に切り替えます。開発者は異なるデバイス用に個別のコントローラーを実装する必要はありません — iPad用にpopoverPresentationControllerを正しく設定するだけで十分です。