CachedNetworkImage: ключові поняття та віджет ImageProvider

Що таке CachedNetworkImage?

CachedNetworkImage — це віджет Flutter з однойменного пакета на pub.dev, що надає завантаження зображень із мережі з автоматичним кешуванням. Він є надбудовою над стандартним Image.network, додаючи файлове кешування, індикатори прогресу та спеціальну обробку помилок.

Всередині CachedNetworkImage використовує flutter_cache_manager — менеджер кешу з базою даних SQLite для відстеження файлів. При першому запиті зображення завантажується з мережі, зберігається на диску, і при наступних запитах видається з кешу з урахуванням TTL (за замовчуванням 7 днів). Кешування в пам'яті керується стандартним 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 — це функції-білдери, що приймають контекст, 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 обмежують розмір кешованого зображення в оперативній пам'яті, знижуючи навантаження на ImageCache Flutter. cacheKey дозволяє задати спеціальний ключ кешу замість URL, що корисно для зображень з токенами авторизації в URL (query-параметри змінюються при кожному запиті, а вміст залишається тим самим).

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