إتقان Google Flutter و Dart — بناء تطبيقات جميلة وعالية الأداء تعمل على أنظمة متعددة للجوال والويب وسطح المكتب

وصف الدورة

تأخذك هذه الدورة الشاملة القائمة على المشاريع من مبتدئ تمامًا إلى مطوّر فلاتر محترف. ستتعلم لغة Dart من الصفر، وتتقن إطار عمل فلاتر، وتصمم واجهات مستخدم متجاوبة وقابلة للتكيف، وتدير الحالة (State) باحترافية، وتدمج واجهات برمجة التطبيقات (APIs) وقواعد البيانات، وتطبّق المصادقة والأمان، وتحسّن الأداء، وتكتب الاختبارات، وتطبّق العمارة النظيفة (Clean Architecture)، وتنشر تطبيقات جاهزة للإنتاج على أندرويد و iOS والويب و Windows و macOS و Linux.

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

الفئة المستهدفة

• المبتدئون تمامًا الذين لا تتوفر لديهم خبرة سابقة (أو تتوفر خبرة محدودة) في تطوير تطبيقات الجوال
• مطورو الويب الراغبون في التوسع نحو الجوال
• الطلاب والمتحولون المهنيون الساعون للحصول على وظائف مطوّر فلاتر
• المطورون الذين يعرفون لغات أخرى ويريدون إتقان فلاتر باحترافية

المتطلبات الأساسية

• إلمام أساسي بالحاسوب
• الإلمام بأي لغة برمجة مفيد وليس شرطًا
• الاستعداد للتدرّب يوميًا وإكمال المشاريع

أهداف التعلّم

بنهاية هذه الدورة ستكون قادرًا على:

• كتابة كود Dart نظيف وحديث مع الأمان من القيم الفارغة (null safety) و async/await والتدفقات (Streams) وميزات اللغة المتقدمة
• بناء واجهات مستخدم معقدة ومتجاوبة وقابلة للتكيف باستخدام عناصر فلاتر (widgets)
• تنفيذ التنقّل الاحترافي والنماذج (forms) وإدخال المستخدم
• اختيار وتطبيق الحل المناسب لإدارة الحالة (setState، Provider، Riverpod، BLoC)
• استهلاك واجهات REST API، والتعامل مع المصادقة، وإدارة البيانات دون اتصال
• دمج خدمات Firebase
• تطبيق العمارة النظيفة ومبادئ SOLID
• كتابة اختبارات الوحدة (unit) والواجهة (widget) والتكامل (integration)
• تحسين الأداء وتشخيص المشكلات باستخدام Flutter DevTools
• نشر التطبيقات على Google Play و App Store والويب
• استخدام الأدوات الحديثة و CI/CD والتطوير بمساعدة الذكاء الاصطناعي

الوقت التقديري للتعلّم

• مكثّف بدوام كامل: 10–12 أسبوعًا
• بدوام جزئي (10–15 ساعة/أسبوع): 4–6 أشهر
• إجمالي المحتوى الموجّه + التدريب: حوالي 180–220 ساعة

بيئة التطوير الموصى بها

• Visual Studio Code أو Android Studio / IntelliJ IDEA
• Flutter SDK (القناة المستقرة)
• Dart SDK (مرفق مع فلاتر)
• محاكي أندرويد و/أو جهاز أندرويد فعلي
• Xcode (لنظام macOS فقط) لتطوير iOS

الأجهزة/البرامج المطلوبة

• حاسوب يعمل بنظام Windows 10/11، أو macOS 12+، أو Linux (يُفضّل Ubuntu 20.04+)
• ذاكرة وصول عشوائي (RAM) لا تقل عن 8 جيجابايت (يُفضّل 16 جيجابايت)
• مساحة تخزين فارغة 20+ جيجابايت
• اتصال إنترنت مستقر لتنزيل الحزم واختبار واجهات برمجة التطبيقات

الفرص الوظيفية بعد إكمال الدورة

• مطوّر تطبيقات جوال بفلاتر
• مهندس تطبيقات جوال متعددة المنصات
• مطوّر فلاتر مبتدئ إلى متوسط
• مطوّر فلاتر مستقل (فريلانسر)
• مهندس معماري لتطبيقات الجوال (مع اكتساب خبرة إضافية)
• أدوار full-stack تتضمن واجهات فلاتر الأمامية

نظرة عامة على هيكل الدورة

• المستوى 1 — مقدمة في تطوير تطبيقات الجوال وفلاتر
• المستوى 2 — تثبيت وإعداد فلاتر
• المستوى 3 — برمجة Dart من الصفر
• المستوى 4 — أول تطبيق فلاتر لك
• المستوى 5 — عناصر فلاتر (Widgets)
• المستوى 6 — واجهة المستخدم والتصميم المتجاوب
• المستوى 7 — التنقّل والتوجيه (Navigation & Routing)
• المستوى 8 — إدخال المستخدم والنماذج
• المستوى 9 — إدارة الحالة (State Management)
• المستوى 10 — العمل مع واجهات برمجة التطبيقات (APIs)
• المستوى 11 — التخزين المحلي وقواعد البيانات
• المستوى 12 — Firebase مع فلاتر
• المستوى 13 — المصادقة والأمان
• المستوى 14 — فلاتر المتقدم
• المستوى 15 — عمارة فلاتر (Architecture)
• المستوى 16 — الاختبار (Testing)
• المستوى 17 — تحسين الأداء
• المستوى 18 — الحزم والإضافات (Packages & Plugins)
• المستوى 19 — ميزات الجهاز
• المستوى 20 — فلاتر على الويب وسطح المكتب
• المستوى 21 — نشر التطبيقات
• المستوى 22 — CI/CD
• المستوى 23 — الذكاء الاصطناعي + تطوير فلاتر
• المستوى 24 — مشاريع احترافية
• المستوى 25 — أفضل ممارسات فلاتر
• المستوى 26 — الأخطاء الشائعة في فلاتر
• المستوى 27 — خارطة طريق مطوّر فلاتر
• المستوى 28 — التمارين والتقييمات
• المستوى 29 — اختبار الشهادة الاحترافية النهائي

المستوى 1 — مقدمة في تطوير تطبيقات الجوال وفلاتر

الدرس 1.1 — ما هو تطوير تطبيقات الجوال؟

أهداف التعلّم

• فهم ماهية تطوير تطبيقات الجوال
• التمييز بين الأسلوب الأصلي (Native) والأسلوب متعدد المنصات (Cross-Platform)
• التعرّف على المنصتين الرئيسيتين (أندرويد و iOS)

لماذا هذا مهم؟

يحتاج كل عمل تجاري حديث تقريبًا إلى حضور على الجوال. فهم هذا المشهد يساعدك على اختيار التقنية المناسبة ووضع توقعات واقعية.

شرح تفصيلي

تطوير تطبيقات الجوال هو عملية إنشاء برمجيات تعمل على الهواتف الذكية والأجهزة اللوحية. المنصتان الأكثر انتشارًا هما أندرويد من جوجل و iOS من آبل.

أندرويد مقابل iOS

• أندرويد مفتوح المصدر، ويعمل على مجموعة واسعة من الأجهزة، ويستخدم Java أو Kotlin كلغات أساسية.
• iOS مغلق المصدر، ويعمل فقط على أجهزة آبل، ويستخدم بشكل أساسي Swift (أو Objective-C).

الأصلي (Native) مقابل متعدد المنصات (Cross-Platform)

• التطوير الأصلي يعني كتابة قاعدتي كود منفصلتين لأندرويد و iOS. يمنح هذا عادةً أفضل أداء وأعمق تكامل مع المنصة، لكنه يضاعف تكلفة التطوير والصيانة.
• أُطر العمل متعددة المنصات تتيح لك كتابة معظم الكود مرة واحدة وتشغيله على منصات متعددة.

مكانة فلاتر

فلاتر هو مجموعة أدوات واجهة مستخدم متعددة المنصات أنشأتها جوجل. يستخدم لغة Dart ويُترجم إلى كود آلة أصلي، مما يوفر أداءً قريبًا من الأصلي مع السماح بقاعدة كود واحدة لأندرويد و iOS والويب و Windows و macOS و Linux.

متى يكون فلاتر هو الخيار الأفضل

• عندما تحتاج إلى الإطلاق على منصات متعددة بسرعة
• عندما تريد فريقًا واحدًا وقاعدة كود واحدة
• عندما تقدّر واجهات مستخدم قابلة للتخصيص بشكل كبير وجميلة
• عندما يكون الأداء مهمًا لكنك لا تحتاج إلى ميزات خاصة بمنصة معينة بعمق شديد قد تتطلب استخدامًا مكثفًا لقنوات المنصة (platform channels)

الأخطاء الشائعة

• افتراض أن فلاتر مخصص للجوال فقط (فهو يستهدف أيضًا الويب وسطح المكتب)
• اختيار فلاتر عندما يتطلب التطبيق استخدامًا مكثفًا لواجهات برمجة تطبيقات جديدة جدًا أو نادرة دون تقييم توفر الإضافات (plugins)

أفضل الممارسات

• قيّم دائمًا متطلبات المشروع المحددة قبل اختيار التقنية
• جرّب الميزات الحرجة مبكرًا

تمرين تطبيقي

اكتب فقرة قصيرة تقارن فيها مزايا التطوير الأصلي مقابل فلاتر لتطبيق تجارة إلكترونية بسيط.

مشروع مصغّر

ابحث عن ثلاثة تطبيقات حقيقية مبنية بفلاتر ودوّن المنصات التي تدعمها.

الدرس 1.2 — عمارة فلاتر والمفاهيم الأساسية

أهداف التعلّم

• فهم العمارة الطبقية لفلاتر
• تعلّم أدوار محرك فلاتر (Engine) والإطار (Framework) والمُضمِّن (Embedder)
• استيعاب مفهوم العناصر (widgets) وشجرة العناصر

