CachedNetworkImage : concepts clés et le widget ImageProvider

Qu'est-ce que CachedNetworkImage ?

CachedNetworkImage est un widget Flutter du paquet éponyme sur pub.dev qui fournit un chargement d'images réseau avec mise en cache automatique. C'est une surcouche autour du Image.network standard, ajoutant la mise en cache de fichiers, les indicateurs de progression et la gestion personnalisée des erreurs.

En interne, CachedNetworkImage utilise flutter_cache_manager — un gestionnaire de cache avec une base de données SQLite pour suivre les fichiers. Lors de la première requête, l'image est téléchargée depuis le réseau, sauvegardée sur le disque, et lors des requêtes suivantes, elle est servie depuis le cache en tenant compte du TTL (par défaut 7 jours). La mise en cache en mémoire est gérée par l'ImageCache standard de Flutter.

Le paquet compte plus de 4 000 likes sur pub.dev et est utilisé dans des milliers de projets Flutter. CachedNetworkImage prend en charge toutes les plateformes Flutter : Android, iOS, Web, macOS, Windows et Linux. Grâce à une API unifiée, les développeurs obtiennent un chargement d'images multiplateforme sans code spécifique à une plateforme.

Comment fonctionne la mise en cache d'images dans Flutter

Flutter utilise un système de mise en cache à deux niveaux : ImageCache (mémoire) et flutter_cache_manager (disque + SQLite). ImageCache est un cache global d'images décodées avec des limites de quantité (par défaut 1000) et de taille (par défaut 100 Mo). flutter_cache_manager gère les fichiers sur le disque et leurs métadonnées.

Séquence de recherche

Lorsque CachedNetworkImage reçoit une demande d'image, il vérifie d'abord l'ImageCache de Flutter — si l'image est déjà décodée en mémoire, elle s'affiche instantanément. En cas d'échec du cache, le disque est vérifié via flutter_cache_manager : une requête SQLite vérifie si le fichier existe dans le cache et si son TTL a expiré. Si le fichier est à jour — il est lu du disque, décodé et affiché. Si le fichier est manquant ou que le TTL a expiré — une requête HTTP est effectuée.

• ImageCache — cache global de Flutter, 1000 éléments / 100 Mo par défaut
• flutter_cache_manager — SQLite + système de fichiers, TTL 7 jours
• Téléchargement HTTP — effectué via le paquet http ou un HttpClient personnalisé

Nettoyage du cache

DefaultCacheManager fournit les méthodes emptyCache() (nettoyage complet), cleanCache() (supprimer uniquement les expirés) et clearCacheWithAge() avec une date personnalisée. ImageCache est nettoyé automatiquement en cas de pression mémoire ou manuellement via imageCache.clear().

Architecture du widget CachedNetworkImage

CachedNetworkImage est construit sur la composition de widgets Flutter standard. L'implémentation interne utilise ImageProvider pour le chargement asynchrone et StatefulWidget pour la gestion du cycle de vie.

Paramètres clés

imageUrl — paramètre obligatoire, l'URL de l'image (String ou Uri). placeholder — widget affiché pendant le chargement. errorWidget — widget en cas d'erreur de chargement. progressIndicatorBuilder — builder qui reçoit le contexte, l'URL et DownloadProgress avec les champs totalSize et downloadedSize.

ImageProvider

CachedNetworkImageProvider — une implémentation d'ImageProvider qui retourne CachedNetworkStreamImage, qui gère le téléchargement et la mise en cache. Le fournisseur s'intègre avec l'ImageCache de Flutter et prend en charge toutes les capacités standard d'ImageProvider : mise à l'échelle, centrage et répétition.

Configuration de flutter_cache_manager

flutter_cache_manager est la bibliothèque sous-jacente au système de cache de CachedNetworkImage. Elle fournit DefaultCacheManager avec une base de données SQLite configurée, TTL et limite de fichiers. Si nécessaire, un CacheManager personnalisé peut être créé avec des paramètres uniques.

Un CacheManager personnalisé est créé en héritant de CacheManager avec remplacement de méthodes. Ceci est utile lorsque les images doivent être stockées dans un répertoire séparé ou qu'un client HTTP différent est nécessaire. L'instance du gestionnaire est ensuite passée au paramètre cacheManager de CachedNetworkImage.

