CachedNetworkImage: шта је то, кључни појмови и ImageProvider виџет

Шта је CachedNetworkImage?

CachedNetworkImage је Flutter виџет из истоименог pub.dev пакета, који пружа учитавање слика из мреже са аутоматским кеширањем. Он је надоградња стандардног Image.network-а, додајући фајловско кеширање, индикаторе напретка и прилагођену обраду грешака.

Унутрашње, CachedNetworkImage користи flutter_cache_manager — менаџер кеша са SQLite базом података за праћење фајлова. При првом захтеву, слика се учитава из мреже, чува на диску, а при наредним захтевима се испоручује из кеша узимајући у обзир TTL (подразумевано 7 дана). In-memory кешом управља стандардни Flutter ImageCache.

Пакет има више од 4 000 лајкова на pub.dev-у и користи се у хиљадама Flutter пројеката. CachedNetworkImage подржава све Flutter платформе: Android, iOS, Web, macOS, Windows и Linux. Захваљујући јединственом API-ју, програмер добија вишеплатформско учитавање слика без кода специфичног за платформу.

Како функционише кеширање слика у Flutter-у

Flutter користи двостепени систем кеширања: ImageCache (меморија) и flutter_cache_manager (диск + SQLite). ImageCache је глобални кеш декодираних слика са лимитом броја (подразумевано 1000) и величине (подразумевано 100 MB). flutter_cache_manager управља фајловима на диску и њиховим метаподацима.

Редослед провере

Када CachedNetworkImage прими захтев за сликом, прво проверава ImageCache Flutter-а — ако је слика већ декодирана у меморији, приказује се тренутно. При промашају, диск се проверава кроз flutter_cache_manager: SQLite упит проверава да ли фајл постоји у кешу и да ли му је TTL истекао. Ако је фајл актуелан — чита се са диска, декодира и приказује. Ако фајл не постоји или је TTL истекао — извршава се HTTP захтев.

• ImageCache — глобални кеш Flutter-а, подразумевано 1000 елемената / 100 MB
• flutter_cache_manager — SQLite + фајл систем, TTL 7 дана
• HTTP учитавање — извршава се кроз http пакет или прилагођени HttpClient

Чишћење кеша

DefaultCacheManager пружа методе emptyCache() (потпуно чишћење), cleanCache() (брисање само застарелих) и clearCacheWithAge() са прилагођеним датумом. ImageCache се чисти аутоматски при притиску на меморију или ручно кроз imageCache.clear().

Архитектура CachedNetworkImage виџета

CachedNetworkImage је изграђен на композицији стандардних Flutter виџета. Унутрашња имплементација користи ImageProvider за асинхроно учитавање и StatefulWidget за праћење животног циклуса.

Кључни параметри

imageUrl — обавезни параметар, URL слике (String или Uri). placeholder — виџет приказан током учитавања. errorWidget — виџет при грешци учитавања. progressIndicatorBuilder — builder који прима контекст, URL и DownloadProgress са пољима totalSize и downloadedSize.

ImageProvider

CachedNetworkImageProvider — имплементација ImageProvider-а која враћа CachedNetworkStreamImage, који управља преузимањем и кеширањем. Провајдер се интегрише са Flutter ImageCache-ом и подржава све могућности стандардног ImageProvider-а: скалирање, центрирање и понављање.

Подешавање flutter_cache_manager-а

flutter_cache_manager — библиотека која је основа кеширања CachedNetworkImage-а. Пружа DefaultCacheManager са подешеном SQLite базом, TTL-ом и лимитом фајлова. По потреби се може креирати прилагођени CacheManager са јединственим параметрима.

Прилагођени CacheManager се креира наслеђивањем CacheManager-а са преписивањем метода. Ово је корисно када треба чувати слике у посебном директоријуму или користити другачији HTTP клијент. Затим се инстанца менаџера прослеђује cacheManager параметру CachedNetworkImage-а.

SQLite база DefaultCacheManager-а налази се у директоријуму апликације temporaryDirectory на путањи `{key}/CacheObjects.db`. Садржи табелу cacheObjects са пољима key (URL), relativePath, url, creationDate, eTag, httpHeaders. При чишћењу застарелих записа користи се SQL упит са условом по maxAgeCacheObject-у.

Примери коришћења CachedNetworkImage у Dart-у

CachedNetworkImage пружа два главна начина учитавања: виџет CachedNetworkImage и провајдер CachedNetworkImageProvider за прилагођене сценарије.

Основно учитавање са placeholder-ом

CachedNetworkImage — основни начин. Довољно је проследити imageUrl и placeholder. Виџет аутоматски приказује placeholder до завршетка учитавања и замењује га сликом.

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 и errorWidget су функције-builder које примају контекст, URL и (за errorWidget) објекат грешке. Овај приступ омогућава приказивање различитих резервних садржаја у зависности од URL-а или типа грешке.

Учитавање са напретком

progressIndicatorBuilder — параметар који омогућава приказивање напретка учитавања у процентима. DownloadProgress садржи totalSize (може бити -1 ако је величина непозната) и 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 — опциони параметар који омогућава прилагођавање приказа слике: додавање заобљења, сенке, декорације. У примеру се користи DecorationImage са BorderRadius за округле углове.

Коришћење CachedNetworkImageProvider-а

CachedNetworkImageProvider — провајдер за Image или DecorationImage без коришћења CachedNetworkImage виџета. Користан при раду са BoxDecoration, FadeInImage или прилагођеним Image виџетима.

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

ImageBuilder и прилагођена обрада

Параметар imageBuilder у CachedNetworkImage-у омогућава замену стандардног Image виџета прилагођеном имплементацијом. Уместо директног приказивања Image-а, може се користити Container са декорацијом, ClipRRect са обрезивањем или Ink.image за ripple ефекат. imageBuilder прима контекст и ImageProvider готове слике, дајући потпуну контролу над рендеровањем.

Додатни параметри: memCacheWidth и memCacheHeight ограничавају величину кеширане слике у RAM меморији, смањујући оптерећење Flutter ImageCache-а. cacheKey омогућава постављање прилагођеног кључа кеша уместо URL-а, што је корисно за слике са токенима за ауторизацију у URL-у (параметри упита се мењају при сваком захтеву, али садржај остаје исти).

CachedNetworkImage vs стандардни Image.network

Стандардни виџет Image.network учитава слику при сваком поновном изграђивању виџета без чувања на диску. CachedNetworkImage додаје фајловско кеширање, напредак и обраду грешака, али додаје зависност од flutter_cache_manager-а и SQLite-а.

За пројекте где су важни рад ван мреже и уштеда саобраћаја, CachedNetworkImage је недвосмислен избор. За једноставне екране за једнократну употребу (нпр. onboarding или splash), Image.network не захтева додатне зависности.

Подешавање CachedNetworkImage у Flutter пројекту

CachedNetworkImage се додаје као стандардна pub.dev зависност. Након инсталације, виџет је спреман за употребу. flutter_cache_manager улази као транзитивна зависност.

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

Подразумевано се користи DefaultCacheManager са подешавањима: TTL = 7 дана, макс 200 фајлова. За промену глобалних параметара, креира се прилагођена инстанца CacheManager-а са Config-ом, где се преписују maxAgeCacheObject, maxNrOfCacheObjects и 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",
    ),
  ),
);

// Коришћење прилагођеног менаџера:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes и maxHeightBytes — опциони параметри за ограничавање величине кешираног фајла. Ово је корисно за уштеду простора на диску када је оригинална слика већа од потребне величине екрана.