شرح تفصيلي

يمتلك فلاتر عمارة طبقية:

• الإطار (Dart) — مكتبة واجهة المستخدم عالية المستوى المكتوبة بلغة Dart. هذا ما تتعامل معه يوميًا (Material، Cupertino، العناصر، الإيماءات، الرسوم المتحركة، إلخ).
• المحرك (++C) — مسؤول عن العرض منخفض المستوى (Skia أو Impeller)، وتخطيط النص، وإدخال/إخراج الملفات، وقنوات المنصة.
• المُضمِّن (Embedder) — كود خاص بالمنصة يستضيف محرك فلاتر على أندرويد و iOS و Windows، إلخ.

العناصر (Widgets)

في فلاتر، كل شيء هو عنصر (widget). العنصر هو وصف غير قابل للتغيير (immutable) لجزء من واجهة المستخدم. تشكّل العناصر شجرة. عندما تتغيّر حالة التطبيق، يعيد فلاتر بناء الأجزاء المتأثرة من شجرة العناصر بكفاءة.

إعادة التحميل السريع (Hot Reload) وإعادة التشغيل السريع (Hot Restart)

• إعادة التحميل السريع تحقن الكود المحدَّث في آلة Dart الافتراضية أثناء تشغيلها مع الحفاظ على حالة التطبيق الحالية. وهي سريعة جدًا ومثالية لتكرار تصميم الواجهة.
• إعادة التشغيل السريع تعيد تشغيل آلة Dart الافتراضية وتفقد حالة التطبيق. استخدمها عند تغيير ()main أو المتغيرات العامة.

نظام العرض (Rendering)

يرسم فلاتر كل بكسل بنفسه باستخدام محرك العرض الخاص به. لا يعتمد على عناصر واجهة نظام التشغيل الأصلية (OEM widgets). لهذا السبب تبدو واجهات فلاتر متسقة عبر المنصات، ولهذا السبب يكون التخصيص قويًا جدًا.

مزايا فلاتر

• قاعدة كود واحدة لستّ منصات
• أداء ممتاز (الترجمة المسبقة AOT)
• واجهة مستخدم معبّرة ومرنة للغاية
• دورة تطوير سريعة (إعادة التحميل السريع)
• نظام بيئي متنامٍ ودعم قوي من جوجل

القيود

• قد يكون حجم التطبيق أكبر من التطبيقات الأصلية الخالصة
• بعض الميزات الخاصة بالمنصة لا تزال تتطلب قنوات منصة أو إضافات
• دعم الويب، رغم كونه جاهزًا للإنتاج، لا يزال يحتوي على اختلافات عن الجوال

مقارنة فلاتر بتقنيات أخرى

تمرين تطبيقي

اشرح بأسلوبك الخاص لماذا تُبسّط فلسفة “كل شيء عنصر” في فلاتر عملية بناء واجهة المستخدم.

المستوى 2 — تثبيت وإعداد فلاتر

الدرس 2.1 — تثبيت فلاتر على Windows و macOS و Linux

أهداف التعلّم

• تثبيت حزمة تطوير فلاتر (SDK) بشكل صحيح على نظام التشغيل لديك
• إعداد متغيّر البيئة PATH
• التحقق من التثبيت باستخدام Flutter Doctor

خطوات التثبيت التفصيلية (مفاهيمية)

Windows

1. نزّل أحدث حزمة فلاتر المستقرة بصيغة zip.
2. استخرجها إلى موقع خالٍ من المسافات والرموز الخاصة (مثال: C:\src\flutter).
3. أضف مجلد flutter\bin إلى متغيّر PATH في نظامك.
4. افتح موجّه أوامر جديدًا وشغّل flutter doctor.

macOS

1. نزّل الحزمة.
2. استخرجها (عادةً إلى ~/development/flutter).
3. أضف مجلد bin إلى ملف تعريف الصدفة لديك (.zshrc أو .bash_profile).
4. شغّل flutter doctor.

Linux

1. نزّل الحزمة واستخرجها.
2. أضف مسار bin إلى ~/.bashrc أو ~/.zshrc.
3. ثبّت التبعيات المطلوبة للنظام التي يذكرها flutter doctor.

الأوامر الأساسية ومعانيها

flutter doctor

يتحقق من بيئتك ويُبلغ عن التبعيات المفقودة (سلسلة أدوات أندرويد، Xcode، إضافات VS Code، إلخ).

flutter --version

يعرض إصدارَي فلاتر و Dart المثبَّتين حاليًا.

flutter create my_app

ينشئ مشروع فلاتر جديدًا بهيكل المجلدات القياسي.

flutter run

يبني التطبيق ويشغّله على جهاز متصل أو محاكي.

إعداد Android Studio / VS Code

• ثبّت Android Studio وحزمة تطوير أندرويد (SDK).
• أنشئ جهازًا افتراضيًا واحدًا على الأقل (محاكي).
• في VS Code، ثبّت الإضافتين الرسميتين Flutter و Dart.
• على macOS، ثبّت Xcode من App Store وشغّل sudo xcode-select --switch /Applications/Xcode.app.

مشكلات التثبيت الشائعة وحلولها

• “مكوّن cmdline-tools مفقود” ← ثبّت Android SDK Command-line Tools عبر مدير SDK في Android Studio.
• “لم تُقبل تراخيص أندرويد” ← شغّل flutter doctor --android-licenses واقبل الجميع.
• PATH غير موجود ← أعد تشغيل الطرفية أو الحاسوب بعد تعديل PATH.
• مشكلات Xcode على macOS ← افتح Xcode مرة واحدة واقبل اتفاقية الترخيص.

تمرين تطبيقي

شغّل flutter doctor -v وفسّر كل سطر من المُخرَجات.

المستوى 3 — برمجة Dart من الصفر

الدرس 3.1 — المتغيرات والأنواع والأمان من القيم الفارغة (Null Safety)

أهداف التعلّم

• إعلان المتغيرات بشكل صحيح
• فهم نظام الأنواع في Dart
• استخدام الأمان من القيم الفارغة بثقة

الشرح

Dart لغة ذات كتابة (typing) قوية مع استدلال النوع (type inference). منذ إصدار Dart 2.12، يكون الأمان من القيم الفارغة مفعّلًا افتراضيًا.

الصياغة

// نوع صريح
String name = 'Flutter';

// استدلال النوع
var age = 25;
final pi = 3.14159;      // ثابت وقت التشغيل
const gravity = 9.81;    // ثابت وقت الترجمة

// أنواع قابلة لأن تكون فارغة (nullable)
String? nickname;        // يمكن أن تكون null
String nonNullable = 'Hello'; // لا يمكن أن تكون null

المُعامِلات الواعية بالقيم الفارغة (Null-aware Operators)

String? maybeName;
print(maybeName ?? 'Guest');           // إذا كانت null، استخدم 'Guest'
print(maybeName?.length);              // وصول آمن
maybeName ??= 'Anonymous';             // إسناد فقط إذا كانت null

الأخطاء الشائعة

• نسيان علامة ? عندما يمكن أن يكون المتغيّر فارغًا (null)
• استخدام ! (تأكيد عدم الفراغ) دون تحقّق، مما قد يسبب خطأً وقت التشغيل

أفضل الممارسات

• فضّل الأنواع غير القابلة للفراغ (non-nullable) كلما أمكن
• استخدم late فقط عندما تضمن التهيئة قبل أول قراءة
• فضّل final على var عندما لا تتغيّر القيمة

تمرين تطبيقي

أنشئ برنامجًا صغيرًا يعلن عن نص قابل لأن يكون فارغًا (nullable string)، ويطبع طوله بأمان، ويوفّر قيمة افتراضية.

الدرس 3.2 — التجميعات والدوال والتحكّم في التدفّق

المواضيع الأساسية المشمولة بشكل شامل

• القوائم (Lists)، المجموعات (Sets)، الخرائط (Maps)
• for، while، do-while، for-in، forEach
• if / else، تعبيرات switch (Dart 3)
• الدوال ذات المعاملات الموضعية والمسمّاة والاختيارية
• دوال السهم (Arrow functions)
• الدوال ذات الرتبة الأعلى (Higher-order functions)

مثال كامل — تصفية قائمة

void main() {
  final numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

  final evenNumbers = numbers.where((n) => n.isEven).toList();
  final doubled = numbers.map((n) => n * 2).toList();

  print(evenNumbers); // [2, 4, 6, 8, 10]
  print(doubled);     // [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
}

يتم تدريس الأصناف (Classes) والوراثة (Inheritance) والخلطات (Mixins) والأنواع العامّة (Generics) عبر أمثلة تدريجية تقود إلى نماذج واقعية (User، Product، Order، إلخ).

البرمجة غير المتزامنة (Async)

تُغطّى الـ Futures و async/await والتدفقات (Streams) ومعالجة الأخطاء باستخدام try/catch عبر أمثلة عملية شبيهة بالشبكات قبل الانتقال إلى فلاتر.

المستوى 4 — أول تطبيق فلاتر لك

الدرس 4.1 — هيكل المشروع وتطبيق “Hello Flutter”

أهداف التعلّم

• فهم هيكل مشروع فلاتر القياسي
• إنشاء وتشغيل تطبيق أساسي
• تعلّم أدوار main() و runApp() و MaterialApp و Scaffold

هيكل المشروع (المجلدات الرئيسية)

• lib/ — يوجد هنا كل كود Dart المصدري. main.dart هو نقطة الدخول.
• android/, ios/, web/, windows/, macos/, linux/ — كود خاص بكل منصة.
• pubspec.yaml — التبعيات والأصول (assets).
• test/ — اختبارات الوحدة والواجهة.

تطبيق Hello Flutter الكامل

