CachedNetworkImage: mi ez, kulcsfontosságú fogalmak és az ImageProvider widget

Mi az a CachedNetworkImage?

CachedNetworkImage egy Flutter widget az azonos nevű pub.dev csomagból, amely automatikus gyorsítótárazással teszi lehetővé képek betöltését a hálózatról. Ez egy réteg a szabványos Image.network felett, fájlgyorsítótárazást, folyamatjelzőket és egyéni hibakezelést hozzáadva.

Belsőleg a CachedNetworkImage a flutter_cache_manager-t használja — egy gyorsítótár-kezelőt SQLite adatbázissal a fájlok nyomon követéséhez. Az első kérésnél a kép letöltődik a hálózatról, elmentődik a lemezre, és a következő kéréseknél a gyorsítótárból kerül elő a TTL (alapértelmezetten 7 nap) figyelembevételével. A memóriabeli gyorsítótárat a Flutter szabványos ImageCache-je kezeli.

A csomagnak több mint 4 000 kedvelése van a pub.dev-en, és több ezer Flutter projektben használják. A CachedNetworkImage támogatja az összes Flutter platformot: Android, iOS, Web, macOS, Windows és Linux. Az egységes API-nak köszönhetően a fejlesztő platformfüggetlen képbetöltést kap platform-specifikus kód nélkül.

Hogyan működik a képgyorsítótárazás Flutter-ben

A Flutter kétszintű gyorsítótárazási rendszert használ: ImageCache (memória) és flutter_cache_manager (lemez + SQLite). Az ImageCache a dekódolt képek globális gyorsítótára számbeli (alapértelmezetten 1000) és méretbeli (alapértelmezetten 100 MB) korláttal. A flutter_cache_manager a lemezen lévő fájlokat és azok metaadatait kezeli.

Ellenőrzési sorrend

Amikor a CachedNetworkImage képkérést kap, először a Flutter ImageCache-ét ellenőrzi — ha a kép már dekódolva van a memóriában, azonnal megjelenik. Hiány esetén a lemez ellenőrzésre kerül a flutter_cache_manager-en keresztül: egy SQLite lekérdezés ellenőrzi, hogy a fájl létezik-e a gyorsítótárban és nem járt-e le a TTL-je. Ha a fájl aktuális — lemezről olvasásra kerül, dekódolódik és megjelenik. Ha a fájl nem létezik vagy a TTL lejárt — HTTP kérés kerül végrehajtásra.

• ImageCache — Flutter globális gyorsítótár, alapértelmezetten 1000 elem / 100 MB
• flutter_cache_manager — SQLite + fájlrendszer, TTL 7 nap
• HTTP betöltés — a http csomagon vagy egyéni HttpClient-en keresztül történik

Gyorsítótár ürítése

DefaultCacheManager metódusokat biztosít: emptyCache() (teljes ürítés), cleanCache() (csak a lejártak törlése) és clearCacheWithAge() egyéni dátummal. Az ImageCache automatikusan ürül memórianyomás esetén, vagy manuálisan az imageCache.clear() segítségével.

A CachedNetworkImage widget felépítése

A CachedNetworkImage szabványos Flutter widgetek kompozíciójára épül. A belső implementáció ImageProvider-t használ az aszinkron betöltéshez és StatefulWidget-et az életciklus követéséhez.

Kulcsfontosságú paraméterek

imageUrl — kötelező paraméter, a kép URL-je (String vagy Uri). placeholder — a betöltés alatt megjelenített widget. errorWidget — widget betöltési hiba esetén. progressIndicatorBuilder — builder, amely context-et, URL-t és DownloadProgress-et kap a totalSize és downloadedSize mezőkkel.

ImageProvider

CachedNetworkImageProvider — az ImageProvider implementációja, amely CachedNetworkStreamImage-ot ad vissza, kezelve a letöltést és gyorsítótárazást. A provider integrálódik a Flutter ImageCache-szel, és támogatja a szabványos ImageProvider összes képességét: méretezést, középre igazítást és ismétlést.

A flutter_cache_manager konfigurálása

flutter_cache_manager — a CachedNetworkImage gyorsítótárazásának alapjául szolgáló könyvtár. DefaultCacheManager-t biztosít konfigurált SQLite adatbázissal, TTL-lel és fájlkorláttal. Szükség esetén egyéni CacheManager hozható létre egyedi paraméterekkel.

