إنشاء Model Class في Dart بمعرّفات ثابتة وconstructor واضح، وتحويل JSON بفحص الأنواع وعرض البيانات في Flutter دون خرائط ديناميكية أو بيانات شخصية تجريبية.
لماذا نموذج بيانات؟
عندما تعرض قائمة دروس تحتاج عقدًا يصف كل درس: معرف وعنوان ووصف وربما حقول أخرى وفق المنتج. Model Class يجعل الأنواع والاحتياجات ظاهرة بدل نشر مفاتيح نصية في كل Widget. constructor ينشئ الكائن ويهيئ حقوله؛ لا يقوم تلقائيًا بتحميل API أو إنشاء getters وsetters مستقلة لكل قيمة. المثال يستعمل Lesson بدل Model عام، ويحذف أرقام هواتف وأسماء أشخاص لا حاجة لها لشرح قائمة دروس تعليمية.
required وfinal وconst
required يطلب تمرير معامل مسمى، لكنه لا يثبت أن عنوانًا غير فارغ أو أن id فريد بين عناصر قاعدة البيانات. final يمنع إعادة إسناد الحقل بعد تهيئته، ولا يجمّد تلقائيًا أي List أو Map مخزنة داخله. const constructor يسمح باستعمال كائن ثابت عندما تكون الشروط والقيم مناسبة، ولا يعني أن كل استدعاء له يصبح ثابتًا ضمنيًا. اختَر قواعد النموذج من معنى البيانات، ثم تحقق منها في حد مناسب بدل افتراض أن أنواع Dart تغطي كل صلاحية تجارية.
JSON يحتاج فحص العقد
jsonDecode يعيد بيانات تحتاج تفسيرًا، ولذلك fromJson في المثال يفحص أن id عدد صحيح موجب وأن title نص غير فارغ وأن summary نص. يرمي FormatException واضحة عند مخالفة العقد بدل تمرير null إلى Text أو استخدام as عشوائي يؤدي إلى خطأ بعيد عن مصدر البيانات. هذه سياسة مبسطة لتجربة محلية، ويجب مواءمتها مع عقد API الحقيقي؛ بعض الخدمات ترسل معرفات نصية أو حقولًا اختيارية. لا تحول كل رقم أو قيمة null إلى String دون قرار لأن ذلك يخفي خطأ البيانات.
الهوية ليست رقم الموضع
المعرّف الثابت يميز الدرس عند الفرز والتصفية والتنقل. لا تستخدم index هوية دائمة إذا كانت القائمة تتغير، ولا تكرر id نفسه لعناصر مختلفة ثم تضع ValueKey متطابقًا عليها. فرادة المعرف عبر القائمة مسؤولية تحميل البيانات أو طبقة المجال، وليست نتيجة تلقائية لنجاح fromJson لكائن واحد. إذا كانت الصفوف تملك حالة يمكن أن تحتاج أيضًا findChildIndexCallback عند إعادة الترتيب في builder؛ مفتاح وحده ليس وصفة لحفظ كل حالة في أي بنية.
افصل النموذج عن العرض
Lesson لا يحتاج BuildContext أو لون بطاقة أو Navigator ليصف البيانات، بينما LessonTile يستقبل النموذج ويبني العرض. بذلك يمكن اختبار التحويل دون ضخ واجهة كاملة، وتغيير شكل البطاقة دون تعديل عقد API. لا تضع صورة شبكة لا علاقة لها بالشرح داخل كل نموذج لمجرد تعبئة مساحة. عند تمرير الدرس لصفحة تفاصيل استخدم constructor معلومًا أو معرّفًا قابلًا لإعادة التحميل حسب تصميم التنقل والروابط العميقة، ولا تنشئ شاشة جديدة منفصلة لكل عنصر.
اختبارات مفيدة
اختبر JSON صحيحًا وآخر بمعرف نصي وعنوان فارغ ووصف غائب وفق السياسة المعلنة، وتأكد أن الخطأ يظهر عند التحويل. اختبر قائمة بلا عناصر ومعرفات مكررة في طبقة الجمع إذا كانت من الخارج، ثم راجع النص الطويل وتكبير الخط في العرض. المثال لا ينفذ شبكة أو تخزينًا؛ fromJson لا يعني أن البيانات موثوقة أمنيًا أو أن المستخدم يملك إذن قراءتها. تحقق الخادم والصلاحيات والتحميل والفشل مسائل منفصلة يجب إضافتها عند ربط التطبيق بمصدر فعلي.
مثال مستقل للتجربة
شغّل المثال داخل مشروع Flutter تجريبي. يعتمد على Material فقط ولا يحتاج assets أو أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class Lesson {
const Lesson({required this.id, required this.title, required this.summary});
final int id;
final String title;
final String summary;
factory Lesson.fromJson(Map<String, dynamic> json) {
final id = json['id'];
final title = json['title'];
final summary = json['summary'];
if (id is! int || id <= 0 || title is! String || title.trim().isEmpty || summary is! String) {
throw const FormatException('Invalid lesson data');
}
return Lesson(id: id, title: title.trim(), summary: summary);
}
}
class DemoPage extends StatelessWidget {
const DemoPage({super.key});
static final _lessons = [
Lesson.fromJson({'id': 1, 'title': 'Dart models', 'summary': 'Separate data from presentation.'}),
Lesson.fromJson({'id': 2, 'title': 'Flutter lists', 'summary': 'Build rows from typed lesson data.'}),
];
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Typed lesson data')),
body: ListView.builder(
padding: const EdgeInsets.all(16), itemCount: _lessons.length,
itemBuilder: (_, index) => LessonTile(key: ValueKey(_lessons[index].id), lesson: _lessons[index]),
),
);
}
class LessonTile extends StatelessWidget {
const LessonTile({super.key, required this.lesson});
final Lesson lesson;
@override
Widget build(BuildContext context) => Card(child: Padding(
padding: const EdgeInsets.all(16), child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
Text(lesson.title, style: Theme.of(context).textTheme.titleLarge),
const SizedBox(height: 8), Text(lesson.summary),
]),
));
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.