import 'package:flutter/material.dart';

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

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Hello Flutter',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Hello Flutter'),
        centerTitle: true,
      ),
      body: const Center(
        child: Text(
          'Welcome to Flutter Development',
          style: TextStyle(fontSize: 24, fontWeight: FontWeight.w500),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {},
        child: const Icon(Icons.add),
      ),
    );
  }
}

شرح الكود

• تقوم ()runApp بتضخيم العنصر المُعطى وإرفاقه بالشاشة.
• يوفّر MaterialApp تنسيق Material Design والتنقّل والترجمة (localization).
• ينفّذ Scaffold الهيكل البصري الأساسي لتصميم Material (شريط التطبيق، المحتوى، الزر العائم، الدرج، إلخ).

التطوير التدريجي

يضيف الطلاب بعد ذلك Drawer و BottomNavigationBar و SafeArea، محوّلين التطبيق البسيط إلى قالب بداية يبدو احترافيًا.

المستوى 5 — عناصر فلاتر (Widgets)

نظرة عامة على المستوى

في المستويات السابقة تعلّمت ما هو فلاتر، وكيفية تثبيته، وكيف تعمل Dart، وكيفية إنشاء تطبيق أساسي باستخدام MaterialApp و Scaffold. الآن ستتقن اللبنات الأساسية لكل واجهة فلاتر: العناصر (widgets).

كل ما تراه على الشاشة هو عنصر. فهم العناصر بعمق — كيفية تهيئتها، وكيفية تلقّيها للقيود (constraints)، وكيفية تركيبها، وكيفية تحويل فلاتر لها إلى بكسلات — هو أساس التطوير الاحترافي بفلاتر.

أهداف التعلّم

• استخدام العناصر الأساسية بشكل صحيح وتنسيقها باحترافية
• تركيب تخطيطات معقدة باستخدام Row و Column و Stack و Expanded و Flexible وما يتصل بها
• بناء قوائم وشبكات تمرير فعّالة باستخدام ListView و GridView و Slivers
• فهم العلاقة بين أشجار Widget و Element و RenderObject
• تشخيص مشكلات التخطيط والأداء الشائعة المتعلقة بالعناصر
• إنشاء مكوّنات واجهة مستخدم قابلة لإعادة الاستخدام ومنظّمة جيدًا

المتطلبات الأساسية

• الارتياح مع أساسيات Dart (المتغيرات، الدوال، الأصناف، الأمان من القيم الفارغة)
• القدرة على إنشاء وتشغيل تطبيق فلاتر بسيط
• فهم StatelessWidget وطريقة build و MaterialApp / Scaffold

الوحدة 1 — العناصر الأساسية

الدرس 5.1 — عنصر Text

ما هو؟

Text هو العنصر الأساسي الذي يعرض سلسلة نصية على الشاشة. وهو غير قابل للتغيير (immutable) وقابل للتهيئة بدرجة كبيرة عبر خصائص التنسيق.

لماذا هو مهم؟

تقريبًا كل شاشة تحتوي على نص. إتقان Text و TextStyle أساسي لواجهات قابلة للقراءة، ويسهل الوصول إليها، ومتّسقة مع الهوية البصرية.

كيف يعمل

يستقبل عنصر Text سلسلة نصية و TextStyle اختياري. أثناء مرحلة التخطيط (layout) يقيس فلاتر النص باستخدام مقاييس الخط الحالية والقيود المُعطاة من العنصر الأب. ثم يُرسم النص على اللوحة (canvas).

الصياغة والخصائص المهمة

Text(
  String data, {
  Key? key,
  TextStyle? style,
  TextAlign? textAlign,
  TextDirection? textDirection,
  bool softWrap = true,
  TextOverflow? overflow,
  int? maxLines,
  ...
})

الخصائص الأساسية:

• style ← يتحكم في حجم الخط، الوزن، اللون، تباعد الأحرف، الارتفاع، إلخ.
• textAlign ← يسار، وسط، يمين، ضبط (justify)
• overflow ← قص، تلاشي، نقاط حذف، مرئي
• maxLines ← يحدد عدد الأسطر

مثال أساسي

Text('Hello Flutter')

مثال برمجي كامل

import 'package:flutter/material.dart';

class TextDemo extends StatelessWidget {
  const TextDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Text Widget')),
      body: Padding(
        padding: const EdgeInsets.all(24.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text(
              'Primary Heading',
              style: TextStyle(
                fontSize: 28,
                fontWeight: FontWeight.bold,
                color: Colors.black87,
              ),
            ),
            const SizedBox(height: 12),
            Text(
              'This is a longer paragraph that demonstrates soft wrapping, '
              'letter spacing, and line height control for better readability.',
              style: TextStyle(
                fontSize: 16,
                height: 1.5,
                letterSpacing: 0.3,
                color: Colors.grey[800],
              ),
            ),
            const SizedBox(height: 24),
            const Text(
              'This text will be truncated with an ellipsis if it is too long for the available space.',
              maxLines: 1,
              overflow: TextOverflow.ellipsis,
              style: TextStyle(fontSize: 16),
            ),
          ],
        ),
      ),
    );
  }
}

شرح الكود

• يستخدم Text الأول تنسيقًا كبيرًا وعريضًا لعنوان.
• يوضّح Text الثاني تنسيق الفقرات باستخدام height (ارتفاع السطر) و letterSpacing.
• يوضّح Text الثالث maxLines و overflow: TextOverflow.ellipsis — نمط شائع لعناوين القوائم.

مثال من الواقع

في بطاقة منتج للتجارة الإلكترونية، يستخدم اسم المنتج maxLines: 2 مع نقاط حذف، ويستخدم السعر لونًا مميزًا عريضًا، ويستخدم الوصف رماديًا أفتح مع ارتفاع سطر محكوم.

الأخطاء الشائعة

• نسيان const عندما لا يتغيّر النص أبدًا (يسبب إعادة بناء غير ضرورية).
• استخدام أحجام خط صغيرة جدًا دون مراعاة إمكانية الوصول.
• الاعتماد فقط على اللون لنقل المعنى (مشكلة في إمكانية الوصول).

أفضل الممارسات

• فضّل Theme.of(context).textTheme على التنسيقات المُرمَّزة يدويًا (hard-coded).
• وفّر دائمًا maxLines + overflow مناسبَين للمحتوى الديناميكي.
• استخدم const Text(...) كلما أمكن.

تمارين تطبيقية

1. أنشئ ثلاثة أنماط نصية: عنوان، نص أساسي، وتعليق توضيحي.
2. اعرض جملة طويلة تُقتطع بعد سطرين.
3. وسّط عنوانًا أفقيًا وعموديًا باستخدام خصائص Text فقط وعنصر أب.

تحدٍّ

ابنِ بطاقة “اقتباس اليوم” تعرض اقتباسًا بخط مائل، والمؤلف بخط عريض، وتتعامل مع الاقتباسات الطويلة بسلاسة.

مشروع مصغّر

أنشئ رأس ملف شخصي بسيط يعرض الاسم الكامل للمستخدم (كبير)، واسم المستخدم (رمادي)، ونبذة قصيرة تُقتطع بعد ثلاثة أسطر.

الدرس 5.2 — عنصر Icon

ما هو؟

يعرض Icon رمزًا رسوميًا من خط (Material Icons، Cupertino Icons، أو خطوط أيقونات مخصصة).

لماذا هو مهم؟

تنقل الأيقونات الإجراءات والحالة أسرع من النص وهي ضرورية لواجهات الجوال الحديثة.

كيف يعمل

تُعرَض الأيقونات من ملف خط. يربط فلاتر IconData (نقطة الترميز) بحرف رسومي (glyph) ويرسمه بالحجم واللون المطلوبَين.

الصياغة

Icon(
  IconData icon, {
  Key? key,
  double? size,
  Color? color,
  String? semanticLabel,
  TextDirection? textDirection,
})

مثال برمجي كامل

Row(
  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
  children: const [
    Icon(Icons.home, size: 32, color: Colors.blue),
    Icon(Icons.favorite, size: 32, color: Colors.red),
    Icon(Icons.settings, size: 32, color: Colors.grey),
    Icon(Icons.notifications_active, size: 32, color: Colors.orange),
  ],
)

مثال من الواقع

تعتمد أشرطة التنقّل السفلية، وأزرار الإجراءات في أشرطة التطبيقات، ومؤشرات الحالة (متصل/غير متصل، البطارية، الواي فاي) بشكل كبير على عنصر Icon.

الأخطاء الشائعة

• استخدام الأيقونات دون semanticLabel (يضرّ بإمكانية الوصول).
• ترميز الألوان يدويًا بدلًا من استخدام IconTheme أو ColorScheme.

أفضل الممارسات

• وفّر دائمًا semanticLabel للأيقونات المهمة.
• فضّل أيقونات Material أو أنشئ مجموعة أيقونات مخصصة متسقة.
• اضبط حجم الأيقونات نسبةً إلى النص المحيط (عادةً 20–28 بكسل منطقي لإجراءات المحتوى).

تمارين تطبيقية

1. أنشئ صفًا من أربع أيقونات إجراء بألوان مختلفة.
2. أضف تلميحًا (tooltip) لكل أيقونة.
3. ابنِ صفّ حالة بسيط (واي فاي، بطارية، إشارة) باستخدام الأيقونات.

الدرس 5.3 — عنصر Image

ما هو؟

يعرض Image صورة من الأصول (assets)، أو الشبكة، أو الذاكرة، أو الملف.

لماذا هو مهم؟

الصور محورية في التطبيقات الحديثة — صور المنتجات، الصور الرمزية، اللافتات، الرسوم التوضيحية.

كيف يعمل

