CachedNetworkImage: ce este, concepte cheie și widgetul ImageProvider

Ce este CachedNetworkImage?

CachedNetworkImage este un widget Flutter din pachetul pub.dev cu același nume, care oferă încărcarea imaginilor din rețea cu cache automat. Este un strat peste Image.network standard, adăugând cache pe fișiere, indicatoare de progres și gestionare personalizată a erorilor.

Intern, CachedNetworkImage folosește flutter_cache_manager — un manager de cache cu bază de date SQLite pentru urmărirea fișierelor. La prima solicitare, imaginea este descărcată din rețea, salvată pe disc, iar la solicitările ulterioare este livrată din cache ținând cont de TTL (implicit 7 zile). Cache-ul in-memory este gestionat de ImageCache standard al Flutter.

Pachetul are peste 4 000 de aprecieri pe pub.dev și este folosit în mii de proiecte Flutter. CachedNetworkImage suportă toate platformele Flutter: Android, iOS, Web, macOS, Windows și Linux. Datorită API-ului unificat, dezvoltatorul obține încărcare cross-platformă a imaginilor fără cod specific platformei.

Cum funcționează cache-ul imaginilor în Flutter

Flutter folosește un sistem de cache pe două niveluri: ImageCache (memorie) și flutter_cache_manager (disc + SQLite). ImageCache este un cache global al imaginilor decodate cu limită de număr (implicit 1000) și dimensiune (implicit 100 MB). flutter_cache_manager gestionează fișierele pe disc și metadatele acestora.

Ordinea verificării

Când CachedNetworkImage primește o solicitare de imagine, verifică mai întâi ImageCache al Flutter — dacă imaginea este deja decodată în memorie, este afișată instantaneu. În caz de ratare, discul este verificat prin flutter_cache_manager: o interogare SQLite verifică dacă fișierul există în cache și dacă TTL-ul său nu a expirat. Dacă fișierul este actual — este citit de pe disc, decodat și afișat. Dacă fișierul nu există sau TTL-ul a expirat — se execută o solicitare HTTP.

• ImageCache — cache global Flutter, implicit 1000 elemente / 100 MB
• flutter_cache_manager — SQLite + sistem de fișiere, TTL 7 zile
• Încărcarea HTTP — se execută prin pachetul http sau HttpClient personalizat

Curățarea cache-ului

DefaultCacheManager oferă metodele emptyCache() (curățare completă), cleanCache() (ștergere doar a celor expirate) și clearCacheWithAge() cu dată personalizată. ImageCache este curățat automat la presiunea memoriei sau manual prin imageCache.clear().

Arhitectura widgetului CachedNetworkImage

CachedNetworkImage este construit pe compoziția widgeturilor standard Flutter. Implementarea internă folosește ImageProvider pentru încărcare asincronă și StatefulWidget pentru urmărirea ciclului de viață.

Parametri cheie

imageUrl — parametru obligatoriu, URL-ul imaginii (String sau Uri). placeholder — widget afișat în timpul încărcării. errorWidget — widget la eroare de încărcare. progressIndicatorBuilder — builder care primește context, URL și DownloadProgress cu câmpurile totalSize și downloadedSize.

ImageProvider

CachedNetworkImageProvider — implementare ImageProvider care returnează CachedNetworkStreamImage, gestionând descărcarea și cache-ul. Providerul se integrează cu ImageCache Flutter și suportă toate capacitățile ImageProvider standard: scalare, centrare și repetare.

Configurarea flutter_cache_manager

flutter_cache_manager — biblioteca care stă la baza cache-ului CachedNetworkImage. Oferă DefaultCacheManager cu bază de date SQLite configurată, TTL și limită de fișiere. La nevoie, se poate crea un CacheManager personalizat cu parametri unici.

CacheManager personalizat se creează prin moștenirea CacheManager cu suprascrierea metodelor. Acest lucru este util când trebuie să stocați imaginile într-un director separat sau să folosiți un client HTTP diferit. Apoi instanța managerului este transmisă parametrului cacheManager al CachedNetworkImage.

