شرح استخدام Cached Network Image في Flutter

تُعد حزمة cached_network_image واحدة من الحزم المهمة في تطوير تطبيقات Flutter، حيث تتيح للمطورين تحميل الصور من الإنترنت وتخزينها مؤقتاً لعرضها لاحقاً بدون الحاجة إلى إعادة تحميلها. هذا المقال سيوضح كيفية استخدام هذه الحزمة مع شرح للأكواد ونواتجها.

تثبيت حزمة Cached Network Image

لتثبيت الحزمة، يجب عليك تعديل ملف pubspec.yaml الخاص بمشروعك. أضف السطر التالي ضمن قسم dependencies:

dependencies:
  flutter:
    sdk: flutter
  cached_network_image: ^3.3.1

بعد ذلك، قم بتشغيل الأمر التالي في الـ terminal لتثبيت الحزمة:

flutter pub get

“اقرأ أيضاً: شرح استخدام introduction_screen في Flutter“

استخدام الحزمة في التطبيق

استيراد الحزمة

بعد تثبيت الحزمة، يمكنك استيرادها في ملف Dart الخاص بك:

import 'package:cached_network_image/cached_network_image.dart';

عرض صورة من الانترنت

لاستخدام الحزمة لعرض صورة من الإنترنت، يمكنك استخدام CachedNetworkImage بدلاً من Image.network. المثال التالي يوضح كيفية استخدام CachedNetworkImage:

import 'package:flutter/material.dart';
import 'package:cached_network_image/cached_network_image.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Cached Network Image Example'),
        ),
        body: Center(
          child: CachedNetworkImage(
            imageUrl: "https://via.placeholder.com/150",
            placeholder: (context, url) => CircularProgressIndicator(),
            errorWidget: (context, url, error) => Icon(Icons.error),
          ),
        ),
      ),
    );
  }
}

شرح الكود

• استيراد الحزمة: تم استيراد حزمة cached_network_image لاستخدام مكوناتها.
• CachedNetworkImage: يتم استخدام هذه الويدجت لعرض الصورة.
• imageUrl: يُستخدم لتحديد رابط الصورة التي سيتم تحميلها.
• placeholder: يُعرض أثناء تحميل الصورة.
• errorWidget: يُعرض في حال فشل تحميل الصورة.

ناتج الكود

عند تشغيل التطبيق، ستظهر صورة من الرابط المحدد، وفي حال تحميل الصورة سيتم عرض مؤشر التحميل، وإذا حدث خطأ سيتم عرض أيقونة الخطأ.

“اقرأ أيضاً: شرح استخدام Font Awesome في Flutter“

الخصائص الأساسية في Cached Network Image

imageUrl

• الوصف: رابط الصورة التي سيتم تحميلها.
• نوع البيانات: String
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
  )

httpHeaders

• الوصف: رؤوس HTTP المخصصة التي يمكن إضافتها إلى طلب الصورة.
• نوع البيانات: Map<String, String>?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    httpHeaders: {"Authorization": "Bearer your_token_here"},
  )

imageBuilder

• الوصف: دالة تبني الويدجت الخاص بالصورة بعد تحميلها.
• نوع البيانات: Widget Function(BuildContext, ImageProvider<Object>)?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    imageBuilder: (context, imageProvider) => Container(
      decoration: BoxDecoration(
        image: DecorationImage(
          image: imageProvider,
          fit: BoxFit.cover,
        ),
      ),
    ),
  )

placeholder

• الوصف: ويدجت يُعرض أثناء تحميل الصورة من الانترنت.
• نوع البيانات: Widget Function(BuildContext, String)?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    placeholder: (context, url) => CircularProgressIndicator(),
  )

progressIndicatorBuilder

• الوصف: ويدجت يُعرض أثناء تحميل الصورة مع مؤشر التقدم.
• نوع البيانات: Widget Function(BuildContext, String, DownloadProgress)?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    progressIndicatorBuilder: (context, url, downloadProgress) =>
        CircularProgressIndicator(value: downloadProgress.progress),
  )

errorWidget

• الوصف: ويدجت يُعرض في حالة حدوث خطأ أثناء تحميل الصورة.
• نوع البيانات: Widget Function(BuildContext, String, Object)?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    errorWidget: (context, url, error) => Icon(Icons.error),
  )

“اقرأ أيضاً: شرح استخدام ويدجت AnimatedList في فلاتر“

خصائص التحريك والتأثيرات في Cached Network Image

fadeOutDuration

• الوصف: مدة تأثير التلاشي عند إزالة الصورة.
• نوع البيانات: Duration?
• القيمة الافتراضية: const Duration(milliseconds: 1000)
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    fadeOutDuration: Duration(milliseconds: 500),
  )

fadeOutCurve

• الوصف: منحنى التلاشي عند إزالة الصورة.
• نوع البيانات: Curve
• القيمة الافتراضية: Curves.easeOut
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    fadeOutCurve: Curves.easeInOut,
  )