Egyéni CacheManager a CacheManager-ből való örökléssel és metódusok felülírásával hozható létre. Ez akkor hasznos, ha a képeket külön könyvtárban kell tárolni vagy más HTTP klienst kell használni. Ezután a kezelő példánya átadásra kerül a CachedNetworkImage cacheManager paraméterének.

A DefaultCacheManager SQLite adatbázisa az alkalmazás temporaryDirectory könyvtárában található a `{key}/CacheObjects.db` útvonalon. Tartalmazza a cacheObjects táblát key (URL), relativePath, url, creationDate, eTag, httpHeaders mezőkkel. A lejárt rekordok törlésekor SQL lekérdezés használatos a maxAgeCacheObject szerinti feltétellel.

Példák a CachedNetworkImage használatára Dart-ban

A CachedNetworkImage két fő betöltési módot kínál: a CachedNetworkImage widgetet és a CachedNetworkImageProvider-t egyéni forgatókönyvekhez.

Alapvető betöltés helyőrzővel

CachedNetworkImage — a fő mód. Elég megadni az imageUrl-t és a placeholder-t. A widget automatikusan megjeleníti a helyőrzőt a betöltés befejezéséig, majd lecseréli a képre.

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

A placeholder és errorWidget builder függvények, amelyek context-et, URL-t és (az errorWidget esetén) hibaobjektumot kapnak. Ez a megközelítés lehetővé teszi különböző helyettesítők megjelenítését az URL-től vagy a hiba típusától függően.

Betöltés folyamatjelzéssel

progressIndicatorBuilder — paraméter, amely lehetővé teszi a betöltési folyamat százalékos megjelenítését. A DownloadProgress tartalmazza a totalSize-t (lehet -1, ha a méret ismeretlen) és a downloadedSize-t.

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 — opcionális paraméter, amely lehetővé teszi a kép megjelenítésének testreszabását: lekerekítés, árnyék, dekoráció hozzáadása. A példában DecorationImage van használatban BorderRadius-szal a lekerekített sarkokhoz.

CachedNetworkImageProvider használata

CachedNetworkImageProvider — provider Image vagy DecorationImage számára a CachedNetworkImage widget használata nélkül. Hasznos BoxDecoration, FadeInImage vagy egyéni Image widgetekkel való munkánál.

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

ImageBuilder és egyéni feldolgozás

A imageBuilder paraméter a CachedNetworkImage-ben lehetővé teszi a szabványos Image widget egyéni implementációra cserélését. A közvetlen Image megjelenítés helyett használható Container dekorációval, ClipRRect vágással vagy Ink.image hullám effekthez. Az imageBuilder megkapja a kész kép context-jét és ImageProvider-jét, teljes kontrollt adva a renderelés felett.

További paraméterek: memCacheWidth és memCacheHeight korlátozzák a gyorsítótárazott kép méretét a RAM-ban, csökkentve a Flutter ImageCache terhelését. A cacheKey lehetővé teszi egyéni gyorsítótár-kulcs beállítását az URL helyett, ami hasznos az URL-ben hitelesítési tokeneket tartalmazó képeknél (a lekérdezési paraméterek minden kérésnél változnak, de a tartalom ugyanaz marad).

CachedNetworkImage vs szabványos Image.network

A szabványos Image.network widget minden widget-újraépítéskor betölti a képet anélkül, hogy lemezre mentené. A CachedNetworkImage fájlgyorsítótárazást, folyamatjelzést és hibakezelést ad hozzá, de függőséget hoz létre a flutter_cache_manager és SQLite iránt.

Azoknál a projekteknél, ahol fontos az offline munka és a sávszélesség megtakarítás, a CachedNetworkImage egyértelmű választás. Egyszerű egyszeri képernyőknél (pl. onboarding vagy splash) az Image.network nem igényel további függőségeket.

CachedNetworkImage beállítása Flutter projektben

A CachedNetworkImage szabványos pub.dev függőségként kerül hozzáadásra. Telepítés után a widget használatra kész. A flutter_cache_manager tranzitív függőségként kerül be.

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

Alapértelmezetten a DefaultCacheManager kerül használatra a következő beállításokkal: TTL = 7 nap, max 200 fájl. A globális paraméterek módosításához egy egyéni CacheManager példány jön létre Config-gal, ahol a maxAgeCacheObject, maxNrOfCacheObjects és repo felülírásra kerül.

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

// Egyéni kezelő használata:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes és maxHeightBytes — opcionális paraméterek a gyorsítótárazott fájl méretének korlátozására. Ez hasznos a lemezterület megtakarításához, ha az eredeti kép nagyobb a szükséges képernyőméretnél.