CachedNetworkImage：主要概念とImageProviderウィジェット

CachedNetworkImageとは？

CachedNetworkImageは、pub.devの同名パッケージのFlutterウィジェットで、自動キャッシュによるネットワーク画像読み込みを提供します。標準のImage.networkをラップし、ファイルキャッシュ、プログレスインジケーター、カスタムエラーハンドリングを追加します。

内部的には、CachedNetworkImageはflutter_cache_manager — ファイル追跡用のSQLiteデータベースを持つキャッシュマネージャー — を使用します。最初のリクエストでは画像がネットワークからダウンロードされディスクに保存され、後続のリクエストではTTL（デフォルト7日）を考慮してキャッシュから提供されます。インメモリキャッシュはFlutterの標準ImageCacheによって管理されます。

このパッケージはpub.devで4,000以上のいいねを獲得しており、何千ものFlutterプロジェクトで使用されています。CachedNetworkImageはすべてのFlutterプラットフォーム（Android、iOS、Web、macOS、Windows、Linux）をサポートしています。統一されたAPIにより、開発者はプラットフォーム固有のコードなしでクロスプラットフォームの画像読み込みを実現できます。

Flutterでの画像キャッシュの仕組み

Flutterは2レベルのキャッシュシステムを使用します：ImageCache（メモリ）とflutter_cache_manager（ディスク＋SQLite）。ImageCacheは、デコード済み画像のグローバルキャッシュで、数（デフォルト1000）とサイズ（デフォルト100 MB）に制限があります。flutter_cache_managerはディスク上のファイルとそのメタデータを管理します。

検索シーケンス

CachedNetworkImageが画像リクエストを受け取ると、最初にFlutterのImageCacheをチェックします — 画像がすでにメモリにデコードされている場合は即座に表示されます。キャッシュミスの場合、flutter_cache_managerを介してディスクがチェックされます：SQLiteクエリでファイルがキャッシュに存在するか、TTLが期限切れかどうかを確認します。ファイルが有効な場合 — ディスクから読み込まれ、デコードされ、表示されます。ファイルがないかTTLが期限切れの場合 — HTTPリクエストが実行されます。

• ImageCache — グローバルなFlutterキャッシュ、デフォルトで1000アイテム / 100 MB
• flutter_cache_manager — SQLite＋ファイルシステム、TTL 7日
• HTTPダウンロード — httpパッケージまたはカスタムHttpClientを介して実行

キャッシュのクリーンアップ

DefaultCacheManagerは、emptyCache()（完全クリーンアップ）、cleanCache()（期限切れのみ削除）、およびカスタム日付によるclearCacheWithAge()メソッドを提供します。ImageCacheはメモリプレッシャー時に自動的に、またはimageCache.clear()で手動でクリアされます。

CachedNetworkImageウィジェットのアーキテクチャ

CachedNetworkImageは、標準のFlutterウィジェット構成に基づいて構築されています。内部実装では、非同期読み込みにImageProvider、ライフサイクル管理にStatefulWidgetを使用しています。

主要パラメーター

imageUrl — 必須パラメーター、画像のURL（StringまたはUri）。placeholder — 読み込み中に表示されるウィジェット。errorWidget — 読み込みエラー時のウィジェット。progressIndicatorBuilder — コンテキスト、URL、totalSizeおよびdownloadedSizeフィールドを持つDownloadProgressを受け取るビルダー。

ImageProvider

CachedNetworkImageProvider — ダウンロードとキャッシュを管理するCachedNetworkStreamImageを返すImageProviderの実装です。このプロバイダーはFlutterのImageCacheと統合され、スケーリング、センタリング、繰り返しなど、すべての標準ImageProvider機能をサポートします。

flutter_cache_managerの設定

flutter_cache_managerは、CachedNetworkImageのキャッシュの基盤となるライブラリです。設定済みのSQLiteデータベース、TTL、ファイル制限を持つDefaultCacheManagerを提供します。必要に応じて、独自のパラメーターを持つカスタムCacheManagerを作成できます。

カスタムCacheManagerは、メソッドオーバーライドを使用してCacheManagerから継承することで作成されます。これは、画像を別のディレクトリに保存する必要がある場合や、異なるHTTPクライアントが必要な場合に便利です。マネージャーインスタンスはCachedNetworkImageのcacheManagerパラメーターに渡されます。

DefaultCacheManagerのSQLiteデータベースは、アプリケーションのtemporaryDirectoryの`{key}/CacheObjects.db`パスにあります。cacheObjectsテーブルには、key（URL）、relativePath、url、creationDate、eTag、httpHeadersのフィールドが含まれています。期限切れエントリーのクリーンアップ時には、maxAgeCacheObjectの条件に基づくSQLクエリが使用されます。

DartでのCachedNetworkImage使用例

CachedNetworkImageは、CachedNetworkImageウィジェットとカスタムシナリオ向けのCachedNetworkImageProviderという2つの主要な読み込みアプローチを提供します。

プレースホルダーを使用した基本読み込み

CachedNetworkImage — 主要なアプローチです。imageUrlとplaceholderを渡すだけで、ウィジェットは自動的に読み込み完了までプレースホルダーを表示し、その後画像に置き換えます。