La base de données SQLite de DefaultCacheManager se trouve dans le temporaryDirectory de l'application au chemin `{key}/CacheObjects.db`. Elle contient la table cacheObjects avec les champs : key (URL), relativePath, url, creationDate, eTag, httpHeaders. Lors du nettoyage des entrées expirées, une requête SQL avec une condition sur maxAgeCacheObject est utilisée.

Exemples d'utilisation de CachedNetworkImage en Dart

CachedNetworkImage offre deux approches principales de chargement : le widget CachedNetworkImage et CachedNetworkImageProvider pour les scénarios personnalisés.

Chargement de base avec placeholder

CachedNetworkImage — l'approche principale. Il suffit de passer imageUrl et placeholder. Le widget affiche automatiquement le placeholder jusqu'à la fin du chargement et le remplace par l'image.

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 et errorWidget sont des fonctions builder qui acceptent le contexte, l'URL et (pour errorWidget) un objet d'erreur. Cette approche permet d'afficher différents placeholders selon l'URL ou le type d'erreur.

Chargement avec progression

progressIndicatorBuilder — un paramètre qui permet d'afficher la progression du téléchargement en pourcentage. DownloadProgress contient totalSize (peut être -1 si inconnu) et 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 — un paramètre optionnel qui permet de personnaliser l'affichage de l'image : ajouter des coins arrondis, des ombres, des décorations. L'exemple utilise DecorationImage avec BorderRadius pour des coins arrondis.

Utilisation de CachedNetworkImageProvider

CachedNetworkImageProvider — un fournisseur pour Image ou DecorationImage sans utiliser le widget CachedNetworkImage. Utile lorsqu'on travaille avec BoxDecoration, FadeInImage ou des widgets d'image personnalisés.

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

ImageBuilder et traitement personnalisé

Le paramètre imageBuilder dans CachedNetworkImage permet de remplacer le widget Image standard par une implémentation personnalisée. Au lieu d'afficher directement l'Image, vous pouvez utiliser un Container avec décoration, ClipRRect pour le recadrage, ou Ink.image pour des effets de vague. imageBuilder reçoit le contexte et l'ImageProvider de l'image prête, donnant un contrôle total sur le rendu.

Paramètres supplémentaires : memCacheWidth et memCacheHeight limitent la taille de l'image mise en cache dans la RAM, réduisant la charge sur l'ImageCache de Flutter. cacheKey permet de définir une clé de cache personnalisée au lieu de l'URL, utile pour les images avec des jetons d'autorisation dans l'URL (les paramètres de requête changent à chaque demande mais le contenu reste le même).

CachedNetworkImage vs Image.network standard

Le widget standard Image.network charge l'image à chaque reconstruction du widget sans la sauvegarder sur le disque. CachedNetworkImage ajoute la mise en cache de fichiers, les indicateurs de progression et la gestion des erreurs, mais ajoute une dépendance à flutter_cache_manager et SQLite.

Pour les projets où la capacité hors ligne et les économies de bande passante sont importantes, CachedNetworkImage est le choix évident. Pour les écrans simples et uniques (par exemple, onboarding ou splash), Image.network ne nécessite pas de dépendances supplémentaires.

Configurer CachedNetworkImage dans un projet Flutter

CachedNetworkImage est ajouté comme une dépendance standard de pub.dev. Après l'installation, le widget est prêt à l'emploi. flutter_cache_manager est inclus comme dépendance transitive.

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

Par défaut, DefaultCacheManager est utilisé avec les paramètres : TTL = 7 jours, max 200 fichiers. Pour modifier les paramètres globaux, une instance personnalisée de CacheManager est créée avec Config, où maxAgeCacheObject, maxNrOfCacheObjects et repo sont remplacés.

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

// Utilisation d'un gestionnaire personnalisé :
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes et maxHeightBytes — paramètres optionnels pour limiter la taille du fichier mis en cache. Ceci est utile pour économiser de l'espace disque lorsque l'image originale est plus grande que la taille d'écran requise.