CachedNetworkImage: Schlüsselkonzepte und das ImageProvider-Widget

Was ist CachedNetworkImage?

CachedNetworkImage ist ein Flutter-Widget aus dem gleichnamigen pub.dev-Paket, das Netzwerkbildladung mit automatischem Caching bereitstellt. Es ist ein Wrapper um das standardmäßige Image.network und fügt Datei-Caching, Fortschrittsanzeigen und benutzerdefinierte Fehlerbehandlung hinzu.

Intern verwendet CachedNetworkImage flutter_cache_manager — einen Cache-Manager mit einer SQLite-Datenbank zur Verfolgung von Dateien. Bei der ersten Anforderung wird das Bild aus dem Netzwerk heruntergeladen, auf der Festplatte gespeichert und bei nachfolgenden Anforderungen unter Berücksichtigung des TTL (Standard 7 Tage) aus dem Cache bereitgestellt. Das In-Memory-Caching wird vom standardmäßigen ImageCache von Flutter verwaltet.

Das Paket hat über 4.000 Likes auf pub.dev und wird in Tausenden von Flutter-Projekten verwendet. CachedNetworkImage unterstützt alle Flutter-Plattformen: Android, iOS, Web, macOS, Windows und Linux. Dank einer einheitlichen API erhalten Entwickler plattformübergreifendes Laden von Bildern ohne plattformspezifischen Code.

Wie funktioniert das Bild-Caching in Flutter

Flutter verwendet ein zweistufiges Caching-System: ImageCache (Arbeitsspeicher) und flutter_cache_manager (Festplatte + SQLite). ImageCache ist ein globaler Cache decodierter Bilder mit Beschränkungen für Anzahl (Standard 1000) und Größe (Standard 100 MB). flutter_cache_manager verwaltet Dateien auf der Festplatte und deren Metadaten.

Suchsequenz

Wenn CachedNetworkImage eine Bildanforderung erhält, überprüft es zunächst den ImageCache von Flutter — wenn das Bild bereits im Arbeitsspeicher decodiert ist, wird es sofort angezeigt. Bei einem Cache-Fehler wird die Festplatte über flutter_cache_manager überprüft: Eine SQLite-Abfrage prüft, ob die Datei im Cache vorhanden ist und ob ihr TTL abgelaufen ist. Wenn die Datei aktuell ist — wird sie von der Festplatte gelesen, decodiert und angezeigt. Wenn die Datei fehlt oder das TTL abgelaufen ist — wird eine HTTP-Anfrage gestellt.

• ImageCache — globaler Flutter-Cache, standardmäßig 1000 Elemente / 100 MB
• flutter_cache_manager — SQLite + Dateisystem, TTL 7 Tage
• HTTP-Download — erfolgt über das http-Paket oder einen benutzerdefinierten HttpClient

Cache-Bereinigung

DefaultCacheManager bietet die Methoden emptyCache() (vollständige Bereinigung), cleanCache() (nur abgelaufene entfernen) und clearCacheWithAge() mit einem benutzerdefinierten Datum. ImageCache wird bei Speicherdruck automatisch oder manuell über imageCache.clear() geleert.

Architektur des CachedNetworkImage-Widgets

CachedNetworkImage basiert auf der Komposition standardmäßiger Flutter-Widgets. Die interne Implementierung verwendet ImageProvider für asynchrones Laden und StatefulWidget für die Lebenszyklusverwaltung.

Wichtige Parameter

imageUrl — erforderlicher Parameter, die Bild-URL (String oder Uri). placeholder — Widget, das während des Ladens angezeigt wird. errorWidget — Widget bei Ladefehlern. progressIndicatorBuilder — Builder, der Kontext, URL und DownloadProgress mit den Feldern totalSize und downloadedSize erhält.

ImageProvider

CachedNetworkImageProvider — eine ImageProvider-Implementierung, die CachedNetworkStreamImage zurückgibt, das Herunterladen und Caching verwaltet. Der Anbieter integriert sich in den ImageCache von Flutter und unterstützt alle standardmäßigen ImageProvider-Funktionen: Skalierung, Zentrierung und Wiederholung.

Konfiguration von flutter_cache_manager

flutter_cache_manager ist die dem Caching von CachedNetworkImage zugrunde liegende Bibliothek. Sie bietet DefaultCacheManager mit einer konfigurierten SQLite-Datenbank, TTL und Dateilimit. Bei Bedarf kann ein benutzerdefinierter CacheManager mit eindeutigen Parametern erstellt werden.

Ein benutzerdefinierter CacheManager wird durch Vererbung von CacheManager mit Methodenüberschreibungen erstellt. Dies ist nützlich, wenn Bilder in einem separaten Verzeichnis gespeichert werden müssen oder ein anderer HTTP-Client erforderlich ist. Die Manager-Instanz wird dann an den cacheManager-Parameter von CachedNetworkImage übergeben.