يحمّل فلاتر بيانات الصورة، ويفكّها، ويرسمها وفقًا لقواعد BoxFit والمحاذاة. تُخزَّن صور الشبكة مؤقتًا (cache) افتراضيًا.

المُنشِئات المهمة

• Image.asset
• Image.network
• Image.file
• Image.memory

مثال برمجي كامل

ClipRRect(
  borderRadius: BorderRadius.circular(12),
  child: Image.network(
    'https://picsum.photos/400/300',
    width: double.infinity,
    height: 200,
    fit: BoxFit.cover,
    loadingBuilder: (context, child, loadingProgress) {
      if (loadingProgress == null) return child;
      return const Center(child: CircularProgressIndicator());
    },
    errorBuilder: (context, error, stackTrace) {
      return const Center(child: Icon(Icons.broken_image, size: 48));
    },
  ),
)

شرح الكود

• يقوم ClipRRect بتدوير الزوايا.
• يملأ BoxFit.cover المساحة مع الحفاظ على نسبة العرض إلى الارتفاع.
• يوفّر loadingBuilder و errorBuilder حالتَي تحميل وخطأ احترافيتين.

الأخطاء الشائعة

• عدم التعامل مع حالتَي التحميل والخطأ.
• استخدام صور كبيرة جدًا دون استراتيجية تصغير أو تخزين مؤقت.
• نسيان الإعلان عن الأصول في pubspec.yaml.

أفضل الممارسات

• وفّر دائمًا واجهات بناء (builders) للتحميل والخطأ لصور الشبكة.
• استخدم حزمة cached_network_image لصور الشبكة في الإنتاج.
• فضّل صيغة WebP أو أصولًا بأحجام مناسبة.

تمارين تطبيقية

1. اعرض صورة أصل محلية.
2. اعرض صورة شبكة مع مؤشر تحميل وبديل عند الخطأ.
3. أنشئ صورة رمزية دائرية باستخدام ClipOval + Image.

الدرس 5.4 — عنصر Container

ما هو؟

Container هو عنصر مساعد يجمع بين الرسم والتموضع والتحجيم. يمكنه تطبيق اللون، والزخرفة (decoration)، والحشو (padding)، والهامش (margin)، والقيود، والتحويلات.

لماذا هو مهم؟

هو أحد أكثر العناصر استخدامًا لإنشاء البطاقات والأزرار والشارات والأشكال المخصصة.

كيف يعمل

يطبّق Container أولًا الحشو، ثم القيود، ثم الزخرفة/اللون، وأخيرًا الهامش. إذا لم يُعطَ عنصرًا فرعيًا فإنه يحاول أن يكون بأكبر حجم ممكن (وفقًا للقيود).

الخصائص المهمة

• width, height
• padding, margin
• color أو decoration
• alignment
• constraints
• transform

مثال برمجي كامل — هيكل بطاقة منتج

Container(
  margin: const EdgeInsets.all(16),
  padding: const EdgeInsets.all(16),
  decoration: BoxDecoration(
    color: Colors.white,
    borderRadius: BorderRadius.circular(16),
    boxShadow: [
      BoxShadow(
        color: Colors.black.withOpacity(0.08),
        blurRadius: 12,
        offset: const Offset(0, 4),
      ),
    ],
  ),
  child: const Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      Text('Wireless Headphones', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
      SizedBox(height: 8),
      Text('\$129.99', style: TextStyle(fontSize: 16, color: Colors.green)),
    ],
  ),
)

الأخطاء الشائعة

• استخدام color و decoration معًا (يتعارضان).
• وضع هوامش كبيرة داخل قيود ضيّقة، مما يسبب تجاوز الحدود (overflow).
• الإفراط في استخدام Container عندما يكفي عنصر أبسط (SizedBox، Padding، ColoredBox).

أفضل الممارسات

• فضّل DecoratedBox أو Padding أو SizedBox أو ColoredBox عندما تحتاج ميزة واحدة فقط.
• استخدم BoxDecoration للحدود والتدرجات والظلال.
• حافظ على منطق الزخرفة متسقًا عبر التطبيق (أنشئ أنماط بطاقات قابلة لإعادة الاستخدام).

الدرس 5.5 — SizedBox و Padding و Center

SizedBox

يفرض على العنصر الفرعي عرضًا و/أو ارتفاعًا محددًا، أو ينشئ مساحة فارغة.

const SizedBox(height: 16)
const SizedBox(width: 8)
SizedBox(width: 120, height: 40, child: ElevatedButton(...))

Padding

يضيف مساحة فارغة حول عنصر فرعي.

Padding(
  padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
  child: Text('Content'),
)

Center

يوسّط عنصره الفرعي داخل نفسه (أفقيًا وعموديًا).

const Center(child: Text('Centered'))

متى تستخدم أيًّا منها

• استخدم SizedBox للفراغات الثابتة أو العناصر ذات الحجم الثابت.
• استخدم Padding عندما تحتاج فقط إلى تباعد حول عنصر.
• استخدم Center عندما يكون الهدف الأساسي هو التوسيط.

خطأ شائع

تداخل عدة عناصر Padding بدلًا من دمج القيم في EdgeInsets واحد.

الدرس 5.6 — Card و Divider و Placeholder

Card

حاوية بتصميم Material مع ارتفاع (elevation) وزوايا مدوّرة. فضّل Card على Container العادي مع ظل عندما تريد تنسيق Material القياسي.

Card(
  elevation: 2,
  shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
  child: const Padding(
    padding: EdgeInsets.all(16),
    child: Text('Card content'),
  ),
)

Divider

يرسم خطًا رفيعًا أفقيًا (أو عموديًا).

const Divider(height: 32, thickness: 1)
const VerticalDivider(width: 24, thickness: 1)

Placeholder

صندوق بسيط مفيد أثناء تطوير الواجهة قبل جاهزية المحتوى الحقيقي.

const Placeholder(fallbackHeight: 120)

الوحدة 2 — عناصر التخطيط (Layout Widgets)

الدرس 5.7 — Row و Column

ما هما؟

يرتّب Row العناصر الفرعية أفقيًا. يرتّب Column العناصر الفرعية عموديًا. هما العمود الفقري لمعظم تخطيطات فلاتر.

كيف تعمل القيود

يستقبل Row أو Column القيود من العنصر الأب ويمرّر قيودًا صارمة أو مرنة إلى عناصره الفرعية حسب mainAxisSize ووجود Expanded/Flexible.

الخصائص المهمة

• mainAxisAlignment
• crossAxisAlignment
• mainAxisSize
• children

مثال كامل — رأس ملف شخصي

Row(
  children: [
    const CircleAvatar(radius: 32, child: Icon(Icons.person)),
    const SizedBox(width: 16),
    Expanded(
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: const [
          Text('Sarah Johnson', style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold)),
          Text('@sarah_j', style: TextStyle(color: Colors.grey)),
        ],
      ),
    ),
    IconButton(icon: const Icon(Icons.more_vert), onPressed: () {}),
  ],
)

الأخطاء الشائعة

• نسيان Expanded أو Flexible عندما يحتاج عنصر فرعي إلى أخذ المساحة المتبقية ← أخطاء تجاوز الحدود.
• تداخل عدد كبير جدًا من Row/Column دون فهم انتشار القيود.

أفضل الممارسات

• فضّل Expanded عندما يجب أن يملأ العنصر الفرعي كل المساحة المتبقية.
• فضّل Flexible عندما يمكن أن يكون العنصر الفرعي أصغر من المساحة المتبقية.
• حافظ على شجرة العناصر ضحلة (shallow) قدر الإمكان.

الدرس 5.8 — Expanded و Flexible

يفرض Expanded على عنصر فرعي في Row/Column/Flex ملء المساحة المتبقية على المحور الرئيسي. يسمح Flexible للعنصر الفرعي بملء المساحة المتبقية لكن لا يفرض ذلك.

Row(
  children: [
    Container(width: 60, height: 60, color: Colors.red),
    Expanded(child: Container(height: 60, color: Colors.blue)),
    Flexible(child: Container(width: 80, height: 60, color: Colors.green)),
  ],
)

قاعدة عامة

• استخدم Expanded لمناطق المحتوى المرن (القوائم، النصوص التي يجب أن تنمو).
• استخدم Flexible عندما تريد أن يحافظ العنصر الفرعي على حجمه الجوهري إن أمكن.

الدرس 5.9 — Stack و Positioned

يضع Stack العناصر الفرعية فوق بعضها البعض. يعطي Positioned (صالح فقط داخل Stack) قيمًا صريحة top/right/bottom/left.

مثال كامل — صورة مع تراكب نصّي

Stack(
  children: [
    Image.network('https://picsum.photos/400/250', fit: BoxFit.cover, width: double.infinity, height: 250),
    Positioned(
      bottom: 16,
      left: 16,
      right: 16,
      child: Text(
        'Beautiful Landscape',
        style: TextStyle(color: Colors.white, fontSize: 20, fontWeight: FontWeight.bold, shadows: [
          Shadow(blurRadius: 8, color: Colors.black54),
        ]),
      ),
    ),
    Positioned(
      top: 12,
      right: 12,
      child: IconButton(
        icon: const Icon(Icons.favorite_border, color: Colors.white),
        onPressed: () {},
      ),
    ),
  ],
)

الأخطاء الشائعة

• استخدام Positioned خارج Stack.
• نسيان أن العناصر غير المُموضَعة (non-positioned) تُحاذى وفقًا لـ alignment (الافتراضي أعلى-بداية).

الدرس 5.10 — Wrap و Align و AspectRatio و FittedBox و ConstrainedBox

• Wrap — يشبه Row لكنه ينتقل إلى سطر جديد عند نفاد المساحة (الوسوم، عوامل التصفية).
• Align — يموضع عنصرًا فرعيًا داخل نفسه باستخدام قيمة Alignment.
• AspectRatio — يفرض على عنصر فرعي الحفاظ على نسبة عرض إلى ارتفاع.
• FittedBox — يُحجّم ويموضع عنصره الفرعي داخل نفسه.
• ConstrainedBox — يفرض قيودًا إضافية على عنصره الفرعي.