fadeInDuration

• الوصف: مدة تأثير التلاشي عند تحميل الصورة.
• نوع البيانات: Duration?
• القيمة الافتراضية: const Duration(milliseconds: 500)
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    fadeInDuration: Duration(milliseconds: 700),
  )

fadeInCurve

• الوصف: منحنى التلاشي عند تحميل الصورة.
• نوع البيانات: Curve
• القيمة الافتراضية: Curves.easeIn
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    fadeInCurve: Curves.easeInOut,
  )

“اقرأ أيضاً: شرح أنواع الدوال functions في لغة دارت (Dart)“

خصائص الحجم والمظهر في Cached Network Image

width و height

• الوصف: تحديد عرض وارتفاع الصورة.
• نوع البيانات: double?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    width: 100,
    height: 100,
  )

fit

• الوصف: كيفية ملاءمة الصورة داخل الويدجت.
• نوع البيانات: BoxFit?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    fit: BoxFit.cover,
  )

alignment

• الوصف: محاذاة الصورة داخل الويدجت.
• نوع البيانات: Alignment
• القيمة الافتراضية: Alignment.center
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    alignment: Alignment.topLeft,
  )

repeat

• الوصف: تحديد كيفية تكرار الصورة إذا كانت أصغر من الحاوية.
• نوع البيانات: ImageRepeat
• القيمة الافتراضية: ImageRepeat.noRepeat
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    repeat: ImageRepeat.repeat,
  )

matchTextDirection

• الوصف: يحدد ما إذا كان يجب محاذاة الصورة بناءً على اتجاه النص.
• نوع البيانات: bool
• القيمة الافتراضية: false
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    matchTextDirection: true,
  )

خصائص التخزين المؤقت في Cached Network Image

cacheManager

• الوصف: إدارة مخصصة للتخزين المؤقت.
• نوع البيانات: BaseCacheManager?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    cacheManager: CustomCacheManager(),
  )

useOldImageOnUrlChange

• الوصف: يحدد ما إذا كان يجب استخدام الصورة القديمة عند تغيير الرابط.
• نوع البيانات: bool
• القيمة الافتراضية: false
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    useOldImageOnUrlChange: true,
  )

cacheKey

• الوصف: مفتاح مخصص للصورة في التخزين المؤقت.
• نوع البيانات: String?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    cacheKey: "customKey",
  )

maxWidthDiskCache و maxHeightDiskCache

• الوصف: تحديد أقصى عرض وارتفاع للصورة في التخزين المؤقت.
• نوع البيانات: int?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    maxWidthDiskCache: 200,
    maxHeightDiskCache: 200,
  )

خصائص إضافية في Cached Network Image

color و colorBlendMode

• الوصف: لتلوين الصورة وتحديد وضع المزج.
• نوع البيانات: Color? و BlendMode?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    color: Colors.red,
    colorBlendMode: BlendMode.colorBurn,
  )

filterQuality

• الوصف: جودة الفلترة عند عرض الصورة.
• نوع البيانات: FilterQuality
• القيمة الافتراضية: FilterQuality.low
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    filterQuality: FilterQuality.high,
  )

placeholderFadeInDuration

• الوصف: مدة تأثير التلاشي عند عرض الصورة.
• نوع البيانات: Duration?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    placeholderFadeInDuration: Duration(milliseconds: 300),
  )

errorListener

• الوصف: دالة لاستقبال الأخطاء أثناء تحميل الصورة.
• نوع البيانات: void Function(Object)?
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    errorListener: (error) {
      print("Error loading image: $error");
    },
  )

imageRenderMethodForWeb

• الوصف: تحديد طريقة عرض الصورة للويب.
• نوع البيانات: ImageRenderMethodForWeb
• القيمة الافتراضية: ImageRenderMethodForWeb.HtmlImage
• مثال:

  CachedNetworkImage(
    imageUrl: "https://via.placeholder.com/150",
    imageRenderMethodForWeb: ImageRenderMethodForWeb.HttpGet,
  )

باستخدام هذه الخصائص المختلفة، يمكنك تخصيص تجربة تحميل وعرض الصور في تطبيقك بطرق عديدة، مما يوفر أداءً أفضل وتجربة مستخدم أكثر سلاسة ومرونة.

“اقرأ أيضاً: شرح جملة الشرط If في لغة دارت“

حزمة cached_network_image تُعد أداة قوية وفعالة لتحميل وعرض الصور من الإنترنت في تطبيقات Flutter مع ميزات التخزين المؤقت. من خلال استخدام هذه الحزمة، يمكنك تحسين أداء تطبيقك وتقليل استهلاك البيانات بشكل كبير.

لا تتردد في استكشاف المزيد من الميزات والخيارات المتاحة في الوثائق الرسمية للحزمة لمزيد من التحكم والمرونة في تطبيقاتك.