CachedNetworkImage: concetti chiave e il widget ImageProvider

Cos'è CachedNetworkImage?

CachedNetworkImage è un widget Flutter del pacchetto omonimo su pub.dev che fornisce il caricamento di immagini di rete con memorizzazione automatica nella cache. È un involucro attorno al Image.network standard, aggiungendo la cache su file, gli indicatori di progresso e la gestione personalizzata degli errori.

Internamente, CachedNetworkImage utilizza flutter_cache_manager — un gestore di cache con database SQLite per tracciare i file. Alla prima richiesta, l'immagine viene scaricata dalla rete, salvata su disco e, nelle richieste successive, viene servita dalla cache tenendo conto del TTL (default 7 giorni). La cache in memoria è gestita dall'ImageCache standard di Flutter.

Il pacchetto ha oltre 4.000 mi piace su pub.dev ed è utilizzato in migliaia di progetti Flutter. CachedNetworkImage supporta tutte le piattaforme Flutter: Android, iOS, Web, macOS, Windows e Linux. Grazie a un'API unificata, gli sviluppatori ottengono il caricamento di immagini multipiattaforma senza codice specifico per piattaforma.

Come funziona la memorizzazione nella cache delle immagini in Flutter

Flutter utilizza un sistema di cache a due livelli: ImageCache (memoria) e flutter_cache_manager (disco + SQLite). ImageCache è una cache globale di immagini decodificate con limiti sul numero (default 1000) e sulla dimensione (default 100 MB). flutter_cache_manager gestisce i file su disco e i loro metadati.

Sequenza di ricerca

Quando CachedNetworkImage riceve una richiesta di immagine, controlla prima l'ImageCache di Flutter — se l'immagine è già decodificata in memoria, viene visualizzata istantaneamente. In caso di mancata corrispondenza nella cache, il disco viene controllato tramite flutter_cache_manager: una query SQLite verifica se il file esiste nella cache e se il suo TTL è scaduto. Se il file è aggiornato — viene letto dal disco, decodificato e visualizzato. Se il file manca o il TTL è scaduto — viene effettuata una richiesta HTTP.

• ImageCache — cache globale di Flutter, 1000 elementi / 100 MB per impostazione predefinita
• flutter_cache_manager — SQLite + file system, TTL 7 giorni
• Download HTTP — effettuato tramite il pacchetto http o un HttpClient personalizzato

Pulizia della cache

DefaultCacheManager fornisce i metodi emptyCache() (pulizia completa), cleanCache() (rimuovere solo quelli scaduti) e clearCacheWithAge() con una data personalizzata. ImageCache viene pulito automaticamente in caso di pressione della memoria o manualmente tramite imageCache.clear().

Architettura del widget CachedNetworkImage

CachedNetworkImage è costruito sulla composizione di widget Flutter standard. L'implementazione interna utilizza ImageProvider per il caricamento asincrono e StatefulWidget per la gestione del ciclo di vita.

Parametri chiave

imageUrl — parametro obbligatorio, l'URL dell'immagine (String o Uri). placeholder — widget visualizzato durante il caricamento. errorWidget — widget in caso di errore di caricamento. progressIndicatorBuilder — builder che riceve contesto, URL e DownloadProgress con i campi totalSize e downloadedSize.

ImageProvider

CachedNetworkImageProvider — un'implementazione di ImageProvider che restituisce CachedNetworkStreamImage, che gestisce il download e la memorizzazione nella cache. Il provider si integra con l'ImageCache di Flutter e supporta tutte le funzionalità standard di ImageProvider: ridimensionamento, centratura e ripetizione.

Configurazione di flutter_cache_manager

flutter_cache_manager è la libreria alla base del sistema di cache di CachedNetworkImage. Fornisce DefaultCacheManager con un database SQLite configurato, TTL e limite di file. Se necessario, è possibile creare un CacheManager personalizzato con parametri unici.

Un CacheManager personalizzato viene creato ereditando da CacheManager con override dei metodi. Ciò è utile quando le immagini devono essere archiviate in una directory separata o è necessario un client HTTP diverso. L'istanza del gestore viene quindi passata al parametro cacheManager di CachedNetworkImage.