تحلّ هذه العناصر مشكلات تخطيط محددة جدًا وهي ضرورية لواجهات مستخدم مصقولة.

الوحدة 3 — عناصر التمرير (Scrolling Widgets)

الدرس 5.11 — ListView و ListView.builder

ListView هو الطريقة الأكثر شيوعًا لعرض قائمة قابلة للتمرير من العناصر الفرعية. للقوائم الطويلة أو غير المحدودة، فضّل دائمًا مُنشئ builder:

ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    return ListTile(
      leading: CircleAvatar(child: Text('${index + 1}')),
      title: Text(items[index].title),
      subtitle: Text(items[index].subtitle),
      onTap: () {},
    );
  },
)

لماذا builder؟

يبني بكسل فقط العناصر المرئية (بالإضافة إلى هامش صغير)، وهو أمر بالغ الأهمية للأداء مع مئات أو آلاف العناصر.

يضيف ListView.separated فاصلًا بين العناصر — مثالي للفواصل (dividers).

الدرس 5.12 — GridView

GridView.builder(
  gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
    mainAxisSpacing: 12,
    crossAxisSpacing: 12,
    childAspectRatio: 0.75,
  ),
  itemCount: products.length,
  itemBuilder: (context, index) {
    return ProductCard(product: products[index]);
  },
)

خطأ شائع

استخدام GridView عادي مع قائمة كبيرة من العناصر الفرعية بدلًا من GridView.builder.

الدرس 5.13 — SingleChildScrollView والتمرير المتداخل

استخدم SingleChildScrollView عندما يكون لديك عنصر فرعي واحد قد يتجاوز الحدود (النماذج، الأعمدة الطويلة). تجنّب تداخل عناصر قابلة للتمرير تتمرّر في نفس الاتجاه دون معالجة خاصة (NestedScrollView أو استخدام دقيق لـ PrimaryScrollController).

الدرس 5.14 — CustomScrollView و Slivers

الـ Slivers هي البروتوكول منخفض المستوى للمناطق القابلة للتمرير. يتيح لك CustomScrollView تركيب عدة slivers:

• SliverAppBar (رأس قابل للطي)
• SliverList
• SliverGrid
• SliverToBoxAdapter
• SliverFillRemaining

مثال — رأس قابل للطي + قائمة

CustomScrollView(
  slivers: [
    SliverAppBar(
      expandedHeight: 200,
      pinned: true,
      flexibleSpace: FlexibleSpaceBar(
        title: const Text('My App'),
        background: Image.network('...', fit: BoxFit.cover),
      ),
    ),
    SliverList(
      delegate: SliverChildBuilderDelegate(
        (context, index) => ListTile(title: Text('Item $index')),
        childCount: 50,
      ),
    ),
  ],
)

يُستخدَم هذا النمط في العديد من التطبيقات الاحترافية (شاشات الملفات الشخصية، تفاصيل المنتجات، قارئات الأخبار).

الوحدة 4 — عمارة العرض في فلاتر (Rendering Architecture)

Widget ← Element ← RenderObject

شجرة Widget — كائنات تهيئة غير قابلة للتغيير. تنشئها في طريقة build. تصف كيف يجب أن تبدو الواجهة.

شجرة Element — كائنات قابلة للتغيير تحتفظ بتهيئة العنصر الحالية وتدير دورة حياته. تقرّر العناصر ما إذا كان يمكن تحديث عنصر موجود بعنصر جديد أو يجب استبداله.

شجرة RenderObject — الكائنات التي تنفّذ التخطيط والرسم. كل RenderObject يعرف حجمه وموضعه وكيفية رسم نفسه.

المراحل

1. البناء (Build) — يتم إنشاء العناصر أو تحديثها.
2. التخطيط (Layout) — القيود تتدفق للأسفل، الأحجام تتدفق للأعلى.
3. الرسم (Paint) — ترسم RenderObjects في طبقات.
4. التركيب (Compositing) — تُدمَج الطبقات وتُرسَل إلى وحدة معالجة الرسومات (GPU).

فهم هذا الأنبوب (pipeline) يساعدك على تشخيص سبب عدم ظهور عنصر، أو سبب خطأ التخطيط، أو سبب ضعف الأداء.

نصيحة عملية

عندما تستدعي setState، يضع فلاتر علامة على State المعني بأنه “قذر” (dirty). فقط الأشجار الفرعية “القذرة” تُعاد بناؤها. لهذا السبب يهم الحفاظ على الحالة منخفضة قدر الإمكان واستخدام عناصر const.

مشروع تطبيقي للمستوى 5 — شاشة عرض المنتجات

ابنِ شاشة عرض منتجات كاملة تتضمن:

• شريط تطبيق مخصص
• قائمة فئات أفقية (ListView بتمرير أفقي)
• شبكة منتجات متجاوبة (GridView.builder)
• كل بطاقة منتج تستخدم Container/Card و Image و Text و Icon وحشوًا مناسبًا
• محاكاة السحب للتحديث (pull-to-refresh)
• حالتَي فراغ وتحميل

يجمع هذا المشروع كل ما تم تدريسه في المستوى 5.

أسئلة مراجعة المستوى 5

1. ما الفرق بين Expanded و Flexible؟
2. لماذا يجب أن تفضّل ListView.builder على ListView للقوائم الطويلة؟
3. ماذا يحدث إذا وضعت عنصر Positioned خارج Stack؟
4. اشرح العلاقة بين Widget و Element و RenderObject في فقرة واحدة.
5. متى تختار CustomScrollView على ListView بسيط؟

المستوى 6 — واجهة المستخدم والتصميم المتجاوب

نظرة عامة على المستوى

في المستوى 5 تعلّمت العناصر الفردية التي تشكّل اللبنات الأساسية لكل شاشة. في هذا المستوى ستتعلم كيفية تنسيق تلك العناصر بشكل متسق، وإنشاء أنظمة بصرية احترافية، وجعل الواجهات تتكيّف بسلاسة مع أحجام الشاشات المختلفة، والاتجاهات، والمنصات.

أهداف التعلّم

• إنشاء وتطبيق سمة (theme) كاملة بنظام Material 3 (فاتحة وداكنة)
• استخدام ColorScheme و TextTheme وسمات المكوّنات بشكل صحيح
• بناء أزرار وبطاقات ومربّعات حوار وأوراق سفلية (bottom sheets) وأشرطة إشعار (snack bars) متسقة
• التحكّم في التباعد والأشكال والارتفاع (elevation) بشكل منهجي
• جعل التخطيطات تستجيب لحجم الشاشة والاتجاه والمنصة
• استخدام MediaQuery و LayoutBuilder و OrientationBuilder بفعالية
• تصميم واجهات تعمل بشكل جيد على الهواتف والأجهزة اللوحية والأجهزة القابلة للطي وسطح المكتب والويب

الوحدة 1 — Material Design و Material 3

الدرس 6.1 — ما هو Material Design و Material 3؟

ما هو؟

Material Design هو نظام التصميم الخاص بجوجل. Material 3 (يُعرَف أيضًا بـ Material You) هو أحدث إصدار. يركّز على اللون الديناميكي، والأشكال الأكبر، وتحسين إمكانية الوصول، والتخصيص الشخصي.

كيف يعمل في فلاتر

ينفّذ فلاتر Material 3 عبر ThemeData و ColorScheme. عند ضبط useMaterial3: true، تتبنى العديد من العناصر تلقائيًا اللغة البصرية الجديدة.

إعداد سمة أساسي

MaterialApp(
  theme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(
      seedColor: const Color(0xFF6750A4),
      brightness: Brightness.light,
    ),
  ),
  darkTheme: ThemeData(
    useMaterial3: true,
    colorScheme: ColorScheme.fromSeed(
      seedColor: const Color(0xFF6750A4),
      brightness: Brightness.dark,
    ),
  ),
  themeMode: ThemeMode.system,
  home: const HomePage(),
)

شرح الكود

• يولّد ColorScheme.fromSeed لوحة ألوان متناسقة كاملة من لون بذرة واحد.
• يحدد theme و darkTheme الوضعين.
• يتبع themeMode: ThemeMode.system إعداد الجهاز.

الأخطاء الشائعة

• ضبط useMaterial3: true مع الاستمرار في استخدام خصائص ألوان Material 2 القديمة.
• ترميز الألوان يدويًا بدلًا من القراءة من Theme.of(context).colorScheme.

أفضل الممارسات

• ولّد دائمًا ColorScheme من بذرة (seed).
• فضّل الألوان الدلالية (primary، onPrimary، surface، onSurface، error، إلخ) على القيم اللونية الخام.
• حافظ على تزامن السمتين الفاتحة والداكنة باستخدام نفس البذرة.

تمرين تطبيقي

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

الدرس 6.2 — ColorScheme بعمق

الخصائص الأساسية التي ستستخدمها يوميًا

• primary / onPrimary
• secondary / onSecondary
• surface / onSurface
• background / onBackground (استُبدلت الآن إلى حد كبير بـ surface)
• error / onError
• outline، shadow، scrim، إلخ.

كيفية الوصول إلى الألوان

final colorScheme = Theme.of(context).colorScheme;

Container(
  color: colorScheme.primaryContainer,
  child: Text(
    'Hello',
    style: TextStyle(color: colorScheme.onPrimaryContainer),
  ),
)

أفضل ممارسة

لا تُرمِّز أبدًا Colors.blue أو Color(0xFF...) يدويًا في العناصر عندما يوجد لون دلالي متاح. اسحب دائمًا من ColorScheme.

