CachedNetworkImage: co to je, klíčové pojmy a widget ImageProvider

Co je CachedNetworkImage?

CachedNetworkImage je widget Flutter ze stejnojmenného balíčku pub.dev, který poskytuje načítání obrázků z sítě s automatickým ukládáním do mezipaměti. Je to vrstva nad standardním Image.network, přidávající ukládání do mezipaměti souborů, indikátory průběhu a vlastní zpracování chyb.

Interně CachedNetworkImage používá flutter_cache_manager — správce mezipaměti s databází SQLite pro sledování souborů. Při prvním požadavku je obrázek stažen z sítě, uložen na disk a při následujících požadavcích je doručen z mezipaměti s ohledem na TTL (ve výchozím nastavení 7 dní). In-memory mezipaměť je spravována standardním ImageCache Flutter.

Balíček má více než 4 000 lajků na pub.dev a používá se v tisících projektů Flutter. CachedNetworkImage podporuje všechny platformy Flutter: Android, iOS, Web, macOS, Windows a Linux. Díky jednotnému API získává vývojář multiplatformní načítání obrázků bez kódu specifického pro platformu.

Jak funguje ukládání obrázků do mezipaměti ve Flutter

Flutter používá dvouúrovňový systém ukládání do mezipaměti: ImageCache (paměť) a flutter_cache_manager (disk + SQLite). ImageCache je globální mezipaměť dekódovaných obrázků s limitem počtu (výchozí 1000) a velikosti (výchozí 100 MB). flutter_cache_manager spravuje soubory na disku a jejich metadata.

Pořadí kontroly

Když CachedNetworkImage obdrží požadavek na obrázek, nejprve zkontroluje ImageCache Flutter — pokud je obrázek již dekódován v paměti, zobrazí se okamžitě. Při neúspěchu je disk zkontrolován prostřednictvím flutter_cache_manager: dotaz SQLite zkontroluje, zda soubor existuje v mezipaměti a zda nevypršela jeho TTL. Pokud je soubor aktuální — je přečten z disku, dekódován a zobrazen. Pokud soubor neexistuje nebo TTL vypršelo — provede se HTTP požadavek.

• ImageCache — globální mezipaměť Flutter, výchozí 1000 prvků / 100 MB
• flutter_cache_manager — SQLite + souborový systém, TTL 7 dní
• HTTP načítání — provádí se prostřednictvím balíčku http nebo vlastního HttpClient

Čištění mezipaměti

DefaultCacheManager poskytuje metody emptyCache() (úplné vyčištění), cleanCache() (smazání pouze prošlých) a clearCacheWithAge() s vlastním datem. ImageCache se čistí automaticky při paměťovém tlaku nebo ručně prostřednictvím imageCache.clear().

Architektura widgetu CachedNetworkImage

CachedNetworkImage je postaven na kompozici standardních widgetů Flutter. Interní implementace používá ImageProvider pro asynchronní načítání a StatefulWidget pro sledování životního cyklu.

Klíčové parametry

imageUrl — povinný parametr, URL obrázku (String nebo Uri). placeholder — widget zobrazený během načítání. errorWidget — widget při chybě načítání. progressIndicatorBuilder — builder přijímající kontext, URL a DownloadProgress s poli totalSize a downloadedSize.

ImageProvider

CachedNetworkImageProvider — implementace ImageProvider vracející CachedNetworkStreamImage, který spravuje stahování a ukládání do mezipaměti. Poskytovatel se integruje s ImageCache Flutter a podporuje všechny možnosti standardního ImageProvider: škálování, centrování a opakování.

Konfigurace flutter_cache_manager

flutter_cache_manager — knihovna, která je základem ukládání do mezipaměti CachedNetworkImage. Poskytuje DefaultCacheManager s nakonfigurovanou databází SQLite, TTL a limitem souborů. V případě potřeby lze vytvořit vlastní CacheManager s jedinečnými parametry.

