Cache di immagini di rete in Flutter con cached_network_image

Per prima cosa aggiungiamo il pacchetto cached_network_image al file pubspec.yaml. Puoi farlo manualmente oppure tramite riga di comando.

Da terminale, nella cartella del progetto, esegui:

flutter pub add cached_network_image

In alternativa aggiungi la riga nella sezione dependencies del pubspec.yaml e poi lancia flutter pub get.

dependencies:
  flutter:
    sdk: flutter
  cached_network_image: ^3.3.1

Importiamo il pacchetto e usiamo il widget CachedNetworkImage al posto del classico Image.network. Alla prima esecuzione l'immagine viene scaricata e salvata in cache; alle successive viene letta direttamente dal disco, molto più velocemente.

import 'package:flutter/material.dart';
import 'package:cached_network_image/cached_network_image.dart';

class ImmagineDemo extends StatelessWidget {
  const ImmagineDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Cache Immagini')),
      body: Center(
        child: CachedNetworkImage(
          imageUrl: 'https://picsum.photos/400/300',
          width: 400,
          height: 300,
          fit: BoxFit.cover,
        ),
      ),
    );
  }
}

Un buon UX prevede di mostrare un indicatore durante il caricamento e un'icona di errore se l'immagine non è disponibile. Usiamo le proprietà placeholder ed errorWidget.

• placeholder: widget mostrato durante il download.
• errorWidget: widget mostrato se il caricamento fallisce (URL errato, assenza di rete, ecc.).

CachedNetworkImage(
  imageUrl: 'https://picsum.photos/400/300',
  width: 400,
  height: 300,
  fit: BoxFit.cover,
  placeholder: (context, url) => const Center(
    child: CircularProgressIndicator(),
  ),
  errorWidget: (context, url, error) => const Icon(
    Icons.broken_image,
    size: 48,
    color: Colors.grey,
  ),
)

cached_network_image supporta una transizione di dissolvenza tra placeholder e immagine. Possiamo regolarne la durata con fadeInDuration e fadeOutDuration.

Per un caricamento più informativo possiamo usare progressIndicatorBuilder, che fornisce il progresso del download (downloaded/totalSize) e ci permette di mostrare una percentuale reale.

CachedNetworkImage(
  imageUrl: 'https://picsum.photos/600/400',
  fit: BoxFit.cover,
  fadeInDuration: const Duration(milliseconds: 500),
  progressIndicatorBuilder: (context, url, progress) => Center(
    child: CircularProgressIndicator(
      value: progress.progress, // null finché non si conosce la dimensione totale
    ),
  ),
  errorWidget: (context, url, error) => const Icon(Icons.error),
)

A volte serve un'immagine di rete come sfondo di un container o dentro un CircleAvatar. In questi casi non possiamo usare il widget direttamente, ma il provider CachedNetworkImageProvider, che si integra con DecorationImage e con backgroundImage.

// Sfondo di un Container
Container(
  width: 200,
  height: 200,
  decoration: BoxDecoration(
    borderRadius: BorderRadius.circular(16),
    image: DecorationImage(
      image: CachedNetworkImageProvider('https://picsum.photos/200'),
      fit: BoxFit.cover,
    ),
  ),
)

// Avatar circolare
CircleAvatar(
  radius: 40,
  backgroundImage:
      CachedNetworkImageProvider('https://i.pravatar.cc/150'),
)

Per liberare spazio o forzare il refresh delle immagini, puoi gestire la cache tramite DefaultCacheManager del pacchetto flutter_cache_manager (dipendenza di cached_network_image).

È utile, ad esempio, in un pulsante "Pulisci cache" nelle impostazioni dell'app. Puoi rimuovere una singola immagine con removeFile(url) oppure svuotare tutto con emptyCache().

import 'package:flutter_cache_manager/flutter_cache_manager.dart';

// Rimuove dalla cache una singola immagine
Future<void> rimuoviImmagine(String url) async {
  await DefaultCacheManager().removeFile(url);
}

// Svuota completamente la cache delle immagini
Future<void> svuotaCache() async {
  await DefaultCacheManager().emptyCache();
}

// Esempio di pulsante
ElevatedButton.icon(
  onPressed: svuotaCache,
  icon: const Icon(Icons.delete),
  label: const Text('Pulisci cache'),
)