الدرس 6.3 — الطباعة و TextTheme

أدوار النص في Material 3

displayLarge ← displaySmall، headlineLarge ← headlineSmall، titleLarge ← titleSmall، bodyLarge ← bodySmall، labelLarge ← labelSmall

مثال كامل

Text(
  'Welcome back',
  style: Theme.of(context).textTheme.headlineMedium?.copyWith(
    fontWeight: FontWeight.bold,
  ),
)

Text(
  'Here is your dashboard summary for today.',
  style: Theme.of(context).textTheme.bodyLarge?.copyWith(
    color: Theme.of(context).colorScheme.onSurfaceVariant,
  ),
)

الخطوط المخصصة

1. أضف ملفات الخط إلى مجلد assets/fonts.
2. أعلن عنها في pubspec.yaml.
3. طبّقها في ThemeData:

theme: ThemeData(
  useMaterial3: true,
  fontFamily: 'Inter',
  textTheme: const TextTheme(
    headlineMedium: TextStyle(fontFamily: 'Inter', fontWeight: FontWeight.w600),
    bodyLarge: TextStyle(fontFamily: 'Inter'),
  ),
)

خطأ شائع

الإفراط في تجاوز (override) العديد من أنماط النص بتنسيقات مؤقتة بدلًا من توسيع السمة.

أفضل ممارسة

أنشئ مجموعة صغيرة من أنماط النص الدلالية وأعد استخدامها. استخدم copyWith فقط للتعديلات الطفيفة.

الوحدة 2 — مكوّنات واجهة المستخدم الشائعة

الدرس 6.4 — الأزرار

يوفّر فلاتر عدة أنواع أزرار من Material 3: ElevatedButton، FilledButton، FilledButton.tonal، OutlinedButton، TextButton، IconButton، FloatingActionButton.

مثال زر احترافي

FilledButton.icon(
  onPressed: () {},
  icon: const Icon(Icons.add),
  label: const Text('Create New'),
  style: FilledButton.styleFrom(
    padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 16),
    shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
  ),
)

أفضل الممارسات

• فضّل FilledButton للإجراء الأساسي في الشاشة.
• استخدم OutlinedButton أو TextButton للإجراءات الثانوية.
• حافظ على ارتفاع زر متسق (عادةً 40–48 بكسل منطقي).
• وفّر دائمًا onPressed بقيمة null عندما يجب أن يظهر الزر معطّلًا.

الدرس 6.5 — البطاقات، مربّعات الحوار، الأوراق السفلية، وأشرطة الإشعار

Card

Card(
  elevation: 0,
  color: Theme.of(context).colorScheme.surfaceContainerHighest,
  shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)),
  child: Padding(
    padding: const EdgeInsets.all(20),
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text('Revenue', style: Theme.of(context).textTheme.titleMedium),
        const SizedBox(height: 8),
        Text('\$24,500', style: Theme.of(context).textTheme.headlineSmall),
      ],
    ),
  ),
)

Dialog

showDialog(
  context: context,
  builder: (context) => AlertDialog(
    title: const Text('Confirm Delete'),
    content: const Text('This action cannot be undone.'),
    actions: [
      TextButton(onPressed: () => Navigator.pop(context), child: const Text('Cancel')),
      FilledButton(onPressed: () => Navigator.pop(context, true), child: const Text('Delete')),
    ],
  ),
);

Bottom Sheet

showModalBottomSheet(
  context: context,
  showDragHandle: true,
  builder: (context) => Padding(
    padding: const EdgeInsets.all(24),
    child: Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        Text('Options', style: Theme.of(context).textTheme.titleLarge),
        const SizedBox(height: 16),
        ListTile(leading: const Icon(Icons.share), title: const Text('Share'), onTap: () {}),
        ListTile(leading: const Icon(Icons.link), title: const Text('Copy Link'), onTap: () {}),
      ],
    ),
  ),
);

SnackBar

ScaffoldMessenger.of(context).showSnackBar(
  SnackBar(
    content: const Text('Item saved successfully'),
    behavior: SnackBarBehavior.floating,
    action: SnackBarAction(label: 'Undo', onPressed: () {}),
  ),
);

الأخطاء الشائعة

• استخدام ScaffoldMessenger الجذر بشكل غير صحيح عند وجود Scaffold متداخلة.
• جعل الأوراق السفلية طويلة جدًا دون جعلها قابلة للتمرير.

الدرس 6.6 — التباعد والأشكال والارتفاع

نظام التباعد — تستخدم التطبيقات الاحترافية مقياس تباعد متسقًا (عادةً مضاعفات 4 أو 8): 4، 8، 12، 16، 24، 32، 48، 64.

class AppSpacing {
  static const double xs = 4;
  static const double sm = 8;
  static const double md = 16;
  static const double lg = 24;
  static const double xl = 32;
}

الأشكال — يشجّع Material 3 على نصف أقطار زوايا أكبر (12–28).

class AppShapes {
  static final small = RoundedRectangleBorder(borderRadius: BorderRadius.circular(8));
  static final medium = RoundedRectangleBorder(borderRadius: BorderRadius.circular(12));
  static final large = RoundedRectangleBorder(borderRadius: BorderRadius.circular(16));
}

الوحدة 3 — التصميم المتجاوب والقابل للتكيف

الدرس 6.7 — MediaQuery

يعطيك MediaQuery معلومات عن الشاشة الحالية: الحجم، الاتجاه، الحشو (النتوءات، واجهة النظام)، عامل تحجيم النص، السطوع، إلخ.

final size = MediaQuery.sizeOf(context);
final padding = MediaQuery.paddingOf(context);
final orientation = MediaQuery.orientationOf(context);
final textScaler = MediaQuery.textScalerOf(context);

مثال — تجنّب النتوء (notch)

Padding(
  padding: EdgeInsets.only(top: MediaQuery.paddingOf(context).top),
  child: ...,
)

أو ببساطة لفّ المحتوى بـ SafeArea.

الدرس 6.8 — LayoutBuilder ونقاط التكسّر (Breakpoints)

يعطيك LayoutBuilder قيود العنصر الأب، وهو أكثر موثوقية من MediaQuery عندما لا يكون العنصر بملء الشاشة.

class Breakpoints {
  static const double mobile = 600;
  static const double tablet = 900;
  static const double desktop = 1200;
}

Widget build(BuildContext context) {
  return LayoutBuilder(
    builder: (context, constraints) {
      if (constraints.maxWidth < Breakpoints.mobile) {
        return const MobileLayout();
      } else if (constraints.maxWidth < Breakpoints.tablet) {
        return const TabletLayout();
      } else {
        return const DesktopLayout();
      }
    },
  );
}

نمط من الواقع

• الجوال: تنقّل سفلي + عمود واحد
• الجهاز اللوحي: شريط تنقّل جانبي (NavigationRail) + عمودان
• سطح المكتب: شريط تنقّل جانبي أو درج جانبي + محتوى متعدد الأعمدة

الدرس 6.9 — OrientationBuilder

OrientationBuilder(
  builder: (context, orientation) {
    if (orientation == Orientation.portrait) {
      return const PortraitLayout();
    } else {
      return const LandscapeLayout();
    }
  },
)

الدرس 6.10 — التنقّل القابل للتكيف والشبكات المتجاوبة

أنماط التنقّل

• الهاتف ← NavigationBar (سفلي)
• الجهاز اللوحي / سطح المكتب ← NavigationRail أو NavigationDrawer

مثال شبكة متجاوبة

GridView.builder(
  gridDelegate: SliverGridDelegateWithMaxCrossAxisExtent(
    maxCrossAxisExtent: 300,
    mainAxisSpacing: 16,
    crossAxisSpacing: 16,
    childAspectRatio: 0.75,
  ),
  itemBuilder: ...,
)

مشروع مصغّر للمستوى 6 — لوحة تحكّم متجاوبة

ابنِ لوحة تحكّم كاملة تتضمن:

• سمة Material 3 كاملة (فاتحة + داكنة) بلون بذرة للعلامة التجارية.
• شريط تطبيق مع مفتاح تبديل السمة.
• محتوى متجاوب (الجوال: قائمة عمودية + تنقّل سفلي؛ الجهاز اللوحي/سطح المكتب: NavigationRail + شبكة بطاقات متعددة الأعمدة).
• أربع بطاقات ملخّص على الأقل باستخدام تباعد ونمط طباعة وألوان ColorScheme متسقة.
• زر عائم يعرض ورقة سفلية منبثقة بإجراءات سريعة.
• تأكيد SnackBar عند تنفيذ إجراء.
• معالجة آمنة للنتوءات وواجهة النظام باستخدام SafeArea.

أسئلة مراجعة المستوى 6

1. لماذا يجب أن تفضّل ColorScheme.fromSeed على تحديد كل لون يدويًا؟
2. ما الفرق بين MediaQuery.sizeOf(context) والقيود المُعطاة من LayoutBuilder؟
3. متى تختار NavigationRail بدلًا من NavigationBar؟
4. اشرح لماذا يجعل ترميز الألوان والأنماط النصية يدويًا الوضع الداكن صعبًا.
5. ما الطريقة الموصى بها للتعامل مع شريط الحالة ومنطقة النتوء؟

المستوى 7 — التنقّل والتوجيه (Navigation & Routing)

نظرة عامة على المستوى

تحتوي التطبيقات الحقيقية على شاشات كثيرة. يعلّمك هذا المستوى كيفية تعامل فلاتر مع التنقّل — من واجهة Navigator التوجيهية الكلاسيكية إلى التوجيه التعريفي الحديث.

أهداف التعلّم