Vlastní CacheManager se vytváří děděním z CacheManager s přepsáním metod. To je užitečné, když je potřeba ukládat obrázky do samostatného adresáře nebo použít jiného HTTP klienta. Poté je instance správce předána parametru cacheManager v CachedNetworkImage.

Databáze SQLite DefaultCacheManager se nachází v adresáři aplikace temporaryDirectory v cestě `{key}/CacheObjects.db`. Obsahuje tabulku cacheObjects s poli key (URL), relativePath, url, creationDate, eTag, httpHeaders. Při čištění prošlých záznamů se používá SQL dotaz s podmínkou podle maxAgeCacheObject.

Příklady použití CachedNetworkImage v Dart

CachedNetworkImage poskytuje dva hlavní způsoby načítání: widget CachedNetworkImage a provider CachedNetworkImageProvider pro vlastní scénáře.

Základní načítání s placeholderem

CachedNetworkImage — hlavní způsob. Stačí předat imageUrl a placeholder. Widget automaticky zobrazí placeholder do dokončení načítání a nahradí jej obrázkem.

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 a errorWidget jsou funkce builder přijímající kontext, URL a (pro errorWidget) objekt chyby. Tento přístup umožňuje zobrazovat různé náhrady v závislosti na URL nebo typu chyby.

Načítání s průběhem

progressIndicatorBuilder — parametr umožňující zobrazovat průběh načítání v procentech. DownloadProgress obsahuje totalSize (může být -1, pokud není velikost známa) a 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 — volitelný parametr umožňující přizpůsobení zobrazení obrázku: přidání zaoblení, stínu, dekorace. V příkladu se používá DecorationImage s BorderRadius pro zaoblené rohy.

Použití CachedNetworkImageProvider

CachedNetworkImageProvider — provider pro Image nebo DecorationImage bez použití widgetu CachedNetworkImage. Užitečný při práci s BoxDecoration, FadeInImage nebo vlastními widgety Image.

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

ImageBuilder a vlastní zpracování

Parametr imageBuilder v CachedNetworkImage umožňuje nahradit standardní widget Image vlastní implementací. Místo přímého zobrazení Image lze použít Container s dekorací, ClipRRect s oříznutím nebo Ink.image pro efekt vlnění. imageBuilder přijímá kontext a ImageProvider hotového obrázku a poskytuje plnou kontrolu nad vykreslováním.

Další parametry: memCacheWidth a memCacheHeight omezují velikost obrázku uloženého v mezipaměti v RAM, čímž snižují zatížení ImageCache Flutter. cacheKey umožňuje nastavit vlastní klíč mezipaměti namísto URL, což je užitečné pro obrázky s autorizačními tokeny v URL (parametry dotazu se mění při každém požadavku, ale obsah zůstává stejný).

CachedNetworkImage vs standardní Image.network

Standardní widget Image.network načítá obrázek při každém přestavění widgetu bez ukládání na disk. CachedNetworkImage přidává ukládání do mezipaměti souborů, průběh a zpracování chyb, ale přidává závislost na flutter_cache_manager a SQLite.

Pro projekty, kde je důležitá offline práce a úspora přenosu dat, je CachedNetworkImage jednoznačnou volbou. Pro jednoduché jednorázové obrazovky (např. onboarding nebo splash) Image.network nevyžaduje další závislosti.

Nastavení CachedNetworkImage v projektu Flutter

CachedNetworkImage se přidává jako standardní závislost pub.dev. Po instalaci je widget připraven k použití. flutter_cache_manager vstupuje jako tranzitivní závislost.

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

Ve výchozím nastavení se používá DefaultCacheManager s nastavením: TTL = 7 dní, max 200 souborů. Pro změnu globálních parametrů se vytvoří vlastní instance CacheManager s Config, kde se přepíší maxAgeCacheObject, maxNrOfCacheObjects a 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",
    ),
  ),
);

// Použití vlastního správce:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes a maxHeightBytes — volitelné parametry pro omezení velikosti souboru v mezipaměti. To je užitečné pro úsporu místa na disku, když je původní obrázek větší než požadovaná velikost obrazovky.