إضافة الصور في Flutter عبر assets وpubspec.yaml، مع المسارات الصحيحة والمجلدات الفرعية وأبعاد العرض ومعالجة فشل تحميل الصورة دون متغيرات ناقصة.
الأصل المضمّن يختلف عن ملف الجهاز
asset ملف تضيفه إلى المشروع ويُضمّن في حزمة التطبيق عند البناء. لا يعني تعريفه أن التطبيق يستطيع قراءة أي صورة في جهاز المستخدم، ولا أن ملفًا خارج المشروع سيظهر تلقائيًا على هاتف آخر. صور يختارها المستخدم وقت التشغيل وملفات التنزيل ومصادر الشبكة لها واجهات ومسارات مختلفة. المثال يستخدم assets/images/lesson.png مملوكًا للمشروع، فلا تضع مكانه مسارًا محليًا من حاسوبك ثم تتوقع أن يعمل على Android أو الويب.
إعداد pubspec بعناية
داخل قسم flutter الموجود أصلًا أضف assets بمسافة بادئة صحيحة، ثم مسار الملف أو مجلده مع الشرطة المائلة الأخيرة. لا تنشئ قسم flutter ثانيًا وتترك الأول في الملف نفسه. تعريف assets/images/ يشمل الملفات المباشرة في ذلك المجلد، وليس كل شجرة مجلدات فرعية بصورة عامة؛ عرّف المجلدات الإضافية عند الحاجة مع مراعاة آلية نسخ الدقة للصور. احفظ الملف وشغّل flutter pub get، ثم أعد التشغيل أو البناء عند تغير تعريف الحزمة بدل تكرار hot reload دون مراجعة النتيجة.
المسار وحالة الأحرف
طابق الاسم والامتداد وحالة الأحرف بالضبط؛ lesson.png ليس Lesson.PNG على كل نظام ملفات أو منصة. اجعل المسار نسبيًا إلى جذر المشروع كما عُرف في pubspec، ولا تضف شرطة بداية كأنك تقرأ من جذر نظام التشغيل. عند ظهور Unable to load asset راجع وجود الملف وتعريفه ومساره قبل حذف cache شاملًا أو إعادة تثبيت SDK. إذا كان الأصل من package فله عقد آخر يشمل اسم الحزمة، فلا تخلط ذلك بملف داخل تطبيقك.
العرض والحجم الفعلي
Image.asset يقرأ صورة من الحزمة، وBoxFit يحدد عرضها داخل القيود ولا يضغط ملف المصدر تلقائيًا. صورة ضخمة لشعار صغير قد تستهلك مساحة وذاكرة أكثر من المطلوب؛ جهز دقة مناسبة وراجع نسخ الدقة عند الحاجة. AspectRatio يعطي مساحة مستقرة للعرض، وfit.contain يظهر الصورة كاملة بينما cover قد يقص الأطراف. اختر السلوك حسب المحتوى، ولا تقص كودًا أو مخططًا تعليميًا مهمًا فقط للحصول على مستطيل متناسق.
الفشل وإمكانية الوصول
errorBuilder يعرض بديلًا مفهومًا إذا فشل التحميل، لكنه لا يصلح المسار ولا يغني عن اختبار وجود الأصل. المثال يسمح بحقن assetPath مختلف لاختبار النجاح والفشل دون تغيير تصميم الصورة. semanticLabel يصف الصورة المفيدة لقارئ الشاشة؛ الصور الزخرفية قد تحتاج استبعادًا مناسبًا بدل قراءة وصف مكرر. لا تستبدل صورة مهمة بأيقونة صامتة ثم تعتبر المهمة نجحت لأن التطبيق لم يتعطل. راجع التباين والخلفية وصحة الصورة في الثيمين والاتجاهين إن كان ذلك ضمن المنتج.
الصور والخطوط والحدود
تعريف صورة لا يسجل خطًا مخصصًا؛ الخطوط لها قسم fonts وتعريف family وأوزان مطابق لملفاتها. كذلك Image.asset لا يفسر كل صيغة متجهية مثل SVG تلقائيًا كما لو كانت PNG؛ اختر أداة مناسبة للصيغة وافهم قيودها. لا تخزن مفاتيح خدمة سرية داخل assets لأن تضمين الملف في التطبيق لا يجعله مخفيًا. اختبر نسخة release على المنصة المستهدفة مع الأصل الحقيقي، والمثال التالي يحتاج خطوة إعداد الملف وYAML صراحة قبل أن يعرض الصورة بدل البديل.
تعريف الصورة في pubspec.yaml
أضف صورة تملك حق استخدامها باسم assets/images/lesson.png، وادمج السطرين داخل قسم flutter الموجود؛ لا تكرر القسم.
flutter:
assets:
- assets/images/lesson.png
مثال Dart للتجربة بعد الإعداد
شغّل المثال داخل مشروع Flutter تجريبي. يعتمد على Material ويحتاج صورة فعلية وتعريف assets الموضح أعلاه؛ لا يعتمد أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class DemoPage extends StatelessWidget {
const DemoPage({super.key, this.assetPath = 'assets/images/lesson.png'});
final String assetPath;
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Bundled image')),
body: ListView(padding: const EdgeInsets.all(16), children: [
AspectRatio(aspectRatio: 16 / 9, child: Image.asset(
assetPath, fit: BoxFit.contain, semanticLabel: 'Lesson illustration',
errorBuilder: (_, _, _) => const Center(child: Text('Image unavailable: check the asset setup')),
)),
const SizedBox(height: 16),
const Text('This image must be included in pubspec.yaml before building.'),
]),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.






