CachedNetworkImage: temel kavramlar ve ImageProvider widget'ı

CachedNetworkImage nedir?

CachedNetworkImage, pub.dev'deki aynı adlı paketten otomatik önbellekleme ile ağ görüntüsü yükleme sağlayan bir Flutter widget'ıdır. Standart Image.network etrafında bir sarmalayıcıdır ve dosya önbellekleme, ilerleme göstergeleri ve özel hata işleme ekler.

Dahili olarak, CachedNetworkImage flutter_cache_manager — dosyaları izlemek için SQLite veritabanına sahip bir önbellek yöneticisi — kullanır. İlk istekte görüntü ağdan indirilir, diske kaydedilir ve sonraki isteklerde TTL (varsayılan 7 gün) dikkate alınarak önbellekten sunulur. Bellek içi önbellekleme, Flutter'ın standart ImageCache'i tarafından yönetilir.

Paketin pub.dev'de 4.000'den fazla beğenisi vardır ve binlerce Flutter projesinde kullanılır. CachedNetworkImage tüm Flutter platformlarını destekler: Android, iOS, Web, macOS, Windows ve Linux. Birleşik bir API sayesinde geliştiriciler, platforma özgü kod olmadan çapraz platform görüntü yükleme elde eder.

Flutter'da görüntü önbellekleme nasıl çalışır

Flutter iki seviyeli bir önbellekleme sistemi kullanır: ImageCache (bellek) ve flutter_cache_manager (disk + SQLite). ImageCache, sayı (varsayılan 1000) ve boyut (varsayılan 100 MB) sınırlamalarıyla kodu çözülmüş görüntülerin küresel bir önbelleğidir. flutter_cache_manager, diskteki dosyaları ve bunların meta verilerini yönetir.

Arama sırası

CachedNetworkImage bir görüntü isteği aldığında, önce Flutter'ın ImageCache'ini kontrol eder — görüntü zaten bellekte kodu çözülmüşse anında görüntülenir. Önbellekte bulunamazsa, flutter_cache_manager aracılığıyla disk kontrol edilir: bir SQLite sorgusu, dosyanın önbellekte olup olmadığını ve TTL'sinin dolup dolmadığını kontrol eder. Dosya güncelse — diskten okunur, kodu çözülür ve görüntülenir. Dosya yoksa veya TTL'si dolmuşsa — bir HTTP isteği yapılır.

• ImageCache — küresel Flutter önbelleği, varsayılan olarak 1000 öğe / 100 MB
• flutter_cache_manager — SQLite + dosya sistemi, TTL 7 gün
• HTTP indirme — http paketi veya özel HttpClient aracılığıyla gerçekleştirilir

Önbellek temizleme

DefaultCacheManager, emptyCache() (tam temizlik), cleanCache() (yalnızca süresi dolanları kaldır) ve özel tarihle clearCacheWithAge() yöntemlerini sağlar. ImageCache, bellek baskısı altında otomatik olarak veya imageCache.clear() aracılığıyla manuel olarak temizlenir.

CachedNetworkImage widget mimarisi

CachedNetworkImage, standart Flutter widget bileşimi üzerine inşa edilmiştir. Dahili uygulama, asenkron yükleme için ImageProvider ve yaşam döngüsü yönetimi için StatefulWidget kullanır.

Anahtar parametreler

imageUrl — zorunlu parametre, görüntü URL'si (String veya Uri). placeholder — yükleme sırasında görüntülenen widget. errorWidget — yükleme hatasında widget. progressIndicatorBuilder — bağlam, URL ve totalSize ile downloadedSize alanlarına sahip DownloadProgress alan builder.

ImageProvider

CachedNetworkImageProvider — indirme ve önbellekleme işlemlerini yöneten CachedNetworkStreamImage döndüren bir ImageProvider uygulamasıdır. Sağlayıcı, Flutter'ın ImageCache'i ile entegre olur ve ölçekleme, ortalaman ve tekrarlama gibi tüm standart ImageProvider özelliklerini destekler.

flutter_cache_manager yapılandırması

flutter_cache_manager, CachedNetworkImage'ın önbelleklemesinin temelindeki kütüphanedir. Yapılandırılmış bir SQLite veritabanı, TTL ve dosya limiti ile DefaultCacheManager sağlar. Gerekirse, benzersiz parametrelerle özel bir CacheManager oluşturulabilir.

Özel bir CacheManager, yöntem geçersiz kılmalarıyla CacheManager'dan miras alınarak oluşturulur. Bu, görüntülerin ayrı bir dizinde saklanması gerektiğinde veya farklı bir HTTP istemcisi gerektiğinde kullanışlıdır. Yönetici örneği daha sonra CachedNetworkImage'ın cacheManager parametresine aktarılır.