Baza de date SQLite a DefaultCacheManager se află în directorul temporaryDirectory al aplicației la calea `{key}/CacheObjects.db`. Conține tabela cacheObjects cu câmpurile key (URL), relativePath, url, creationDate, eTag, httpHeaders. La curățarea înregistrărilor expirate se folosește o interogare SQL cu condiția după maxAgeCacheObject.

Exemple de utilizare CachedNetworkImage în Dart

CachedNetworkImage oferă două moduri principale de încărcare: widgetul CachedNetworkImage și providerul CachedNetworkImageProvider pentru scenarii personalizate.

Încărcare de bază cu placeholder

CachedNetworkImage — modul principal. Este suficient să transmiteți imageUrl și placeholder. Widgetul afișează automat placeholderul până la finalizarea încărcării și îl înlocuiește cu imaginea.

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 și errorWidget sunt funcții builder care primesc context, URL și (pentru errorWidget) obiectul eroare. Această abordare permite afișarea diferitelor substituiri în funcție de URL sau tipul erorii.

Încărcare cu progres

progressIndicatorBuilder — parametru care permite afișarea progresului încărcării în procente. DownloadProgress conține totalSize (poate fi -1 dacă dimensiunea este necunoscută) și 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 — parametru opțional care permite personalizarea afișării imaginii: adăugarea rotunjirii, umbrei, decorației. În exemplu se folosește DecorationImage cu BorderRadius pentru colțuri rotunjite.

Utilizarea CachedNetworkImageProvider

CachedNetworkImageProvider — provider pentru Image sau DecorationImage fără a folosi widgetul CachedNetworkImage. Util la lucrul cu BoxDecoration, FadeInImage sau widgeturi Image personalizate.

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

ImageBuilder și procesarea personalizată

Parametrul imageBuilder din CachedNetworkImage permite înlocuirea widgetului Image standard cu o implementare personalizată. În locul afișării directe a Image, se poate folosi Container cu decorație, ClipRRect cu tăiere sau Ink.image pentru efect ripple. imageBuilder primește contextul și ImageProvider al imaginii gata, oferind control complet asupra randării.

Parametri suplimentari: memCacheWidth și memCacheHeight limitează dimensiunea imaginii stocate în cache în memoria RAM, reducând încărcarea ImageCache Flutter. cacheKey permite setarea unei chei de cache personalizate în locul URL-ului, util pentru imagini cu token-uri de autorizare în URL (parametrii de interogare se schimbă la fiecare cerere, dar conținutul rămâne același).

CachedNetworkImage vs Image.network standard

Widgetul standard Image.network încarcă imaginea la fiecare reconstruire a widgetului fără a o salva pe disc. CachedNetworkImage adaugă cache pe fișiere, progres și gestionarea erorilor, dar adaugă dependența de flutter_cache_manager și SQLite.

Pentru proiecte unde munca offline și economisirea traficului sunt importante, CachedNetworkImage este alegerea clară. Pentru ecrane simple de unică folosință (de exemplu, onboarding sau splash), Image.network nu necesită dependențe suplimentare.

Configurarea CachedNetworkImage în proiectul Flutter

CachedNetworkImage se adaugă ca dependență standard pub.dev. După instalare, widgetul este gata de utilizare. flutter_cache_manager intră ca dependență tranzitivă.

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

Implicit se folosește DefaultCacheManager cu setările: TTL = 7 zile, max 200 fișiere. Pentru modificarea parametrilor globali, se creează o instanță CacheManager personalizată cu Config, unde se suprascriu maxAgeCacheObject, maxNrOfCacheObjects și repo.

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

// Utilizarea managerului personalizat:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes și maxHeightBytes — parametri opționali pentru limitarea dimensiunii fișierului stocat în cache. Acest lucru este util pentru economisirea spațiului pe disc când imaginea originală este mai mare decât dimensiunea necesară a ecranului.