CachedNetworkImage(
    imageUrl: "https://example.com/photo.jpg",
    placeholder: (context, url) => CircularProgressIndicator(),
    errorWidget: (context, url, error) => Icon(Icons.error),
    width: 200,
    height: 200,
    fit: BoxFit.cover,
)

placeholderとerrorWidgetは、コンテキスト、URL、（errorWidgetの場合は）エラーオブジェクトを受け取るビルダー関数です。このアプローチにより、URLやエラータイプに応じて異なるプレースホルダーを表示できます。

プログレス付き読み込み

progressIndicatorBuilder — ダウンロードの進行状況をパーセンテージで表示できるパラメーターです。DownloadProgressにはtotalSize（不明な場合は-1）とdownloadedSizeが含まれます。

CachedNetworkImage(
    imageUrl: "https://example.com/large.jpg",
    progressIndicatorBuilder: (context, url, downloadProgress) {
        return Center(
            child: SizedBox(
                width: 50,
                height: 50,
                child: Stack(
                    alignment: Alignment.center,
                    children: [
                        CircularProgressIndicator(
                            value: downloadProgress.progress,
                        ),
                        Text(
                            "\(downloadProgress.downloadedSize ~/ 1024) KB",
                        ),
                    ],
                ),
            ),
        };
    },
    imageBuilder: (context, imageProvider) {
        return Container(
            decoration: BoxDecoration(
                borderRadius: BorderRadius.circular(12),
                image: DecorationImage(
                    image: imageProvider,
                    fit: BoxFit.cover,
                ),
            ),
        };
    },
)

imageBuilder — 画像表示をカスタマイズできるオプションのパラメーターです：角丸、影、装飾を追加できます。この例では、角丸にBorderRadiusを使用したDecorationImageを使用しています。

CachedNetworkImageProviderの使用

CachedNetworkImageProvider — CachedNetworkImageウィジェットを使用せずにImageまたはDecorationImageのためのプロバイダーです。BoxDecoration、FadeInImage、またはカスタムImageウィジェットを扱う際に便利です。

Container(
    decoration: BoxDecoration(
        image: DecorationImage(
            image: CachedNetworkImageProvider(
                "https://example.com/bg.jpg",
                maxWidthBytes: 2048,
                maxHeightBytes: 2048,
            ),
            fit: BoxFit.cover,
        ),
    ),
)

ImageBuilderとカスタム処理

CachedNetworkImageのimageBuilderパラメーターを使用すると、標準のImageウィジェットをカスタム実装でオーバーライドできます。Imageを直接表示する代わりに、デコレーション付きのContainer、クリッピング用のClipRRect、またはリップル効果用のInk.imageを使用できます。imageBuilderはコンテキストと準備完了画像のImageProviderを受け取り、レンダリングを完全に制御できます。

追加パラメーター：memCacheWidthとmemCacheHeightはRAM内のキャッシュ画像サイズを制限し、FlutterのImageCacheの負荷を軽減します。cacheKeyを使用すると、URLの代わりにカスタムキャッシュキーを設定できます。これはURLに認証トークンを含む画像（クエリパラメーターはリクエストごとに変わりますが、コンテンツは同じまま）に便利です。

CachedNetworkImage vs 標準のImage.network

標準のImage.networkウィジェットは、ディスクに保存せずにウィジェットの再構築ごとに画像を読み込みます。CachedNetworkImageはファイルキャッシュ、プログレスインジケーター、エラーハンドリングを追加しますが、flutter_cache_managerとSQLiteへの依存が追加されます。

オフライン機能と帯域幅の節約が重要なプロジェクトでは、CachedNetworkImageが明確な選択です。単発のシンプルな画面（オンボーディングやスプラッシュなど）の場合、Image.networkは追加の依存関係を必要としません。

FlutterプロジェクトでのCachedNetworkImageのセットアップ

CachedNetworkImageは標準のpub.dev依存関係として追加されます。インストール後、ウィジェットはすぐに使用できます。flutter_cache_managerは推移的依存関係として含まれます。

// pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  cached_network_image: ^3.4.1

デフォルトでは、DefaultCacheManagerが設定（TTL = 7日、最大200ファイル）で使用されます。グローバルパラメーターを変更するには、Configを使用してカスタムCacheManagerインスタンスを作成し、maxAgeCacheObject、maxNrOfCacheObjects、repoをオーバーライドします。

import 'package:cached_network_image/cached_network_image.dart';
import 'package:flutter_cache_manager/flutter_cache_manager.dart';

final customCacheManager = CacheManager(
  Config(
    "custom_images",
    stalePeriod: Duration(days: 14),
    maxNrOfCacheObjects: 500,
    repo: JsonCacheInfoRepository(
      databaseName: "custom_images_cache.db",
    ),
  ),
);

// カスタムマネージャーの使用:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytesとmaxHeightBytes — キャッシュファイルのサイズを制限するためのオプションのパラメーターです。元の画像が必要な画面サイズより大きい場合、ディスク容量を節約するのに役立ちます。