قراءة JSON من assets في Flutter باستخدام AssetBundle وjsonDecode، مع فحص الجذر والحقول والمعرفات وإدارة Future وحالات التحميل والفشل وإعادة المحاولة.
اعرف شكل JSON الحقيقي
الملف الذي يبدأ بكائن يحتوي lessons يختلف عن ملف جذره قائمة. لا تسمِّ الأول list لمجرد أن داخله مصفوفة، ولا تستخدم اسم friends في الكود بينما الملف يعرف بيانات أخرى. المثال يعتمد عقدًا واحدًا معلنًا: كائن جذري به lessons، وكل عنصر له id وtitle نصيان غير فارغين. إذا كانت خدمة أو ملف آخر له صيغة مختلفة فغيّر parser والعينة والاختبارات معًا بدل إضافة وصول ديناميكي إلى مفاتيح عشوائية حتى تختفي الرسالة.
تجهيز الملف والتضمين
أنشئ assets/data/lessons.json داخل المشروع وأضف مساره تحت assets في قسم flutter الموجود من pubspec.yaml. الاسم وحالة الأحرف والامتداد يجب أن تتطابق، وحفظ ملف خارج المشروع لا يجعله asset. شغّل flutter pub get وأعد البناء عند الحاجة بعد تغيير تعريف الحزمة. الملف المضمّن ليس قاعدة بيانات قابلة للتحديث من المستخدم؛ إذا احتجت كتابة أو مزامنة بيانات فلهما تخزين وتدفق مستقلان. لا تضع أسرارًا داخل asset على أساس أن الملف غير ظاهر في الواجهة.
التحليل وفحص الأنواع
jsonDecode يحلل الصيغة ويعيد قيمة تحتاج تفسيرًا. نجاح التحليل لا يثبت أن الجذر Map أو أن الحقول مناسبة لـ Text. parseLessons يفحص البنية والأنواع والفراغ وتكرار المعرف، ثم يعيد نماذج مكتوبة النوع. يرمي FormatException عند مخالفة العقد بدل TypeError بعيد داخل itemBuilder. لا تحول null تلقائيًا إلى كلمة null مع toString وتعرضها كأنها بيانات صحيحة، ولا تعتبر منطق التحقق المحلي إذن وصول لبيانات يفترض أن يحميها خادم.
Future مستقرة ونطاق AssetBundle
DefaultAssetBundle.of(context) يتيح استبدال الحزمة في الاختبار أو نطاق آخر، لذلك نحصل عليها في didChangeDependencies وننشئ Future عند تغير مثيلها. لا نستدعي loadString مباشرة في كل build، حتى لا تتكرر القراءة والتحليل بسبب إعادة بناء غير مرتبطة بالبيانات. زر Retry يستبدل المستقبل صراحة. تغيير bundle في الاختبار يطلق تحميلًا مناسبًا للنطاق الجديد، بينما مجرد تغيير الثيم لا ينبغي أن يعيد إنشاء العملية إذا لم يتغير مصدرها.
التحميل والخطأ والحجم
اعرض تقدمًا أثناء الانتظار ورسالة عامة مع إعادة محاولة عند الفشل، ولا ترسل exception الخام للمستخدم إذا كان قد يحتوي مسارات أو محتوى غير مناسب. القائمة الفارغة نجاح بلا عناصر، وليست تحميلًا مستمرًا. المثال صغير؛ ملف ضخم قد يحتاج قياس كلفة القراءة والتحليل والتخطيط وربما بنية أخرى. لا تفترض أن loadString ينقل كل jsonDecode تلقائيًا إلى isolate، ولا تقرأ الملف من جديد في كل صف. فصل parser عن الواجهة يتيح قياسه واختباره بصورة أوضح.
اختبارات العقد
اختبر الملف الصحيح وقائمة lessons الفارغة وJSON غير صالح ومفتاحًا غائبًا ونوعًا خاطئًا ومعرفًا مكررًا. استخدم AssetBundle اختبارية لنجاح التحميل وفشله ثم إعادة المحاولة دون تعديل ملفات المستخدم. راجع النص الطويل والخط الكبير والمساحة الضيقة، وتحقق من أن كل صف يعرض عنوان النموذج الصحيح. المثال لا يتصل بالشبكة ولا يكتب الملف؛ بعد نقله إلى منتج حقيقي أضف سياسة إصدار للبيانات إذا كان محتوى الحزمة يتغير بين الإصدارات، ولا تحفظ فهارس قديمة كأنها معرفات دائمة.
ملف التجربة وتعريفه
أنشئ الملف assets/data/lessons.json بالمحتوى التالي، ثم أضف مساره إلى assets داخل قسم flutter الموجود في pubspec.yaml دون تكرار القسم. شغّل flutter pub get وأعد البناء عند الحاجة.
{"lessons":[{"id":"dart","title":"Dart basics"},{"id":"flutter","title":"Flutter layout"}]}flutter:
assets:
- assets/data/lessons.json
مثال Dart بعد إعداد الملف
شغّل المثال داخل مشروع Flutter تجريبي. يحتاج ملف assets وتعريفه الموضحين أعلاه، ولا يعتمد أصنافًا من مشروع خاص. غيّر مساحة النافذة وجرّب تكبير النص أثناء الفحص، ثم انقل المكوّن إلى مشروعك بعد تحديد سياق قيوده الفعلي.
import 'dart:convert';
import 'package:flutter/services.dart';
import 'package:flutter/material.dart';
void main() => runApp(const MaterialApp(home: DemoPage()));
class Lesson {
const Lesson(this.id, this.title);
final String id;
final String title;
}
List<Lesson> parseLessons(String source) {
final root = jsonDecode(source);
if (root is! Map<String, dynamic> || root['lessons'] is! List) throw const FormatException('Expected lessons object');
final ids = <String>{};
return (root['lessons'] as List).map((item) {
if (item is! Map<String, dynamic>) throw const FormatException('Expected lesson object');
final id = item['id']; final title = item['title'];
if (id is! String || id.trim().isEmpty || title is! String || title.trim().isEmpty || !ids.add(id)) throw const FormatException('Invalid lesson fields');
return Lesson(id, title.trim());
}).toList(growable: false);
}
class DemoPage extends StatefulWidget {
const DemoPage({super.key});
@override
State<DemoPage> createState() => _DemoPageState();
}
class _DemoPageState extends State<DemoPage> {
AssetBundle? _bundle;
late Future<List<Lesson>> _future;
Future<List<Lesson>> _load() async => parseLessons(await _bundle!.loadString('assets/data/lessons.json'));
@override
void didChangeDependencies() {
super.didChangeDependencies();
final bundle = DefaultAssetBundle.of(context);
if (bundle != _bundle) { _bundle = bundle; _future = _load(); }
}
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(title: const Text('Bundled JSON')),
body: FutureBuilder<List<Lesson>>(future: _future, builder: (_, snapshot) {
if (snapshot.hasError) return Center(child: TextButton(onPressed: () => setState(() { _future = _load(); }), child: const Text('Could not load. Retry')));
if (!snapshot.hasData) return const Center(child: CircularProgressIndicator());
final data = snapshot.data!;
if (data.isEmpty) return const Center(child: Text('No lessons yet'));
return ListView.builder(itemCount: data.length, itemBuilder: (_, index) => ListTile(key: ValueKey(data[index].id), title: Text(data[index].title)));
}),
);
}مرجع الواجهة البرمجية
راجع التوثيق الرسمي لمطابقة السلوك مع إصدار Flutter المستخدم. نجاح المثال في مساحة واحدة لا يثبت توافق التصميم مع جميع الشاشات؛ اختبر حدود الانتقال والاتجاه واللغة والنص الطويل.
الصور والفيديو من الشرح السابق
الكود النصي أعلاه هو النسخة المصححة؛ قد تختلف المواد المرئية السابقة في أسماء المتغيرات أو طريقة التشغيل.