• التنقّل بين الشاشات باستخدام Navigator
• تحديد واستخدام المسارات المسمّاة (named routes)
• تمرير معطيات إلى شاشة واستقبال نتائج منها
• تنفيذ التنقّل المتداخل
• بناء تنقّل سفلي مع الحفاظ على الحالة باستخدام IndexedStack
• حماية المسارات التي تتطلب تسجيل دخول المستخدم
• فهم الفرق بين التوجيه التوجيهي (imperative) والتعريفي (declarative)
• بناء تطبيق متعدد الشاشات كامل بتدفّق تنقّل نظيف

الوحدة 1 — مفاهيم التنقّل الأساسية

الدرس 7.1 — Navigator والتنقّل الأساسي

ما هو؟

Navigator هو عنصر فلاتر الذي يدير مكدسًا (stack) من المسارات (الشاشات). عندما تدفع (push) مسارًا جديدًا، يُضاف فوق المكدس. عندما تسحب (pop)، يُزال المسار العلوي وتظهر الشاشة السابقة مجددًا.

الصياغة الأساسية

// دفع شاشة جديدة
Navigator.of(context).push(
  MaterialPageRoute(
    builder: (context) => const SecondScreen(),
  ),
);

// سحب الشاشة الحالية
Navigator.of(context).pop();

مثال كامل — شاشتان

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Center(
        child: FilledButton(
          onPressed: () {
            Navigator.of(context).push(
              MaterialPageRoute(
                builder: (context) => const DetailsScreen(),
              ),
            );
          },
          child: const Text('Go to Details'),
        ),
      ),
    );
  }
}

class DetailsScreen extends StatelessWidget {
  const DetailsScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Details')),
      body: Center(
        child: FilledButton(
          onPressed: () => Navigator.of(context).pop(),
          child: const Text('Go Back'),
        ),
      ),
    );
  }
}

شرح الكود

• ينشئ MaterialPageRoute انتقالًا متكيّفًا مع المنصة (انزلاق على iOS، تلاشي/انزلاق على أندرويد).
• تعيد دالة builder العنصر الذي يجب عرضه لهذا المسار.
• تزيل ()pop المسار الحالي وتعود إلى السابق.

الأخطاء الشائعة

• استدعاء Navigator.pop(context) عندما لا يوجد شيء لسحبه (قد يسبب خطأً).
• استخدام BuildContext بعد فجوة غير متزامنة (async gap) دون التحقق من mounted.

أفضل الممارسات

• فضّل Navigator.of(context).push على الصيغة الأقصر Navigator.push(context, ...) من أجل الوضوح.
• تحقّق دائمًا من if (context.mounted) قبل استخدام السياق بعد await.

الدرس 7.2 — تمرير المعطيات إلى شاشة

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (context) => ProductDetailsScreen(productId: 42),
  ),
);

class ProductDetailsScreen extends StatelessWidget {
  const ProductDetailsScreen({super.key, required this.productId});

  final int productId;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Product $productId')),
      body: Center(child: Text('Showing product #$productId')),
    );
  }
}

الدرس 7.3 — إرجاع بيانات من شاشة

// من الشاشة الأولى
final result = await Navigator.of(context).push<String>(
  MaterialPageRoute(builder: (context) => const SelectionScreen()),
);

if (result != null && context.mounted) {
  print('User selected: $result');
}

// داخل SelectionScreen
Navigator.of(context).pop('Selected Value');

خطأ شائع

نسيان تحديد النوع العام (push<String>) ثم مواجهة صعوبة مع الأنواع الديناميكية (dynamic).

الوحدة 2 — المسارات المسمّاة (Named Routes)

الدرس 7.4 — المسارات المسمّاة

MaterialApp(
  initialRoute: '/',
  routes: {
    '/': (context) => const HomeScreen(),
    '/details': (context) => const DetailsScreen(),
    '/profile': (context) => const ProfileScreen(),
    '/settings': (context) => const SettingsScreen(),
  },
)

Navigator.of(context).pushNamed('/details');
Navigator.of(context).pushNamed('/profile');
Navigator.of(context).pop();

تمرير المعطيات مع المسارات المسمّاة

Navigator.of(context).pushNamed(
  '/details',
  arguments: 42,
);

// داخل DetailsScreen
final productId = ModalRoute.of(context)!.settings.arguments as int;

متى تصبح المسارات المسمّاة محدودة

تعمل المسارات المسمّاة بشكل جيد للتطبيقات البسيطة. عندما تحتاج إلى معطيات مضبوطة النوع بدقة، أو حراسة المسارات (route guards)، أو الروابط العميقة (deep linking)، أو التنقّل المتداخل، ينتقل معظم الفرق الاحترافية إلى حل تعريفي مثل go_router.

الوحدة 3 — التنقّل السفلي والحفاظ على الحالة

الدرس 7.5 — BottomNavigationBar + IndexedStack

المشكلة

إذا استبدلت ببساطة محتوى Scaffold عند نقر المستخدم على عنصر تنقّل سفلي، تُفقد حالة كل تبويب (موضع التمرير، بيانات النموذج، إلخ).

الحل الاحترافي

أبقِ كل شاشات التبويبات حيّة وغيّر فقط أيها ظاهر باستخدام IndexedStack.

class MainShell extends StatefulWidget {
  const MainShell({super.key});

  @override
  State<MainShell> createState() => _MainShellState();
}

class _MainShellState extends State<MainShell> {
  int _currentIndex = 0;

  final List<Widget> _pages = const [
    HomeTab(),
    SearchTab(),
    OrdersTab(),
    ProfileTab(),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: IndexedStack(
        index: _currentIndex,
        children: _pages,
      ),
      bottomNavigationBar: NavigationBar(
        selectedIndex: _currentIndex,
        onDestinationSelected: (index) {
          setState(() => _currentIndex = index);
        },
        destinations: const [
          NavigationDestination(icon: Icon(Icons.home_outlined), selectedIcon: Icon(Icons.home), label: 'Home'),
          NavigationDestination(icon: Icon(Icons.search), label: 'Search'),
          NavigationDestination(icon: Icon(Icons.receipt_long_outlined), selectedIcon: Icon(Icons.receipt_long), label: 'Orders'),
          NavigationDestination(icon: Icon(Icons.person_outline), selectedIcon: Icon(Icons.person), label: 'Profile'),
        ],
      ),
    );
  }
}

لماذا IndexedStack؟

تبقى كل العناصر الفرعية في شجرة العناصر. فقط الرؤية تتغيّر. تُحفَظ مواضع التمرير والحالة الداخلية.

خطأ شائع

إعادة بناء قائمة الصفحات بالكامل عند كل تغيير تبويب بدلًا من إبقائها ثابتة.

الوحدة 4 — التنقّل المتداخل والمسارات المحمية

الدرس 7.6 — التنقّل المتداخل

يمكن أن يمتلك كل تبويب مكدس تنقّل خاصًا به. هذا شائع في التطبيقات حيث يمكن لتبويب الرئيسية دفع شاشات تفاصيل بينما يمتلك تبويب الملف الشخصي مكدسه الخاص. تحقّق ذلك بإعطاء كل تبويب Navigator خاصًا به (أو باستخدام موجّه تعريفي يدعم المسارات المتداخلة).

الدرس 7.7 — المسارات المحمية (حارس المصادقة)

المفهوم

يجب أن تكون بعض الشاشات متاحة فقط عندما يكون المستخدم مسجّلًا دخوله.

void openProfile(BuildContext context, bool isLoggedIn) {
  if (isLoggedIn) {
    Navigator.of(context).pushNamed('/profile');
  } else {
    Navigator.of(context).pushNamed('/login');
  }
}

نهج أفضل

مركزة القرار في طبقة التوجيه الخاصة بك بحيث لا تحتاج الأزرار الفردية إلى معرفة منطق المصادقة.

الوحدة 5 — التوجيه التعريفي الحديث (مفاهيم go_router)

لماذا التوجيه التعريفي؟

يصبح التنقّل التوجيهي (push، pop) صعب الصيانة في التطبيقات الكبيرة. يصف التوجيه التعريفي حالة التنقّل بأكملها كدالة لحالة التطبيق. تصبح الروابط العميقة، ودعم الويب، وإعادة توجيه المصادقة أنظف بكثير.

الأفكار الأساسية

• تُعرَّف المسارات في مكان واحد.
• يمكن تنفيذ إعادة التوجيه بناءً على حالة المصادقة.
• معطيات المسار (/product/:id) عناصر من الدرجة الأولى.
• يُدعَم التنقّل المتداخل بشكل طبيعي.

مشروع مصغّر للمستوى 7 — تطبيق متعدد الشاشات كامل

ابنِ تطبيقًا بالشاشات والتدفّقات التالية:

• شاشة البداية (Splash) — تظهر لثانيتين، ثم تعيد التوجيه إلى تسجيل الدخول أو الرئيسية حسب حالة المصادقة.
• شاشة تسجيل الدخول — حقول البريد الإلكتروني وكلمة المرور. عند النجاح ← الرئيسية. رابط للتسجيل.
• شاشة التسجيل — الاسم، البريد الإلكتروني، كلمة المرور. عند النجاح ← الرئيسية.
• الهيكل الرئيسي (بعد تسجيل الدخول) — تنقّل سفلي بأربعة تبويبات: الرئيسية، البحث، الطلبات، الملف الشخصي. استخدم IndexedStack للحفاظ على الحالة.
• تبويب الرئيسية — قائمة عناصر. النقر على عنصر يدفع شاشة تفاصيل (تنقّل متداخل).
• تبويب الملف الشخصي — يعرض معلومات المستخدم + زر تسجيل خروج. تسجيل الخروج يمسح الجلسة ويعود إلى تسجيل الدخول (مع مسح مكدس التنقّل).
• شاشة الإعدادات — يمكن الوصول إليها من الملف الشخصي.

المتطلبات

