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