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 دو سطحی کیشنگ سسٹم استعمال کرتا ہے: ImageCache (میموری) اور flutter_cache_manager (ڈسک + SQLite)۔ ImageCache تعداد (پہلے سے طے شدہ 1000) اور سائز (پہلے سے طے شدہ 100 MB) کی حدود کے ساتھ ڈی کوڈ شدہ تصاویر کا عالمی کیش ہے۔ flutter_cache_manager ڈسک پر فائلوں اور ان کے میٹا ڈیٹا کا انتظام کرتا ہے۔

تلاش کا سلسلہ

جب CachedNetworkImage کو تصویر کی درخواست ملتی ہے، تو یہ پہلے Flutter کے ImageCache کو چیک کرتا ہے — اگر تصویر پہلے سے میموری میں ڈی کوڈ ہے، تو یہ فوری طور پر ظاہر ہوتی ہے۔ کیش مس ہونے پر، 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 اور totalSize اور downloadedSize فیلڈز کے ساتھ DownloadProgress حاصل کرتا ہے۔

ImageProvider

CachedNetworkImageProvider — ImageProvider کا نفاذ جو CachedNetworkStreamImage لوٹاتا ہے، جو ڈاؤن لوڈنگ اور کیشنگ کا انتظام کرتا ہے۔ فراہم کنندہ 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۔

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 builder فنکشنز ہیں جو سیاق و سباق، URL اور (errorWidget کے لیے) ایرر آبجیکٹ قبول کرتے ہیں۔ یہ طریقہ URL یا ایرر کی قسم کے مطابق مختلف placeholder دکھانے کی اجازت دیتا ہے۔

پیش رفت کے ساتھ لوڈنگ

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 بمقابلہ معیاری 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 — کیش شدہ فائل کے سائز کو محدود کرنے کے لیے اختیاری پیرامیٹرز۔ یہ ڈسک کی جگہ بچانے کے لیے مفید ہے جب اصل تصویر مطلوبہ اسکرین سائز سے بڑی ہو۔