CachedNetworkImage: vad är det, nyckelbegrepp och widgeten ImageProvider

Vad är CachedNetworkImage?

CachedNetworkImage är en Flutter-widget från samma pub.dev-paket som tillhandahåller laddning av bilder från nätverket med automatisk cachelagring. Det är ett lager ovanpå standard Image.network som lägger till filcachelagring, förloppsindikatorer och anpassad felhantering.

Internt använder CachedNetworkImage flutter_cache_manager — en cachehanterare med SQLite-databas för att spåra filer. Vid den första begäran laddas bilden ner från nätverket, sparas på disk och vid efterföljande begäranden levereras från cachen med hänsyn till TTL (som standard 7 dagar). In-memory-cachen hanteras av Flutters standard ImageCache.

Paketet har mer än 4 000 gilla-markeringar på pub.dev och används i tusentals Flutter-projekt. CachedNetworkImage stöder alla Flutter-plattformar: Android, iOS, Web, macOS, Windows och Linux. Tack vare det enhetliga API:et får utvecklaren plattformsoberoende bildladdning utan plattformsspecifik kod.

Hur fungerar cachelagring av bilder i Flutter

Flutter använder ett två nivåers cachesystem: ImageCache (minne) och flutter_cache_manager (disk + SQLite). ImageCache är en global cache av avkodade bilder med gräns för antal (standard 1 000) och storlek (standard 100 MB). flutter_cache_manager hanterar filer på disk och deras metadata.

Kontrollordning

När CachedNetworkImage tar emot en bildbegäran kontrollerar den först Flutters ImageCache — om bilden redan är avkodad i minnet visas den omedelbart. Vid en miss kontrolleras disken via flutter_cache_manager: en SQLite-fråga kontrollerar om filen finns i cachen och om dess TTL inte har löpt ut. Om filen är aktuell — läses den från disken, avkodas och visas. Om filen inte finns eller TTL har löpt ut — utförs en HTTP-begäran.

• ImageCache — global Flutter-cache, standard 1 000 element / 100 MB
• flutter_cache_manager — SQLite + filsystem, TTL 7 dagar
• HTTP-laddning — utförs via http-paketet eller anpassad HttpClient

Rensa cache

DefaultCacheManager tillhandahåller metoder emptyCache() (fullständig rensning), cleanCache() (ta bara bort föråldrade) och clearCacheWithAge() med anpassat datum. ImageCache rensas automatiskt vid minnestryck eller manuellt via imageCache.clear().

Arkitekturen för CachedNetworkImage-widgeten

CachedNetworkImage är byggd på komposition av standard Flutter-widgets. Den interna implementeringen använder ImageProvider för asynkron laddning och StatefulWidget för att spåra livscykeln.

Nyckelparametrar

imageUrl — obligatorisk parameter, bildens URL (String eller Uri). placeholder — widget som visas under laddning. errorWidget — widget vid laddningsfel. progressIndicatorBuilder — builder som tar emot context, URL och DownloadProgress med fälten totalSize och downloadedSize.

ImageProvider

CachedNetworkImageProvider — ImageProvider-implementering som returnerar CachedNetworkStreamImage, vilket hanterar nedladdning och cachelagring. Providern integreras med Flutters ImageCache och stöder alla funktioner i standard ImageProvider: skalning, centrering och upprepning.

Konfiguration av flutter_cache_manager

flutter_cache_manager — biblioteket som ligger till grund för CachedNetworkImage-cachelagring. Det tillhandahåller DefaultCacheManager med konfigurerad SQLite-databas, TTL och filgräns. Vid behov kan en anpassad CacheManager med unika parametrar skapas.

En anpassad CacheManager skapas genom arv från CacheManager med överskrivning av metoder. Detta är användbart när bilder måste lagras i en separat katalog eller en annan HTTP-klient måste användas. Sedan skickas hanterarinstansen till cacheManager-parametern i CachedNetworkImage.

SQLite-databasen för DefaultCacheManager finns i applikationens temporaryDirectory på sökvägen `{key}/CacheObjects.db`. Den innehåller tabellen cacheObjects med fälten key (URL), relativePath, url, creationDate, eTag, httpHeaders. Vid rensning av föråldrade poster används en SQL-fråga med villkor baserat på maxAgeCacheObject.

Exempel på användning av CachedNetworkImage i Dart

CachedNetworkImage tillhandahåller två huvudsakliga sätt att ladda: CachedNetworkImage-widgeten och CachedNetworkImageProvider för anpassade scenarier.

Grundladdning med placeholder

CachedNetworkImage — det huvudsakliga sättet. Det räcker att skicka imageUrl och placeholder. Widgeten visar automatiskt platshållaren tills laddningen är klar och ersätter den med bilden.

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 och errorWidget är builder-funktioner som tar emot context, URL och (för errorWidget) felobjektet. Detta tillvägagångssätt gör det möjligt att visa olika ersättningar beroende på URL eller feltyp.

Laddning med förlopp

progressIndicatorBuilder — parameter som gör det möjligt att visa laddningsförloppet i procent. DownloadProgress innehåller totalSize (kan vara -1 om storleken är okänd) och 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 — valfri parameter som gör det möjligt att anpassa bildvisningen: lägga till rundning, skugga, dekoration. I exemplet används DecorationImage med BorderRadius för rundade hörn.

Användning av CachedNetworkImageProvider

CachedNetworkImageProvider — provider för Image eller DecorationImage utan att använda CachedNetworkImage-widgeten. Användbar vid arbete med BoxDecoration, FadeInImage eller anpassade Image-widgets.

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

ImageBuilder och anpassad bearbetning

Parametern imageBuilder i CachedNetworkImage gör det möjligt att ersätta standard Image-widgeten med en anpassad implementering. Istället för direkt visning av Image kan Container med dekoration, ClipRRect med beskärning eller Ink.image för ripple-effekt användas. imageBuilder tar emot context och ImageProvider för den färdiga bilden och ger full kontroll över renderingen.

Ytterligare parametrar: memCacheWidth och memCacheHeight begränsar storleken på den cachade bilden i RAM-minnet, vilket minskar belastningen på Flutters ImageCache. cacheKey gör det möjligt att ställa in en anpassad cache-nyckel istället för URL, vilket är användbart för bilder med auktoriseringstoken i URL:en (frågeparametrar ändras vid varje begäran, men innehållet förblir detsamma).

CachedNetworkImage vs standard Image.network

Standardwidgeten Image.network laddar bilden vid varje widgetombyggnad utan att spara den på disk. CachedNetworkImage lägger till filcachelagring, förlopp och felhantering, men lägger till ett beroende av flutter_cache_manager och SQLite.

För projekt där offline-arbete och bandbreddsbesparing är viktiga är CachedNetworkImage det självklara valet. För enkla engångsskärmar (t.ex. onboarding eller splash) kräver Image.network inga ytterligare beroenden.

Konfigurera CachedNetworkImage i ett Flutter-projekt

CachedNetworkImage läggs till som ett standard pub.dev-beroende. Efter installation är widgeten redo att användas. flutter_cache_manager kommer in som ett transitivt beroende.

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

Som standard används DefaultCacheManager med inställningarna: TTL = 7 dagar, max 200 filer. För att ändra globala parametrar skapas en anpassad CacheManager-instans med Config, där maxAgeCacheObject, maxNrOfCacheObjects och repo skrivs över.

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

// Användning av anpassad hanterare:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes och maxHeightBytes — valfria parametrar för att begränsa storleken på den cachade filen. Detta är användbart för att spara diskutrymme när den ursprungliga bilden är större än den nödvändiga skärmstorleken.