CachedNetworkImage: bu nədir, əsas anlayışlar və ImageProvider vidjeti

CachedNetworkImage nədir?

CachedNetworkImage — eyni adlı pub.dev paketindən Flutter vidjeti, avtomatik keşləmə ilə şəbəkədən şəkillərin yüklənməsini təmin edir. O, standart Image.network üzərində əlavədir, fayl keşləmə, gedişat göstəriciləri və fərdi səhv idarəetməsi əlavə edir.

Daxildə CachedNetworkImage flutter_cache_manager istifadə edir — faylları izləmək üçün SQLite verilənlər bazası olan keş meneceri. İlk sorğuda şəkil şəbəkədən yüklənir, diskdə saxlanılır və sonrakı sorğularda TTL nəzərə alınmaqla keşdən verilir (standart olaraq 7 gün). In-memory keş Flutter-in standart ImageCache-i tərəfindən idarə olunur.

Paketin pub.dev-də 4 000-dən çox bəyənməsi var və minlərlə Flutter layihəsində istifadə olunur. CachedNetworkImage bütün Flutter platformalarını dəstəkləyir: Android, iOS, Web, macOS, Windows və Linux. Vahid API sayəsində tərtibatçı platforma spesifik kodu olmadan çarpaz platformalı şəkil yükləməsi əldə edir.

Flutter-də şəkil keşləmə necə işləyir

Flutter iki səviyyəli keşləmə sistemindən istifadə edir: ImageCache (yaddaş) və flutter_cache_manager (disk + SQLite). ImageCache — say (standart 1000) və ölçü (standart 100 MB) limiti olan dekodlanmış şəkillərin qlobal keşidir. flutter_cache_manager diskdəki faylları və onların metadatlarını idarə edir.

Yoxlama ardıcıllığı

CachedNetworkImage şəkil sorğusu aldıqda, əvvəlcə Flutter ImageCache-ini yoxlayır — əgər şəkil artıq yaddaşda dekodlanıbsa, dərhal göstərilir. Əskik olduqda, disk flutter_cache_manager vasitəsilə yoxlanılır: SQLite sorğusu faylın keşdə olub-olmadığını və TTL-nin bitmədiyini yoxlayır. Əgər fayl aktualdırsa — diskdən oxunur, dekodlanır və göstərilir. Əgər fayl yoxdursa və ya TTL bitibsə — HTTP sorğusu yerinə yetirilir.

• ImageCache — Flutter qlobal keşi, standart 1000 element / 100 MB
• flutter_cache_manager — SQLite + fayl sistemi, TTL 7 gün
• HTTP yükləmə — http paketi və ya fərdi HttpClient vasitəsilə yerinə yetirilir

Keşin təmizlənməsi

DefaultCacheManager emptyCache() (tam təmizləmə), cleanCache() (yalnız köhnəlmiş silmə) və fərdi tarixlə clearCacheWithAge() metodlarını təqdim edir. ImageCache yaddaş çatışmazlığında avtomatik və ya əl ilə imageCache.clear() vasitəsilə təmizlənir.

CachedNetworkImage vidjetinin arxitekturası

CachedNetworkImage standart Flutter vidjetlərinin kompozisiyası üzərində qurulub. Daxili implementasiya asinxron yükləmə üçün ImageProvider və həyat dövrünü izləmək üçün StatefulWidget istifadə edir.

Əsas parametrlər

imageUrl — məcburi parametr, şəkil URL-i (String və ya Uri). placeholder — yükləmə zamanı göstərilən vidjet. errorWidget — yükləmə xətasında vidjet. progressIndicatorBuilder — kontekst, URL və totalSize və downloadedSize sahələri olan DownloadProgress alan builder.

ImageProvider

CachedNetworkImageProvider — yükləmə və keşləməni idarə edən CachedNetworkStreamImage qaytaran ImageProvider implementasiyası. Provayder Flutter ImageCache ilə inteqrasiya olunur və standart ImageProvider-ın bütün imkanlarını dəstəkləyir: miqyaslama, mərkəzləşdirmə və təkrarlama.

flutter_cache_manager-ın konfiqurasiyası

flutter_cache_manager — CachedNetworkImage keşləməsinin əsasında duran kitabxana. O, konfiqurasiya edilmiş SQLite verilənlər bazası, TTL və fayl limiti ilə DefaultCacheManager təqdim edir. Lazım gəldikdə unikal parametrlərlə fərdi CacheManager yaradıla bilər.

Fərdi CacheManager metodları əvəz etməklə CacheManager-dən miras alınaraq yaradılır. Bu, şəkilləri ayrıca kataloqda saxlamaq və ya fərqli HTTP müştərisi istifadə etmək lazım olduqda faydalıdır. Sonra menecer nüsxəsi CachedNetworkImage-ın cacheManager parametrinə ötürülür.