Il database SQLite di DefaultCacheManager si trova nel temporaryDirectory dell'applicazione al percorso `{key}/CacheObjects.db`. Contiene la tabella cacheObjects con i campi: key (URL), relativePath, url, creationDate, eTag, httpHeaders. Durante la pulizia delle voci scadute, viene utilizzata una query SQL con una condizione su maxAgeCacheObject.

Esempi di utilizzo di CachedNetworkImage in Dart

CachedNetworkImage offre due approcci principali al caricamento: il widget CachedNetworkImage e CachedNetworkImageProvider per scenari personalizzati.

Caricamento base con placeholder

CachedNetworkImage — l'approccio principale. Basta passare imageUrl e placeholder. Il widget mostra automaticamente il placeholder fino al completamento del caricamento e lo sostituisce con l'immagine.

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 e errorWidget sono funzioni builder che accettano contesto, URL e (per errorWidget) un oggetto di errore. Questo approccio consente di mostrare placeholder diversi a seconda dell'URL o del tipo di errore.

Caricamento con progresso

progressIndicatorBuilder — un parametro che consente di visualizzare l'avanzamento del download in percentuale. DownloadProgress contiene totalSize (può essere -1 se sconosciuto) e 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 parametro opzionale che consente di personalizzare la visualizzazione dell'immagine: aggiungere angoli arrotondati, ombre, decorazioni. L'esempio utilizza DecorationImage con BorderRadius per angoli arrotondati.

Utilizzo di CachedNetworkImageProvider

CachedNetworkImageProvider — un provider per Image o DecorationImage senza utilizzare il widget CachedNetworkImage. Utile quando si lavora con BoxDecoration, FadeInImage o widget Image personalizzati.

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

ImageBuilder e gestione personalizzata

Il parametro imageBuilder in CachedNetworkImage consente di sovrascrivere il widget Image standard con un'implementazione personalizzata. Invece di visualizzare direttamente l'Image, puoi utilizzare un Container con decorazione, ClipRRect per il ritaglio o Ink.image per effetti ondulatori. imageBuilder riceve il contesto e l'ImageProvider dell'immagine pronta, dando il controllo completo sul rendering.

Parametri aggiuntivi: memCacheWidth e memCacheHeight limitano la dimensione dell'immagine memorizzata nella cache nella RAM, riducendo il carico sull'ImageCache di Flutter. cacheKey consente di impostare una chiave di cache personalizzata anziché l'URL, utile per immagini con token di autorizzazione nell'URL (i parametri di query cambiano a ogni richiesta ma il contenuto rimane lo stesso).

CachedNetworkImage vs Image.network standard

Il widget standard Image.network carica l'immagine a ogni ricostruzione del widget senza salvarla su disco. CachedNetworkImage aggiunge la cache su file, gli indicatori di progresso e la gestione degli errori, ma aggiunge una dipendenza da flutter_cache_manager e SQLite.

Per i progetti in cui la capacità offline e il risparmio di larghezza di banda sono importanti, CachedNetworkImage è la scelta ovvia. Per schermate semplici e una tantum (ad esempio onboarding o splash), Image.network non richiede dipendenze aggiuntive.

Configurare CachedNetworkImage in un progetto Flutter

CachedNetworkImage viene aggiunto come dipendenza standard di pub.dev. Dopo l'installazione, il widget è pronto all'uso. flutter_cache_manager è incluso come dipendenza transitiva.

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

Per impostazione predefinita, viene utilizzato DefaultCacheManager con le impostazioni: TTL = 7 giorni, max 200 file. Per modificare i parametri globali, viene creata un'istanza personalizzata di CacheManager con Config, dove maxAgeCacheObject, maxNrOfCacheObjects e repo vengono sovrascritti.

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

// Utilizzo di un gestore personalizzato:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes e maxHeightBytes — parametri opzionali per limitare la dimensione del file nella cache. Ciò è utile per risparmiare spazio su disco quando l'immagine originale è più grande della dimensione dello schermo richiesta.