【Swift】FileDocument プロトコルとは？使い方や必須メソッドをわかりやすく解説！

2025年8月23日 2025年8月23日

SwiftUIでユーザーによるファイルの保存やエクスポートに欠かせないのが FileDocument プロトコルです。

アプリ内のデータを外部ファイルとして保存したり、読み込んだファイルを画面に反映したりと、ファイルベースの操作をSwiftUIで実現するための基本となる仕組みです。

この記事では FileDocument の基本的な意味や使い方、必須のメソッド、活用シーン、注意点までをわかりやすく丁寧に解説します。

FileDocument とは？

FileDocument は SwiftUI においてファイル入出力（I/O）を抽象化するためのプロトコルです。

このプロトコルに準拠することで、独自のデータ構造をユーザーが保存・読み込み可能な形式として扱えるようになります。

たとえば、テキストファイルやJSON、画像、CSVなど任意のデータを、SwiftUIの .fileImporter() や .fileExporter() と組み合わせて読み書きできます。

UIKitで言うところの UIDocument に相当する存在ですが、SwiftUIではよりシンプルに実装できます。

FileDocument で実装が必要なメソッドとプロパティ

FileDocument を使うには、次のメソッドやプロパティを実装する必要があります。

要素	目的
`static var readableContentTypes: [UTType]`	対応するファイルの種類（UTType）を指定
`init(configuration: ReadConfiguration)`	ファイルを読み込んでデータを初期化する
`func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper`	データをファイルに書き出すロジックを定義

特に読み込み用 init(configuration:) と、書き込み用の fileWrapper(configuration:) が重要です。

どちらもバイナリやテキストの形式に応じて柔軟に対応可能です。

具体例①：テキストファイルの読み書きを定義する FileDocument

下記サンプルでは、.txt（プレーンテキスト）形式のファイルを読み書きするための TextDocument 構造体を定義しています。

FileDocument プロトコルに準拠することで、SwiftUIの .fileImporter() や .fileExporter() と連携。

ファイル読み込み時にはテキストを取り込み、書き出し時には文字列を保存する処理を実現しています。

import SwiftUI
import UniformTypeIdentifiers

struct TextDocument: FileDocument {
    static var readableContentTypes: [UTType] { [.plainText] }
    var text: String

    init(text: String = "") {
        self.text = text
    }

    init(configuration: ReadConfiguration) throws {
        if let data = configuration.file.regularFileContents,
           let string = String(data: data, encoding: .utf8) {
            self.text = string
        } else {
            throw CocoaError(.fileReadCorruptFile)
        }
    }

    func fileWrapper(configuration: WriteConfiguration) throws -&gt; FileWrapper {
        let data = Data(text.utf8)
        return FileWrapper(regularFileWithContents: data)
    }
}

import SwiftUI

import UniformTypeIdentifiers

struct TextDocument: FileDocument {

static var readableContentTypes: [UTType] { [.plainText] }

var text: String

init(text: String = "") {

self.text = text

}

init(configuration: ReadConfiguration) throws {

if let data = configuration.file.regularFileContents,

let string = String(data: data, encoding: .utf8) {

self.text = string

} else {

throw CocoaError(.fileReadCorruptFile)

}

func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {

let data = Data(text.utf8)

return FileWrapper(regularFileWithContents: data)

}

この TextDocument は .plainText を扱うための構造体です。

この構造体によって、ユーザーが読み込んだ .txt ファイルの中身を text プロパティに格納し、編集後に .fileExporter() で再び .txt として保存することができます。

SwiftUIの .fileImporter() や .fileExporter() と組み合わせることで、アプリに「ファイルを開く」「保存する」機能を簡単に追加できるように作られた実用的なサンプルです。

FileDocument の活用シーン

FileDocument は、SwiftUIアプリにおけるファイル操作機能を柔軟かつ安全に実装するための基本的な仕組みです。

下記のような活用シーンが考えられます。

.fileExporter() でユーザーが編集内容をファイル保存したいとき
.fileImporter() で外部ファイルを読み込んでアプリに反映したいとき
CSVやJSONなどアプリ固有のフォーマットで読み書きしたい場合
テキストエディタや画像ビューワなど、ファイルベースの編集機能を提供したいとき
ローカルストレージではなく、iCloudや外部アプリとのファイル共有を実現したいとき

ドキュメントベースのUI設計（iPadアプリなど）にも向いており、SwiftUIらしい宣言的な実装が可能です。

FileDocument を使うときの注意点

FileDocument を安全かつ効果的に活用するためには、ファイル形式の指定やエラーハンドリングの実装など、いくつかの注意点を意識する必要があります。

対応するファイル形式（UTType）を明示しないと、意図通りに動作しない
バイナリ形式やマルチファイルの構造に対応する場合は、FileWrapperの理解が必要
読み込み／書き出しが失敗するケースに備え、例外処理（try/catch）を適切に組み込む必要がある
SwiftUIと連携する際は、.fileImporter()や.fileExporter()との組み合わせが前提になる

これらを考慮することで、より堅牢でユーザーに優しいファイル操作機能を実現できます。

まとめ

今回は SwiftUI における FileDocument プロトコルについて詳しく紹介しました。

FileDocument は、ユーザーによるファイルの読み書きを支えるプロトコル
テキストや画像、独自形式など任意のデータ構造に対応可能
readableContentTypes・init(configuration:)・fileWrapper(configuration:) の3点が必須実装要素
.fileExporter() や .fileImporter() と連携してファイル操作をUIに統合できる
ドキュメント型アプリやデータ保存機能の実装に非常に有効

SwiftUIでファイルを扱う機能を構築する際には、まずこの FileDocument の設計から始めるのがおすすめです！