CachedNetworkImage: wat is het, kernconcepten en de ImageProvider-widget

Wat is CachedNetworkImage?

CachedNetworkImage is een Flutter-widget uit het gelijknamige pub.dev-pakket dat het laden van afbeeldingen uit het netwerk met automatische caching mogelijk maakt. Het is een uitbreiding op de standaard Image.network en voegt bestandscaching, voortgangsindicatoren en aangepaste foutafhandeling toe.

Intern gebruikt CachedNetworkImage flutter_cache_manager — een cachemapper met een SQLite-database voor het bijhouden van bestanden. Bij het eerste verzoek wordt de afbeelding uit het netwerk gedownload, op schijf opgeslagen en bij volgende verzoeken uit de cache geleverd met inachtneming van de TTL (standaard 7 dagen). De in-memory cache wordt beheerd door de standaard ImageCache van Flutter.

Het pakket heeft meer dan 4.000 vind-ik-leuks op pub.dev en wordt gebruikt in duizenden Flutter-projecten. CachedNetworkImage ondersteunt alle Flutter-platformen: Android, iOS, Web, macOS, Windows en Linux. Dankzij de uniforme API krijgt de ontwikkelaar cross-platform afbeeldingsladen zonder platform-specifieke code.

Hoe werkt het cachen van afbeeldingen in Flutter

Flutter gebruikt een tweelaags cachesysteem: ImageCache (geheugen) en flutter_cache_manager (schijf + SQLite). ImageCache is een globale cache van gedecodeerde afbeeldingen met een limiet op aantal (standaard 1000) en grootte (standaard 100 MB). flutter_cache_manager beheert bestanden op schijf en hun metadata.

Controlevolgorde

Wanneer CachedNetworkImage een afbeeldingsverzoek ontvangt, controleert het eerst de Flutter ImageCache — als de afbeelding al in het geheugen is gedecodeerd, wordt deze onmiddellijk weergegeven. Bij een misser wordt de schijf gecontroleerd via flutter_cache_manager: een SQLite-query controleert of het bestand in de cache bestaat en of de TTL niet is verlopen. Als het bestand actueel is — wordt het van schijf gelezen, gedecodeerd en weergegeven. Als het bestand niet bestaat of de TTL is verlopen — wordt een HTTP-verzoek uitgevoerd.

• ImageCache — globale Flutter-cache, standaard 1000 elementen / 100 MB
• flutter_cache_manager — SQLite + bestandssysteem, TTL 7 dagen
• HTTP-laden — uitgevoerd via de http-pakket of aangepaste HttpClient

Cache opschonen

DefaultCacheManager biedt methoden emptyCache() (volledig opschonen), cleanCache() (alleen verlopen verwijderen) en clearCacheWithAge() met aangepaste datum. ImageCache wordt automatisch opgeschoond bij geheugendruk of handmatig via imageCache.clear().

Architectuur van de CachedNetworkImage-widget

CachedNetworkImage is gebouwd op compositie van standaard Flutter-widgets. De interne implementatie gebruikt ImageProvider voor asynchroon laden en StatefulWidget voor het volgen van de levenscyclus.

Belangrijke parameters

imageUrl — verplichte parameter, URL van de afbeelding (String of Uri). placeholder — widget weergegeven tijdens het laden. errorWidget — widget bij laadfout. progressIndicatorBuilder — builder die context, URL en DownloadProgress ontvangt met velden totalSize en downloadedSize.

ImageProvider

CachedNetworkImageProvider — ImageProvider-implementatie die CachedNetworkStreamImage retourneert en het downloaden en cachen beheert. De provider integreert met de Flutter ImageCache en ondersteunt alle mogelijkheden van de standaard ImageProvider: schalen, centreren en herhalen.

Configuratie van flutter_cache_manager

flutter_cache_manager — de bibliotheek die aan de basis ligt van de CachedNetworkImage-caching. Het biedt DefaultCacheManager met een geconfigureerde SQLite-database, TTL en bestandslimiet. Indien nodig kan een aangepaste CacheManager met unieke parameters worden gemaakt.

Een aangepaste CacheManager wordt gemaakt door overerving van CacheManager met het overschrijven van methoden. Dit is handig wanneer afbeeldingen in een aparte map moeten worden opgeslagen of een andere HTTP-client moet worden gebruikt. Vervolgens wordt de beheerderinstantie doorgegeven aan de cacheManager-parameter van CachedNetworkImage.

