CachedNetworkImage: 주요 개념 및 ImageProvider 위젯

CachedNetworkImage란?

CachedNetworkImage는 pub.dev의 동명 패키지에서 제공하는 Flutter 위젯으로, 자동 캐싱으로 네트워크 이미지 로딩을 제공합니다. 표준 Image.network를 래핑하여 파일 캐싱, 진행 표시기 및 사용자 정의 오류 처리를 추가합니다.

내부적으로 CachedNetworkImage는 flutter_cache_manager — 파일 추적을 위한 SQLite 데이터베이스가 있는 캐시 관리자 — 를 사용합니다. 첫 번째 요청 시 이미지가 네트워크에서 다운로드되어 디스크에 저장되고, 후속 요청에서는 TTL(기본 7일)을 고려하여 캐시에서 제공됩니다. 인메모리 캐싱은 Flutter의 표준 ImageCache에 의해 관리됩니다.

이 패키지는 pub.dev에서 4,000개 이상의 좋아요를 보유하고 있으며 수천 개의 Flutter 프로젝트에서 사용됩니다. CachedNetworkImage는 모든 Flutter 플랫폼(Android, iOS, Web, macOS, Windows, Linux)을 지원합니다. 통합 API 덕분에 개발자는 플랫폼별 코드 없이 크로스플랫폼 이미지 로딩을 구현할 수 있습니다.

Flutter에서 이미지 캐싱 작동 방식

Flutter는 2단계 캐싱 시스템을 사용합니다: ImageCache(메모리)와 flutter_cache_manager(디스크 + SQLite). ImageCache는 디코딩된 이미지의 전역 캐시로, 개수(기본 1000개)와 크기(기본 100MB)에 제한이 있습니다. flutter_cache_manager는 디스크의 파일과 해당 메타데이터를 관리합니다.

검색 순서

CachedNetworkImage가 이미지 요청을 받으면 먼저 Flutter의 ImageCache를 확인합니다 — 이미지가 이미 메모리에 디코딩되어 있으면 즉시 표시됩니다. 캐시 미스인 경우 flutter_cache_manager를 통해 디스크를 확인합니다: SQLite 쿼리로 파일이 캐시에 있는지와 TTL이 만료되었는지 확인합니다. 파일이 최신이면 — 디스크에서 읽어 디코딩하여 표시합니다. 파일이 없거나 TTL이 만료되었으면 — HTTP 요청이 실행됩니다.

• ImageCache — 전역 Flutter 캐시, 기본 1000개 항목 / 100MB
• 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 — 컨텍스트, URL 및 totalSize와 downloadedSize 필드가 있는 DownloadProgress를 받는 빌더.

ImageProvider

CachedNetworkImageProvider — 다운로드와 캐싱을 관리하는 CachedNetworkStreamImage를 반환하는 ImageProvider 구현입니다. 이 프로바이더는 Flutter의 ImageCache와 통합되며 크기 조정, 중앙 정렬, 반복 등 모든 표준 ImageProvider 기능을 지원합니다.

flutter_cache_manager 구성

flutter_cache_manager는 CachedNetworkImage 캐싱의 기반 라이브러리입니다. 구성된 SQLite 데이터베이스, TTL 및 파일 제한과 함께 DefaultCacheManager를 제공합니다. 필요에 따라 고유한 매개변수로 사용자 정의 CacheManager를 만들 수 있습니다.

사용자 정의 CacheManager는 메서드 재정의와 함께 CacheManager를 상속하여 생성됩니다. 이는 이미지를 별도 디렉토리에 저장해야 하거나 다른 HTTP 클라이언트가 필요할 때 유용합니다. 그런 다음 관리자 인스턴스가 CachedNetworkImage의 cacheManager 매개변수에 전달됩니다.

DefaultCacheManager의 SQLite 데이터베이스는 애플리케이션의 temporaryDirectory 내 `{key}/CacheObjects.db` 경로에 있습니다. cacheObjects 테이블에는 key(URL), relativePath, url, creationDate, eTag, httpHeaders 필드가 포함됩니다. 만료된 항목을 정리할 때 maxAgeCacheObject에 대한 조건이 있는 SQL 쿼리가 사용됩니다.

Dart에서 CachedNetworkImage 사용 예제

CachedNetworkImage는 CachedNetworkImage 위젯과 사용자 정의 시나리오를 위한 CachedNetworkImageProvider라는 두 가지 주요 로딩 방식을 제공합니다.

플레이스홀더를 사용한 기본 로딩

CachedNetworkImage — 기본 방식입니다. imageUrl과 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 — 이미지 표시를 사용자 정의할 수 있는 선택적 매개변수입니다: 둥근 모서리, 그림자, 장식을 추가할 수 있습니다. 예제에서는 둥근 모서리를 위해 BorderRadius와 함께 DecorationImage를 사용합니다.

CachedNetworkImageProvider 사용

CachedNetworkImageProvider — CachedNetworkImage 위젯 없이 Image 또는 DecorationImage를 위한 프로바이더입니다. BoxDecoration, FadeInImage 또는 사용자 정의 Image 위젯을 사용할 때 유용합니다.

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

ImageBuilder 및 사용자 정의 처리

CachedNetworkImage의 imageBuilder 매개변수를 사용하면 표준 Image 위젯을 사용자 정의 구현으로 재정의할 수 있습니다. Image를 직접 표시하는 대신 장식이 있는 Container, 자르기를 위한 ClipRRect 또는 리플 효과를 위한 Ink.image를 사용할 수 있습니다. imageBuilder는 준비된 이미지의 컨텍스트와 ImageProvider를 받아 렌더링을 완전히 제어할 수 있습니다.

추가 매개변수: memCacheWidth와 memCacheHeight는 RAM의 캐시된 이미지 크기를 제한하여 Flutter ImageCache의 부하를 줄입니다. cacheKey를 사용하면 URL 대신 사용자 정의 캐시 키를 설정할 수 있으며, 이는 URL에 인증 토큰이 있는 이미지(쿼리 매개변수는 요청마다 변경되지만 콘텐츠는 동일하게 유지됨)에 유용합니다.

CachedNetworkImage vs 표준 Image.network

표준 Image.network 위젯은 디스크에 저장하지 않고 위젯이 다시 빌드될 때마다 이미지를 로딩합니다. CachedNetworkImage는 파일 캐싱, 진행 표시기 및 오류 처리를 추가하지만 flutter_cache_manager와 SQLite에 대한 의존성을 추가합니다.

오프라인 기능과 대역폭 절약이 중요한 프로젝트의 경우 CachedNetworkImage가 명확한 선택입니다. 간단한 일회성 화면(예: 온보딩 또는 스플래시)의 경우 Image.network에 추가 의존성이 필요하지 않습니다.

Flutter 프로젝트에 CachedNetworkImage 설정

CachedNetworkImage는 표준 pub.dev 의존성으로 추가됩니다. 설치 후 위젯을 바로 사용할 수 있습니다. flutter_cache_manager는 전이적 의존성으로 포함됩니다.

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

기본적으로 DefaultCacheManager가 설정(TTL = 7일, 최대 200개 파일)과 함께 사용됩니다. 전역 매개변수를 변경하려면 Config로 사용자 정의 CacheManager 인스턴스를 생성하여 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 — 캐시된 파일 크기를 제한하는 선택적 매개변수입니다. 원본 이미지가 필요한 화면 크기보다 큰 경우 디스크 공간을 절약하는 데 유용합니다.