CachedNetworkImage: چیست، مفاهیم کلیدی و ویجت ImageProvider

CachedNetworkImage چیست؟

CachedNetworkImage یک ویجت Flutter از بسته pub.dev به همین نام است که بارگذاری تصاویر از شبکه با کش خودکار را فراهم می‌کند. این ویجت یک لایه روی Image.network استاندارد است که کش فایل، نشانگرهای پیشرفت و مدیریت خطای سفارشی را اضافه می‌کند.

در داخل، CachedNetworkImage از flutter_cache_manager استفاده می‌کند — یک مدیر کش با پایگاه داده SQLite برای ردیابی فایل‌ها. در اولین درخواست، تصویر از شبکه بارگذاری می‌شود، روی دیسک ذخیره می‌شود و در درخواست‌های بعدی با در نظر گرفتن TTL (پیش‌فرض ۷ روز) از کش تحویل داده می‌شود. کش درون حافظه توسط ImageCache استاندارد Flutter مدیریت می‌شود.

این بسته بیش از ۴٬۰۰۰ لایک در pub.dev دارد و در هزاران پروژه Flutter استفاده می‌شود. CachedNetworkImage از همه پلتفرم‌های Flutter پشتیبانی می‌کند: Android، iOS، Web، macOS، Windows و Linux. به لطف API یکپارچه، توسعه‌دهنده بارگذاری تصاویر چندپلتفرمی را بدون کد مختص پلتفرم دریافت می‌کند.

کش کردن تصاویر در Flutter چگونه کار می‌کند

Flutter از سیستم کش دو سطحی استفاده می‌کند: ImageCache (حافظه) و flutter_cache_manager (دیسک + SQLite). ImageCache یک کش سراسری از تصاویر رمزگشایی شده با محدودیت تعداد (پیش‌فرض ۱۰۰۰) و اندازه (پیش‌فرض ۱۰۰ مگابایت) است. flutter_cache_manager فایل‌های روی دیسک و فراداده‌های آنها را مدیریت می‌کند.

ترتیب بررسی

وقتی CachedNetworkImage درخواست تصویری دریافت می‌کند، ابتدا ImageCache Flutter را بررسی می‌کند — اگر تصویر قبلاً در حافظه رمزگشایی شده باشد، فوراً نمایش داده می‌شود. در صورت عدم وجود، دیسک از طریق flutter_cache_manager بررسی می‌شود: پرس‌وجوی SQLite بررسی می‌کند که آیا فایل در کش وجود دارد و TTL آن منقضی نشده است. اگر فایل به‌روز باشد — از دیسک خوانده می‌شود، رمزگشایی می‌شود و نمایش داده می‌شود. اگر فایل وجود نداشته باشد یا TTL منقضی شده باشد — درخواست HTTP انجام می‌شود.

• ImageCache — کش سراسری Flutter، پیش‌فرض ۱۰۰۰ عنصر / ۱۰۰ مگابایت
• flutter_cache_manager — SQLite + سیستم فایل، TTL ۷ روز
• بارگذاری HTTP — از طریق بسته http یا HttpClient سفارشی انجام می‌شود

پاک کردن کش

DefaultCacheManager متدهای emptyCache() (پاک کردن کامل)، cleanCache() (حذف فقط موارد منقضی) و clearCacheWithAge() با تاریخ سفارشی را ارائه می‌دهد. ImageCache به طور خودکار در فشار حافظه یا به صورت دستی از طریق 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 توابع builder هستند که زمینه، URL و (برای errorWidget) شیء خطا را دریافت می‌کنند. این رویکرد امکان نمایش جایگزین‌های مختلف را بسته به URL یا نوع خطا فراهم می‌کند.

بارگذاری با پیشرفت

progressIndicatorBuilder — پارامتری که امکان نمایش درصد پیشرفت بارگذاری را فراهم می‌کند. DownloadProgress شامل totalSize (می‌تواند -۱ باشد اگر اندازه نامشخص است) و 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 برای اثر موج استفاده کرد. imageBuilder زمینه و ImageProvider تصویر آماده را دریافت می‌کند و کنترل کامل روی رندرینگ می‌دهد.

پارامترهای اضافی: memCacheWidth و memCacheHeight اندازه تصویر کش شده در حافظه رم را محدود می‌کنند و بار ImageCache Flutter را کاهش می‌دهند. cacheKey امکان تنظیم کلید کش سفارشی به جای URL را فراهم می‌کند که برای تصاویر با توکن‌های مجوز در URL مفید است (پارامترهای پرس‌وجو در هر بار تغییر می‌کنند اما محتوا یکسان می‌ماند).

CachedNetworkImage در مقابل Image.network استاندارد

ویجت استاندارد Image.network تصویر را در هر بار بازسازی ویجت بدون ذخیره روی دیسک بارگذاری می‌کند. CachedNetworkImage کش فایل، پیشرفت و مدیریت خطا را اضافه می‌کند، اما وابستگی به flutter_cache_manager و SQLite را نیز اضافه می‌کند.

برای پروژه‌هایی که کار آفلاین و صرفه‌جویی در ترافیک مهم است، CachedNetworkImage انتخاب قطعی است. برای صفحه‌های ساده یکبار مصرف (مانند راهنمای ورود یا اسپلش) Image.network به وابستگی‌های اضافی نیاز ندارد.

راه‌اندازی CachedNetworkImage در پروژه Flutter

CachedNetworkImage به عنوان یک وابستگی استاندارد pub.dev اضافه می‌شود. پس از نصب، ویجت آماده استفاده است. flutter_cache_manager به عنوان وابستگی گذرا وارد می‌شود.

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

به طور پیش‌فرض از DefaultCacheManager با تنظیمات: TTL = ۷ روز، حداکثر ۲۰۰ فایل استفاده می‌شود. برای تغییر پارامترهای سراسری، یک نمونه 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 — پارامترهای اختیاری برای محدود کردن اندازه فایل کش شده. این برای صرفه‌جویی در فضای دیسک زمانی که تصویر اصلی بزرگ‌تر از اندازه صفحه مورد نیاز است مفید می‌باشد.