CachedNetworkImage: какво е това, ключови понятия и ImageProvider изглед

Какво е CachedNetworkImage?

CachedNetworkImage е Flutter изглед от едноименния pub.dev пакет, който осигурява зареждане на изображения от мрежата с автоматично кеширане. Той е слой върху стандартния Image.network, добавящ файлово кеширане, индикатори за напредък и персонализирана обработка на грешки.

Вътрешно, CachedNetworkImage използва flutter_cache_manager — мениджър на кеша с база данни SQLite за проследяване на файлове. При първото искане, изображението се изтегля от мрежата, записва се на диска и при последващи искания се доставя от кеша, като се взема предвид TTL (по подразбиране 7 дни). In-memory кешът се управлява от стандартния ImageCache на Flutter.

Пакетът има повече от 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, който управлява изтеглянето и кеширането. Провайдърът се интегрира с ImageCache на Flutter и поддържа всички възможности на стандартния 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 паметта, намалявайки натоварването на ImageCache на Flutter. cacheKey позволява задаване на персонализиран ключ за кеша вместо URL, което е полезно за изображения с токени за упълномощаване в URL (параметрите на заявката се променят при всяка заявка, но съдържанието остава същото).

CachedNetworkImage срещу стандартния 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 — опционални параметри за ограничаване на размера на кеширания файл. Това е полезно за икономия на дисково пространство, когато оригиналното изображение е по-голямо от необходимия размер на екрана.