DefaultCacheManager-in SQLite verilənlər bazası tətbiqin temporaryDirectory kataloqunda `{key}/CacheObjects.db` yolunda yerləşir. O, key (URL), relativePath, url, creationDate, eTag, httpHeaders sahələri olan cacheObjects cədvəlini ehtiva edir. Köhnəlmiş qeydləri təmizləyərkən maxAgeCacheObject-ə görə şərti olan SQL sorğusu istifadə olunur.

Dart-da CachedNetworkImage istifadə nümunələri

CachedNetworkImage iki əsas yükləmə üsulu təqdim edir: CachedNetworkImage vidjeti və fərdi ssenarilər üçün CachedNetworkImageProvider provayderi.

Placeholder ilə əsas yükləmə

CachedNetworkImage — əsas üsul. Sadəcə imageUrl və placeholder ötürmək kifayətdir. Vidjet avtomatik olaraq yükləmə tamamlanana qədər placeholder göstərir və sonra şəkillə əvəz edir.

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 və errorWidget — kontekst, URL və (errorWidget üçün) xəta obyekti qəbul edən builder funksiyalarıdır. Bu yanaşma URL və ya xəta növündən asılı olaraq müxtəlif əvəzedicilər göstərməyə imkan verir.

Gedişatla yükləmə

progressIndicatorBuilder — yükləmə gedişatını faizlə göstərməyə imkan verən parametr. DownloadProgress totalSize (ölçü bilinmirsə -1 ola bilər) və downloadedSize ehtiva edir.

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 — şəkil göstərilməsini fərdiləşdirməyə imkan verən isteğe bağlı parametr: yuvarlaqlaşdırma, kölgə, dekorasiya əlavə etmək. Nümunədə yuvarlaq künclər üçün BorderRadius ilə DecorationImage istifadə olunur.

CachedNetworkImageProvider istifadəsi

CachedNetworkImageProvider — CachedNetworkImage vidjeti olmadan Image və ya DecorationImage üçün provayder. BoxDecoration, FadeInImage və ya fərdi Image vidjetləri ilə işləyərkən faydalıdır.

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

ImageBuilder və fərdi emal

CachedNetworkImage-da imageBuilder parametri standart Image vidjetini fərdi implementasiya ilə əvəz etməyə imkan verir. Birbaşa Image göstərmək əvəzinə dekorasiyalı Container, kəsikli ClipRRect və ya dalğa effekti üçün Ink.image istifadə edilə bilər. imageBuilder hazır şəklin kontekstini və ImageProvider-nı alaraq renderə tam nəzarət verir.

Əlavə parametrlər: memCacheWidth və memCacheHeight operativ yaddaşda keşlənmiş şəklin ölçüsünü məhdudlaşdıraraq Flutter ImageCache yükünü azaldır. cacheKey URL əvəzinə fərdi keş açarı təyin etməyə imkan verir, bu URL-də avtorizasiya tokenləri olan şəkillər üçün faydalıdır (sorğu parametrləri hər dəfə dəyişir, lakin məzmun eyni qalır).

CachedNetworkImage vs standart Image.network

Standart Image.network vidjeti hər vidjet yenidən qurulmasında şəkli diskdə saxlamadan yükləyir. CachedNetworkImage fayl keşləmə, gedişat və səhv idarəetməsi əlavə edir, lakin flutter_cache_manager və SQLite-dən asılılıq yaradır.

Offline iş və trafikə qənaətin vacib olduğu layihələr üçün CachedNetworkImage birbaşa seçimdir. Sadə birdəfəlik ekranlar üçün (məsələn, onboarding və ya splash) Image.network əlavə asılılıq tələb etmir.

Flutter layihəsində CachedNetworkImage-ın qurulması

CachedNetworkImage standart pub.dev asılılığı kimi əlavə olunur. Quraşdırmadan sonra vidjet istifadəyə hazırdır. flutter_cache_manager tranzitiv asılılıq kimi daxil olur.

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

Standart olaraq DefaultCacheManager parametrlərlə istifadə olunur: TTL = 7 gün, maks. 200 fayl. Qlobal parametrləri dəyişmək üçün Config ilə fərdi CacheManager nüsxəsi yaradılır, burada maxAgeCacheObject, maxNrOfCacheObjects və repo əvəz edilir.

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

// Fərdi menecerdən istifadə:
CachedNetworkImage(
    cacheManager: customCacheManager,
    imageUrl: url,
    // ...
)

maxWidthBytes və maxHeightBytes — keşlənmiş faylın ölçüsünü məhdudlaşdırmaq üçün isteğe bağlı parametrlər. Orijinal şəkil lazım olduğundan böyük olduqda disk yerinə qənaət etmək üçün faydalıdır.