CFBundleDocumentTypes とは？役割・サブキー・書き方をmacOS/iOS別に解説

「このアプリでPDFを開けるようにしたい」「自作フォーマットのファイルをダブルクリックしたら自分のアプリが起動するようにしたい」——こうした要件を実現するのが CFBundleDocumentTypes です。
Info.plist に記述するこのキーは、アプリがどのドキュメント種別を処理できるかをシステムに宣言するためのものです。
この記事では CFBundleDocumentTypes の役割・構造・各サブキーの意味から、macOS と iOS の設定の違い、よくあるエラーの対処法まで体系的に解説します。

スポンサーリンク

CFBundleDocumentTypes とは

CFBundleDocumentTypes は、アプリが処理できるドキュメントタイプ（ファイル形式）を1つ以上システムに登録するための Info.plist キーです（Apple Developer「Core Foundation Keys」）。
iOS 3.2以降・全バージョンのmacOSで有効です。

このキーを設定することで、次のような動作が実現できます。

  • ファイルアプリ・Finderの「別のアプリで開く」一覧に自アプリが表示される
  • メールやAirDropで受け取ったファイルを自アプリに渡せるようになる
  • ファイルをダブルクリック（macOS）または外部からの openURL 呼び出し（iOS）で自アプリが起動する
  • macOS では Finder上のファイルに自アプリのカスタムアイコンを表示できる

基本構造

CFBundleDocumentTypes の値は配列（Array）で、各要素は辞書（Dictionary）です。
1つの辞書が「1ドキュメントタイプの定義」に相当します。
複数のファイル形式（例：PDF と JPEG と独自フォーマット）を同時に登録する場合は、辞書を複数並べます。

<key>CFBundleDocumentTypes</key>
<array>
    <dict>
        <!-- ドキュメントタイプ1つ分の定義 -->
        <key>CFBundleTypeName</key>
        <string>PDF Document</string>

        <key>LSItemContentTypes</key>
        <array>
            <string>com.adobe.pdf</string>
        </array>

        <key>CFBundleTypeRole</key>
        <string>Viewer</string>

        <key>LSHandlerRank</key>
        <string>Alternate</string>
    </dict>
</array>

各サブキーの詳細

CFBundleTypeName（推奨）

ドキュメントタイプの内部識別名です。
ユーザーに直接表示される名前ではなく、開発者が管理しやすい文字列を自由に設定します（Apple Developer「Core Foundation Keys」）。

<key>CFBundleTypeName</key>
<string>My App Document</string>

App Store Connect への提出時、この値が LSHandlerRank と紐付いて検証されます。
省略すると App Store Connect から警告（ITMS-90788）が出る場合があるため、必ず設定することを推奨します。

LSItemContentTypes（必須・推奨）

このアプリが処理できるUTI（Uniform Type Identifier）文字列のリストです。
複数の UTI を配列で指定でき、1つの辞書（＝1ドキュメントタイプ定義）に複数のUTIをまとめることができます。

<key>LSItemContentTypes</key>
<array>
    <string>com.adobe.pdf</string>
    <string>public.plain-text</string>
</array>

macOS 10.4以降は LSItemContentTypes を指定すると後述の CFBundleTypeExtensions や CFBundleTypeMIMETypes は無視されます。
現在は LSItemContentTypes を使うのが標準です（Apple Developer「Core Foundation Keys」）。

CFBundleTypeRole（推奨）

このアプリが対象ドキュメントに対してどのような役割を果たすかを示します。

値意味
Editor開く・保存（読み書き）ができる。Document-based appではこの値に応じてSaveコマンドが有効化される
Viewer開く（読み取り）のみできる。Saveコマンドは無効
Shellシェルやスクリプトとして機能するアプリに使用
QLGeneratorQuick Look Generator プラグイン（macOSのみ）
MDImporterSpotlight Importer プラグイン（macOSのみ）
None処理はするが「別のアプリで開く」候補としては表示されない

iOS では Editor / Viewer の2値が主に使われます。
macOS の Document-based app では、この値によって NSDocumentController がSave機能を自動的に制御します（CocoaDev「CFBundleTypeRole」）。

LSHandlerRank（必須・推奨）

このアプリが対象ドキュメントタイプの処理候補としての優先度を示します。

値意味使うケース
OwnerこのUTIの所有者。最高優先度自分が作ったUTI（UTExportedTypeDeclarationsと組み合わせる）
Default既定の処理アプリ候補として登録システム標準形式を処理する場合
Alternate代替アプリとして登録（他のアプリが優先）PDFや画像など広く使われる形式に対応する場合
None処理はするが「別のアプリで開く」候補に出ない内部的に扱うだけでユーザーに見せたくない場合

App Store Connect への提出では LSHandlerRank の設定が必須チェック項目になっており、省略すると警告（ITMS-90788）が発生します。

CFBundleTypeIconFile（macOS のみ・省略可）

macOS でFinderに表示されるドキュメントアイコンのファイル名を指定します（拡張子 .icns、省略時は自動補完）。

<key>CFBundleTypeIconFile</key>
<string>MyDocumentIcon</string>

CFBundleTypeIconFiles（iOS のみ・省略可）

iOS でファイルアプリ等に表示されるドキュメントアイコンの画像ファイル名の配列を指定します。
iOS はサイズ別に複数のPNGファイルを必要とします。

<key>CFBundleTypeIconFiles</key>
<array>
    <string>MyDoc-32</string>
    <string>MyDoc-64</string>
    <string>MyDoc-128</string>
</array>

旧来のキー（非推奨・互換性維持のみ）