Die SQLite-Datenbank von DefaultCacheManager befindet sich im temporaryDirectory der Anwendung unter dem Pfad `{key}/CacheObjects.db`. Sie enthält die Tabelle cacheObjects mit den Feldern: key (URL), relativePath, url, creationDate, eTag, httpHeaders. Beim Bereinigen abgelaufener Einträge wird eine SQL-Abfrage mit einer Bedingung für maxAgeCacheObject verwendet.

Beispiele zur Verwendung von CachedNetworkImage in Dart

CachedNetworkImage bietet zwei Hauptansätze zum Laden: das CachedNetworkImage-Widget und CachedNetworkImageProvider für benutzerdefinierte Szenarien.

Basisladen mit Platzhalter

CachedNetworkImage — der primäre Ansatz. Einfach imageUrl und placeholder übergeben. Das Widget zeigt automatisch den Platzhalter an, bis der Ladevorgang abgeschlossen ist, und ersetzt ihn durch das Bild.

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 und errorWidget sind Builder-Funktionen, die Kontext, URL und (für errorWidget) ein Fehlerobjekt akzeptieren. Dieser Ansatz ermöglicht das Anzeigen unterschiedlicher Platzhalter je nach URL oder Fehlertyp.

Laden mit Fortschritt

progressIndicatorBuilder — ein Parameter, der die Anzeige des Download-Fortschritts in Prozent ermöglicht. DownloadProgress enthält totalSize (kann -1 sein, wenn unbekannt) und 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 — ein optionaler Parameter, der die Anpassung der Bildanzeige ermöglicht: Hinzufügen von abgerundeten Ecken, Schatten, Dekorationen. Das Beispiel verwendet DecorationImage mit BorderRadius für abgerundete Ecken.

Verwendung von CachedNetworkImageProvider

CachedNetworkImageProvider — ein Anbieter für Image oder DecorationImage ohne Verwendung des CachedNetworkImage-Widgets. Nützlich bei der Arbeit mit BoxDecoration, FadeInImage oder benutzerdefinierten Image-Widgets.

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

ImageBuilder und benutzerdefinierte Verarbeitung

Der imageBuilder-Parameter in CachedNetworkImage ermöglicht das Überschreiben des standardmäßigen Image-Widgets durch eine benutzerdefinierte Implementierung. Anstatt das Image direkt anzuzeigen, können Sie einen Container mit Dekoration, ClipRRect zum Zuschneiden oder Ink.image für Welleffekte verwenden. imageBuilder erhält Kontext und ImageProvider des fertigen Bildes und gibt volle Kontrolle über das Rendering.

Zusätzliche Parameter: memCacheWidth und memCacheHeight begrenzen die Größe des zwischengespeicherten Bildes im RAM und reduzieren die Belastung des ImageCache von Flutter. cacheKey ermöglicht das Festlegen eines benutzerdefinierten Cache-Schlüssels anstelle der URL, was für Bilder mit Autorisierungstokens in der URL nützlich ist (Abfrageparameter ändern sich bei jeder Anfrage, aber der Inhalt bleibt gleich).

CachedNetworkImage vs. Standard Image.network

Das standardmäßige Image.network-Widget lädt das Bild bei jedem Widget-Neuaufbau, ohne es auf der Festplatte zu speichern. CachedNetworkImage fügt Datei-Caching, Fortschrittsanzeigen und Fehlerbehandlung hinzu, fügt aber eine Abhängigkeit von flutter_cache_manager und SQLite hinzu.

Für Projekte, bei denen Offline-Fähigkeit und Bandbreitenersparnis wichtig sind, ist CachedNetworkImage die klare Wahl. Für einfache einmalige Bildschirme (z. B. Onboarding oder Splash) benötigt Image.network keine zusätzlichen Abhängigkeiten.

Einrichtung von CachedNetworkImage in einem Flutter-Projekt

CachedNetworkImage wird als standardmäßige pub.dev-Abhängigkeit hinzugefügt. Nach der Installation ist das Widget sofort einsatzbereit. flutter_cache_manager wird als transitive Abhängigkeit eingeschlossen.

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

Standardmäßig wird DefaultCacheManager mit den Einstellungen verwendet: TTL = 7 Tage, max. 200 Dateien. Zum Ändern der globalen Parameter wird eine benutzerdefinierte CacheManager-Instanz mit Config erstellt, bei der maxAgeCacheObject, maxNrOfCacheObjects und repo überschrieben werden.

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",
    ),
  ),
);

// Verwendung eines benutzerdefinierten Managers:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes und maxHeightBytes — optionale Parameter zur Begrenzung der Größe der zwischengespeicherten Datei. Dies ist nützlich, um Festplattenspeicher zu sparen, wenn das Originalbild größer als die erforderliche Bildschirmgröße ist.