
# アプリのファイル

`FileTemplate` は、すべてのプラットフォームの正しいディレクトリにあるアプリ自身のファイルのための Bean です。テキスト、バイト、オブジェクト (JSON として) を、三つの場所に読み書きします。`support` (プライベートで、保持され、バックアップされる)、`cache` (システムが消去することがある)、`documents` (ユーザーに見える) です。Web ではどの場所も IndexedDB です。プロパティはありません。

## 使う理由

どのアプリもいくつかのファイルを書きます。オフラインで使うためのカタログ、キャッシュした表紙、エクスポートなどです。そのたびに `path_provider`、プラットフォームごとの正しいディレクトリ、JSON のコード、書きかけのファイルへの配慮が必要です。テンプレートは、Spring の `JdbcTemplate` や `RestTemplate` のように、置き換え可能なストアの上のテンプレートとして、これを一度だけ行います。

## 例

```dart
@Service()
class Library {
  Library(this.files);

  final FileTemplate files;

  // アプリケーションの ObjectMapper を通じた、JSON としてのオブジェクト。
  Future<void> save(List<Book> books) => files.write('catalog.json', books);

  Future<List<Book>> load() async =>
      await files.read<List<Book>>(
        'catalog.json',
        const ListType<Book>(ClassType<Book>()),
      ) ??
      [];

  Future<void> cacheCover(String id, Uint8List png) =>
      files.cache.write('covers/$id.png', png);   // OS が消去することがある

  Future<void> export(String csv) =>
      files.documents.write('books.csv', csv);    // ユーザーに見える
}
```

## メソッド

| メソッド | 働き |
|---|---|
| `write(path, value)` | テキスト (`String`)、バイト (`Uint8List`)、またはオブジェクト (アプリケーションの `ObjectMapper` を通じた JSON) を書く |
| `read<T>(path, [type])` | それを読み戻す。存在しないファイルは `null` として読まれる。場所には `readString` と `readBytes` がある |
| `exists(path)` | ファイルが存在するかどうか |
| `delete(path)` | ファイルまたはフォルダーを削除する |
| `list(prefix)` | `prefix` が `/` で終わる場合はフォルダーの下のパス、それ以外はそれで始まるパス |
| `modifiedAt(path)` | ファイルが最後に書かれた時刻 |

`files` 自体のメソッドは `support` に作用します。`files.cache` と `files.documents` (そして `files.support`) が他の場所で、それぞれ同じメソッドを持つ `FileArea` です。

## 場所

| 場所 | コードでは | 内容 |
|---|---|---|
| `support` | `files.write(...)` | アプリのプライベートなデータ。保持され、バックアップされる。デフォルト |
| `cache` | `files.cache.write(...)` | システムが消去することがある |
| `documents` | `files.documents.write(...)` | ユーザーの書類フォルダー |

ディレクトリは `path_provider` が見つけるものです。Windows では `support` は `%LOCALAPPDATA%\<company>\<product>` で、ローミングのディレクトリではなくマシン自身のものです。`cache` はその `cache` フォルダーです。Web ではすべてが IndexedDB です。

## 安全なパスと書き込み

- 書き込みはアトミックです。対象の隣の一時ファイルに書き、次に名前を変えます。クラッシュしても半分のファイルが残ることはありません。
- パスはその場所の中にとどまります。`..` と絶対パスは `ArgumentError` を投げます。

## 一時ファイル

一時ファイルは、実行ごとのフォルダー (`<system temp>/spring/<run id>/`) の中で一意の名前を持ちます。

```dart
// ブロックのためだけのファイル: その後、エラーの後でも削除される。
final small = await files.temp(suffix: '.jpg', (file) async {
  await file.writeAsBytes(photo);          // または実際のファイルとして File(file.path)
  return compress(File(file.path));
});

// ブロックのためだけのフォルダー。
await files.tempDir((dir) => unzip(archive, into: dir.path));

// 自分で削除するもの。
final keep = await files.createTemp();
```

ブロックや `createTemp` が残したものはコンテキストが閉じるときに取り除かれ、異常終了した実行のフォルダーは次の起動時に取り除かれます。Web では一時ファイルはメモリ上にあり、`path` を持たず、`tempDir` はサポートされません。

## ストアを置き換える

`FileStore` Bean (暗号化するもの、リモートのもの) を宣言すると、`FileTemplate`、テーマのキャッシュ、テーマの選択のストアがそれに従います。テンプレート自体を置き換えるには、`FileTemplate` Bean を宣言します。`InMemoryFileStore` は、テストのためにすべてをメモリに保持します。

```dart
// テストはデバイスではなくメモリに書く。
final app = springBootTest(
  springApplication,
  overrides: [BeanOverride<FileStore>(InMemoryFileStore())],
);
```

## これを使うもの

- URL からダウンロードしたテーマは、`support` の `spring/themes/` にキャッシュされます ([テーマのプロパティ](themes/properties.md) を参照)。
- ネットワークからのテーマの画像は `spring/images/` にキャッシュされます ([画像](themes/images.md) を参照)。
- ユーザーが選んだテーマは `spring/theme-choice` に保持されます ([テーマ](themes/index.md) を参照)。

## Spring (Java) との対応

Spring にはこうしたテンプレートはありません。形 (置き換え可能なストアの上のテンプレート) は `JdbcTemplate` や、セキュリティスターターの `SecretTemplate` のものです。

## 関連項目

- [SQLite データベース](sqlite.md)
- [spring_core_dart の JSON](../spring-core-dart/json/index.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