以下は macOS 10.3以前との互換性のために残っているキーです。
現在は LSItemContentTypes で統一するのが正しい方法です。

キー内容
CFBundleTypeExtensions拡張子の配列（例：["pdf", "PDF"]）
CFBundleTypeMIMETypesMIMEタイプの配列（例：["application/pdf"]）
CFBundleTypeOSTypesClassic Mac OS の4文字コード（["PDF "] など）

完全な記述例

自作の独自フォーマット（Owner）を登録する例

<!-- ① 独自フォーマットの処理を宣言 -->
<key>CFBundleDocumentTypes</key>
<array>
    <dict>
        <key>CFBundleTypeName</key>
        <string>My App Document</string>

        <key>LSItemContentTypes</key>
        <array>
            <string>com.yourcompany.yourapp.document</string>
        </array>

        <key>CFBundleTypeRole</key>
        <string>Editor</string>

        <key>LSHandlerRank</key>
        <string>Owner</string>
    </dict>
</array>

<!-- ② UTIを定義・公開する（UTExportedTypeDeclarationsと組み合わせる） -->
<key>UTExportedTypeDeclarations</key>
<array>
    <dict>
        <key>UTTypeIdentifier</key>
        <string>com.yourcompany.yourapp.document</string>

        <key>UTTypeConformsTo</key>
        <array>
            <string>public.data</string>
        </array>

        <key>UTTypeTagSpecification</key>
        <dict>
            <key>public.filename-extension</key>
            <array>
                <string>mydata</string>
            </array>
        </dict>

        <key>UTTypeDescription</key>
        <string>My App Document</string>
    </dict>
</array>

他社フォーマット（PDF・画像）を閲覧のみサポートする例

<key>CFBundleDocumentTypes</key>
<array>
    <!-- PDFを閲覧できる -->
    <dict>
        <key>CFBundleTypeName</key>
        <string>PDF Document</string>

        <key>LSItemContentTypes</key>
        <array>
            <string>com.adobe.pdf</string>
        </array>

        <key>CFBundleTypeRole</key>
        <string>Viewer</string>

        <key>LSHandlerRank</key>
        <string>Alternate</string>
    </dict>

    <!-- 主要画像フォーマットをまとめて閲覧できる -->
    <dict>
        <key>CFBundleTypeName</key>
        <string>Images</string>

        <key>LSItemContentTypes</key>
        <array>
            <string>public.jpeg</string>
            <string>public.png</string>
            <string>public.tiff</string>
        </array>

        <key>CFBundleTypeRole</key>
        <string>Viewer</string>

        <key>LSHandlerRank</key>
        <string>Alternate</string>
    </dict>
</array>

iOSで必要な追加設定

iOS で CFBundleDocumentTypes を設定すると、App Store Connect から次の警告（ITMS-90737）が出る場合があります（Apple Developer Lessons「Associating a file type with an LC iOS app」）。

“By declaring the CFBundleDocumentTypes key in your app, you’ve indicated that your app is able to open documents. Please set the UISupportsDocumentBrowser key to ‘YES’ if your app uses a UIDocumentBrowserViewController. Otherwise, set the LSSupportsOpeningDocumentsInPlace key…”

対応は次のどちらかを Info.plist に追加することで解決します。

キー値意味
UISupportsDocumentBrowserYESUIDocumentBrowserViewController を使うドキュメント型アプリの場合
LSSupportsOpeningDocumentsInPlaceYES または NOドキュメントブラウザを使わない場合。YES でファイルを元の場所で直接開く、NO でInboxにコピーして開く

UTExportedTypeDeclarations との使い分け

CFBundleDocumentTypes と UTExportedTypeDeclarations はセットで使うことが多く、それぞれの役割は明確に分かれています（Apple Developer Technical Q&A「QA1959」）。

キー役割
UTExportedTypeDeclarations「このUTIはこういう形式ですよ」とシステム全体にUTIを定義・公開する宣言
CFBundleDocumentTypes「このUTIのファイルはうちのアプリで処理できます」とオープン対応を宣言

独自フォーマットを作る場合は両方を設定する必要があります。
既存のシステムUTI（com.adobe.pdf など）を開くだけであれば CFBundleDocumentTypes のみで十分です。

Xcode での設定方法

コードを直接記述しなくても、Xcode のビジュアル設定画面から同じ内容を設定できます。

  1. Xcodeでプロジェクトを開き、対象ターゲットを選択
  2. 「Info」タブを開く
  3. 「Document Types」セクションを展開し「+」ボタンで新規追加
  4. 「Name」に CFBundleTypeName、「Types」に UTI文字列（LSItemContentTypes）を入力
  5. 「Handler Rank」と「Role」をプルダウンから選択

まとめ

CFBundleDocumentTypes は、アプリが処理できるファイル形式をシステムに登録するための Info.plist キーです。
LSItemContentTypes（UTI文字列）、CFBundleTypeRole（Editor/Viewer など）、LSHandlerRank（Owner/Alternate など）の3つが基本セットで、この組み合わせによって「どのファイルを」「どのような権限で」「どの優先度で」処理するかが決まります。
自作フォーマットを登録する場合は UTExportedTypeDeclarations で UTI を定義してから CFBundleDocumentTypes と組み合わせるのが正しい手順です。
iOS では追加で LSSupportsOpeningDocumentsInPlace または UISupportsDocumentBrowser も設定する必要があります。

参考情報源:

Youtube

神話・歴史・伝承の解説チャンネル

スポンサーリンク

コメント

タイトルとURLをコピーしました