• استخدم مسارات مسمّاة أو هيكل Navigator نظيف.
• مرّر معطى واحدًا على الأقل بين الشاشات.
• أرجع نتيجة من شاشة واحدة.
• احمِ الهيكل الرئيسي بحيث لا يمكن فتحه دون “تسجيل دخول”.
• حافظ على حالة التبويبات باستخدام IndexedStack.
• تعامل مع زر الرجوع بشكل صحيح على أندرويد.

أسئلة مراجعة المستوى 7

1. ما الفرق بين push و pushReplacement؟
2. لماذا يُفضَّل IndexedStack على مجرد استبدال العناصر للتنقّل السفلي؟
3. كيف تُرجع بيانات بأمان من شاشة فُتحت باستخدام push؟
4. ما المشكلة التي تحلّها المسارات المحمية؟
5. متى تبدأ واجهة Navigator الكلاسيكية بالشعور بأنها محدودة؟

المستوى 8 — إدخال المستخدم والنماذج

نظرة عامة على المستوى

يعلّمك هذا المستوى كيفية بناء نماذج احترافية في فلاتر: إدخال النص المُتحكَّم فيه، والتحقق من الصحة (validation)، وإدارة التركيز (focus)، وأنواع إدخال مختلفة، واختيار التاريخ والوقت، وكيفية توفير ملاحظات واضحة أثناء إرسال النموذج.

أهداف التعلّم

• استخدام TextField و TextFormField بشكل صحيح
• إدارة النص باستخدام TextEditingController
• التحكّم في التركيز باستخدام FocusNode
• بناء نماذج بالتحقق من الصحة باستخدام Form و FormState
• إنشاء أدوات تحقق (validators) مخصصة
• استخدام القوائم المنسدلة، وخانات الاختيار، والأزرار الدائرية، والمفاتيح
• عرض منتقيات التاريخ والوقت
• التعامل مع حالتَي التحميل والخطأ أثناء إرسال النموذج

الوحدة 1 — أساسيات إدخال النص

الدرس 8.1 — TextField و TextFormField

ما هو؟

TextField هو إدخال نصي أساسي بتصميم Material. TextFormField هو نفس الإدخال لكنه مصمَّم للعمل داخل Form. يدعم التحقق من الصحة ويتكامل مع FormState.

الصياغة الأساسية

TextField(
  decoration: InputDecoration(
    labelText: 'Email',
    hintText: 'Enter your email',
    border: OutlineInputBorder(),
  ),
  keyboardType: TextInputType.emailAddress,
  textInputAction: TextInputAction.next,
)

المُفضَّل للنماذج — TextFormField

TextFormField(
  decoration: const InputDecoration(
    labelText: 'Email',
    prefixIcon: Icon(Icons.email_outlined),
    border: OutlineInputBorder(),
  ),
  keyboardType: TextInputType.emailAddress,
  textInputAction: TextInputAction.next,
  validator: (value) {
    if (value == null || value.isEmpty) {
      return 'Email is required';
    }
    if (!value.contains('@')) {
      return 'Enter a valid email';
    }
    return null;
  },
)

الأخطاء الشائعة

• استخدام TextField داخل Form ثم محاولة التحقق منه (لن يشارك في التحقق الخاص بالنموذج).
• نسيان التخلّص (dispose) من المُتحكِّمات (تسريب ذاكرة).

أفضل الممارسات

• فضّل TextFormField متى ما كان الحقل ينتمي إلى نموذج.
• وفّر دائمًا labelText أو hintText واضحين.
• استخدم keyboardType و textInputAction المناسبين.

الدرس 8.2 — TextEditingController

مثال كامل

class LoginForm extends StatefulWidget {
  const LoginForm({super.key});

  @override
  State<LoginForm> createState() => _LoginFormState();
}

class _LoginFormState extends State<LoginForm> {
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        TextFormField(
          controller: _emailController,
          decoration: const InputDecoration(labelText: 'Email'),
        ),
        const SizedBox(height: 16),
        TextFormField(
          controller: _passwordController,
          decoration: const InputDecoration(labelText: 'Password'),
          obscureText: true,
        ),
      ],
    );
  }
}

قواعد مهمة

• أنشئ المُتحكِّم في State.
• استدعِ دائمًا ()dispose على كل مُتحكِّم.
• لا تنشئ مُتحكِّمًا أبدًا داخل طريقة build.

الدرس 8.3 — FocusNode ومعالجة لوحة المفاتيح

مثال — نقل التركيز

final _emailFocus = FocusNode();
final _passwordFocus = FocusNode();

TextFormField(
  focusNode: _emailFocus,
  textInputAction: TextInputAction.next,
  onFieldSubmitted: (_) {
    _passwordFocus.requestFocus();
  },
)

إخفاء لوحة المفاتيح

GestureDetector(
  onTap: () => FocusScope.of(context).unfocus(),
  child: Scaffold(...),
)

أفضل ممارسة

تخلّص من كل FocusNode تنشئه، تمامًا مثل المُتحكِّمات.

الوحدة 2 — النماذج والتحقق من الصحة

الدرس 8.4 — Form و FormState

نمط كامل

class RegistrationForm extends StatefulWidget {
  const RegistrationForm({super.key});

  @override
  State<RegistrationForm> createState() => _RegistrationFormState();
}

class _RegistrationFormState extends State<RegistrationForm> {
  final _formKey = GlobalKey<FormState>();
  final _nameController = TextEditingController();
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();

  bool _isLoading = false;

  @override
  void dispose() {
    _nameController.dispose();
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }

  Future<void> _submit() async {
    if (!_formKey.currentState!.validate()) return;

    setState(() => _isLoading = true);

    // محاكاة طلب شبكة
    await Future.delayed(const Duration(seconds: 2));

    if (mounted) {
      setState(() => _isLoading = false);
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Registration successful')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(
        children: [
          TextFormField(
            controller: _nameController,
            decoration: const InputDecoration(labelText: 'Full Name'),
            validator: (value) =>
                value == null || value.trim().isEmpty ? 'Name is required' : null,
          ),
          const SizedBox(height: 16),
          TextFormField(
            controller: _emailController,
            decoration: const InputDecoration(labelText: 'Email'),
            keyboardType: TextInputType.emailAddress,
            validator: (value) {
              if (value == null || value.isEmpty) return 'Email is required';
              if (!value.contains('@')) return 'Enter a valid email';
              return null;
            },
          ),
          const SizedBox(height: 16),
          TextFormField(
            controller: _passwordController,
            decoration: const InputDecoration(labelText: 'Password'),
            obscureText: true,
            validator: (value) {
              if (value == null || value.length < 6) {
                return 'Password must be at least 6 characters';
              }
              return null;
            },
          ),
          const SizedBox(height: 24),
          SizedBox(
            width: double.infinity,
            child: FilledButton(
              onPressed: _isLoading ? null : _submit,
              child: _isLoading
                  ? const SizedBox(
                      height: 20,
                      width: 20,
                      child: CircularProgressIndicator(strokeWidth: 2),
                    )
                  : const Text('Create Account'),
            ),
          ),
        ],
      ),
    );
  }
}

شرح الكود

• يعطيك GlobalKey<FormState> وصولًا إلى ()validate و ()save.
• تشغّل ()validate أداة التحقق (validator) الخاصة بكل حقل.
• يُعطَّل الزر ويعرض مؤشر تحميل أثناء تنفيذ الطلب.
• يُتحقَّق من mounted بعد الفجوة غير المتزامنة.

الأخطاء الشائعة

• إنشاء GlobalKey داخل build.
• نسيان تعطيل الزر أثناء التحميل (يمكن للمستخدم الإرسال عدة مرات).
• عدم التحقق من mounted بعد await.

الدرس 8.5 — أدوات تحقق مخصصة وقابلة لإعادة الاستخدام

String? requiredValidator(String? value) {
  if (value == null || value.trim().isEmpty) return 'This field is required';
  return null;
}

String? emailValidator(String? value) {
  if (value == null || value.isEmpty) return 'Email is required';
  final emailRegex = RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$');
  if (!emailRegex.hasMatch(value)) return 'Enter a valid email address';
  return null;
}

String? passwordValidator(String? value) {
  if (value == null || value.length < 8) {
    return 'Password must be at least 8 characters';
  }
  return null;
}

الوحدة 3 — عناصر تحكم النماذج الأخرى الشائعة

الدرس 8.6 — القائمة المنسدلة، خانة الاختيار، الزر الدائري، المفتاح

DropdownButtonFormField

String? _selectedRole;

DropdownButtonFormField<String>(
  value: _selectedRole,
  decoration: const InputDecoration(labelText: 'Role'),
  items: const [
    DropdownMenuItem(value: 'user', child: Text('User')),
    DropdownMenuItem(value: 'editor', child: Text('Editor')),
    DropdownMenuItem(value: 'admin', child: Text('Admin')),
  ],
  onChanged: (value) => setState(() => _selectedRole = value),
  validator: (value) => value == null ? 'Please select a role' : null,
)

Checkbox

bool _agreeToTerms = false;

CheckboxListTile(
  title: const Text('I agree to the Terms of Service'),
  value: _agreeToTerms,
  onChanged: (value) => setState(() => _agreeToTerms = value ?? false),
  controlAffinity: ListTileControlAffinity.leading,
)

Switch

SwitchListTile(
  title: const Text('Enable notifications'),
  value: _notificationsEnabled,
  onChanged: (value) => setState(() => _notificationsEnabled = value),
)

الدرس 8.7 — منتقيات التاريخ والوقت

منتقي التاريخ

DateTime? _selectedDate;

Future<void> _pickDate() async {
  final now = DateTime.now();
  final picked = await showDatePicker(
    context: context,
    initialDate: _selectedDate ?? now,
    firstDate: DateTime(1900),
    lastDate: now,
  );
  if (picked != null) {
    setState(() => _selectedDate = picked);
  }
}