DefaultCacheManager'ın SQLite veritabanı, uygulamanın temporaryDirectory'sinde `{key}/CacheObjects.db` yolunda bulunur. cacheObjects tablosu şu alanları içerir: key (URL), relativePath, url, creationDate, eTag, httpHeaders. Süresi dolan girdiler temizlenirken, maxAgeCacheObject üzerinde koşul olan bir SQL sorgusu kullanılır.

Dart'ta CachedNetworkImage kullanım örnekleri

CachedNetworkImage iki ana yükleme yaklaşımı sunar: CachedNetworkImage widget'ı ve özel senaryolar için CachedNetworkImageProvider.

Placeholder ile temel yükleme

CachedNetworkImage — birincil yaklaşım. Sadece imageUrl ve placeholder'ı iletin. Widget, yükleme tamamlanana kadar otomatik olarak placeholder'ı görüntüler ve ardından onu görüntüyle değiştirir.

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 ve errorWidget, bağlam, URL ve (errorWidget için) bir hata nesnesi kabul eden builder işlevleridir. Bu yaklaşım, URL'ye veya hata türüne bağlı olarak farklı placeholder'lar göstermeye olanak tanır.

İlerleme ile yükleme

progressIndicatorBuilder — indirme ilerlemesini yüzde olarak görüntülemeye izin veren bir parametredir. DownloadProgress, totalSize (bilinmiyorsa -1 olabilir) ve downloadedSize içerir.

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 — görüntü görünümünü özelleştirmeye izin veren isteğe bağlı bir parametredir: yuvarlak köşeler, gölgeler, süslemeler ekleme. Örnekte yuvarlak köşeler için BorderRadius ile DecorationImage kullanılır.

CachedNetworkImageProvider kullanımı

CachedNetworkImageProvider — CachedNetworkImage widget'ını kullanmadan Image veya DecorationImage için bir sağlayıcıdır. BoxDecoration, FadeInImage veya özel Image widget'larıyla çalışırken kullanışlıdır.

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

ImageBuilder ve özel işleme

CachedNetworkImage'daki imageBuilder parametresi, standart Image widget'ını özel bir uygulamayla geçersiz kılmaya olanak tanır. Doğrudan Image görüntülemek yerine, süslemeli bir Container, kırpma için ClipRRect veya dalga efekti için Ink.image kullanabilirsiniz. imageBuilder, hazır görüntünün bağlamını ve ImageProvider'ını alarak oluşturma üzerinde tam kontrol sağlar.

Ek parametreler: memCacheWidth ve memCacheHeight, RAM'deki önbelleğe alınmış görüntü boyutunu sınırlayarak Flutter ImageCache üzerindeki yükü azaltır. cacheKey, URL yerine özel bir önbellek anahtarı ayarlamaya izin verir; bu, URL'de yetkilendirme belirteci olan görüntüler için kullanışlıdır (sorgu parametreleri her istekte değişir ancak içerik aynı kalır).

CachedNetworkImage vs standart Image.network

Standart Image.network widget'ı, diske kaydetmeden her widget yeniden oluşumunda görüntüyü yükler. CachedNetworkImage, dosya önbellekleme, ilerleme göstergeleri ve hata işleme ekler ancak flutter_cache_manager ve SQLite bağımlılığı ekler.

Çevrimdışı yetenek ve bant genişliği tasarrufunun önemli olduğu projeler için CachedNetworkImage açık bir seçimdir. Basit tek seferlik ekranlar için (örneğin onboarding veya splash), Image.network ek bağımlılık gerektirmez.

Flutter projesinde CachedNetworkImage kurulumu

CachedNetworkImage, standart bir pub.dev bağımlılığı olarak eklenir. Kurulumdan sonra widget kullanıma hazırdır. flutter_cache_manager, geçişli bir bağımlılık olarak dahil edilir.

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

Varsayılan olarak, DefaultCacheManager şu ayarlarla kullanılır: TTL = 7 gün, maksimum 200 dosya. Küresel parametreleri değiştirmek için, Config ile özel bir CacheManager örneği oluşturulur ve burada maxAgeCacheObject, maxNrOfCacheObjects ve repo geçersiz kılınır.

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",
    ),
  ),
);

// Özel bir yönetici kullanma:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes ve maxHeightBytes — önbelleğe alınmış dosya boyutunu sınırlamak için isteğe bağlı parametrelerdir. Orijinal görüntü gerekli ekran boyutundan büyük olduğunda disk alanından tasarruf etmek için kullanışlıdır.