De SQLite-database van DefaultCacheManager bevindt zich in de temporaryDirectory van de applicatie op het pad `{key}/CacheObjects.db`. Het bevat de tabel cacheObjects met velden key (URL), relativePath, url, creationDate, eTag, httpHeaders. Bij het opschonen van verlopen records wordt een SQL-query gebruikt met een voorwaarde op basis van maxAgeCacheObject.

Voorbeelden van het gebruik van CachedNetworkImage in Dart

CachedNetworkImage biedt twee manieren van laden: de CachedNetworkImage-widget en de CachedNetworkImageProvider voor aangepaste scenario's.

Basis laden met placeholder

CachedNetworkImage — de belangrijkste manier. Het volstaat om imageUrl en placeholder door te geven. De widget toont automatisch de placeholder tot het laden is voltooid en vervangt deze door de afbeelding.

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 en errorWidget zijn builder-functies die context, URL en (voor errorWidget) het foutobject ontvangen. Deze aanpak maakt het mogelijk verschillende plaatshouders weer te geven afhankelijk van de URL of het type fout.

Laden met voortgang

progressIndicatorBuilder — parameter die het mogelijk maakt de laadvoortgang in procenten weer te geven. DownloadProgress bevat totalSize (kan -1 zijn als de grootte onbekend is) en 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 — optionele parameter waarmee de weergave van de afbeelding kan worden aangepast: afronding, schaduw, decoratie toevoegen. In het voorbeeld wordt DecorationImage met BorderRadius voor afgeronde hoeken gebruikt.

Gebruik van CachedNetworkImageProvider

CachedNetworkImageProvider — provider voor Image of DecorationImage zonder de CachedNetworkImage-widget te gebruiken. Handig bij het werken met BoxDecoration, FadeInImage of aangepaste Image-widgets.

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

ImageBuilder en aangepaste verwerking

De parameter imageBuilder in CachedNetworkImage maakt het mogelijk de standaard Image-widget te vervangen door een aangepaste implementatie. In plaats van directe weergave van Image kan Container met decoratie, ClipRRect met bijsnijden of Ink.image voor het rimpel-effect worden gebruikt. imageBuilder ontvangt de context en ImageProvider van de gereedzijnde afbeelding en geeft volledige controle over de weergave.

Extra parameters: memCacheWidth en memCacheHeight beperken de grootte van de gecachte afbeelding in het RAM-geheugen, waardoor de belasting van de Flutter ImageCache wordt verminderd. cacheKey maakt het mogelijk een aangepaste cachesleutel in te stellen in plaats van de URL, wat handig is voor afbeeldingen met autorisatietokens in de URL (queryparameters veranderen bij elk verzoek, maar de inhoud blijft hetzelfde).

CachedNetworkImage vs standaard Image.network

De standaard widget Image.network laadt de afbeelding bij elke herbouw van de widget zonder deze op schijf op te slaan. CachedNetworkImage voegt bestandscaching, voortgang en foutafhandeling toe, maar voegt een afhankelijkheid van flutter_cache_manager en SQLite toe.

Voor projecten waar offline werken en bandbreedtebesparing belangrijk zijn, is CachedNetworkImage de duidelijke keuze. Voor eenvoudige eenmalige schermen (bijv. onboarding of splash) vereist Image.network geen extra afhankelijkheden.

CachedNetworkImage instellen in een Flutter-project

CachedNetworkImage wordt toegevoegd als een standaard pub.dev-afhankelijkheid. Na installatie is de widget klaar voor gebruik. flutter_cache_manager wordt als transitieve afhankelijkheid toegevoegd.

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

Standaard wordt DefaultCacheManager gebruikt met instellingen: TTL = 7 dagen, max 200 bestanden. Voor het wijzigen van globale parameters wordt een aangepaste CacheManager-instantie met Config gemaakt, waarin maxAgeCacheObject, maxNrOfCacheObjects en repo worden overschreven.

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

// Gebruik van aangepaste beheerder:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes en maxHeightBytes — optionele parameters voor het beperken van de grootte van het gecachte bestand. Dit is handig voor het besparen van schijfruimte wanneer de originele afbeelding groter is dan de benodigde schermgrootte.