ابنِ Todo App باستخدام Cubit وSQLite في Flutter: مستودع typed واستعلامات آمنة، وإضافة مهمة وإعادة تحميل القائمة مع حالات الانتظار والفشل.
قسّم التطبيق قبل كتابة النموذج
Todo App باستخدام Cubit وSQLite يجمع ثلاث مسؤوليات: قاعدة بيانات تحفظ السجلات، ومستودع يقدم العمليات، وCubit يحول النتائج إلى حالة تعرضها الواجهة. هذا يمنع انتشار rawQuery داخل Widgets. المثال يستخدم قاعدة تعليمية جديدة باسم geecoders_tasks.db ولا يحذف قاعدة تطبيقك القديمة أو يرحّل بياناتها تلقائيًا. أي تطبيق قائم يحتاج خطة نسخة احتياطية وترحيل توافق بنية بياناته قبل التغيير.
تهيئة SQLite بطريقة منتظرة
تفتح openTasksDatabase القاعدة وتنتظر إنشاء الجدول داخل onCreate. لا تطلق execute ثم تعود من callback قبل اكتماله، فقد تبدأ القراءة قبل جاهزية الجدول. يرتبط version بمخطط القاعدة، وليس بعدد المهام. إذا تغير المخطط لاحقًا استخدم ترحيلًا عبر onUpgrade واختبره على نسخة بيانات قديمة. إلغاء تثبيت التطبيق أو مسح بياناته قد يحذف البيانات المحلية، لذا لا تصفها بأنها نسخة احتياطية سحابية.
نموذج واضح بدل خرائط غير مقيدة
يحمل Task معرفًا وعنوانًا وحالة من TaskStatus. يحول fromMap الصف إلى نموذج مفهوم بدل نشر Map ديناميكي في جميع الشاشات. يفرض المخطط أن العنوان والحالة غير فارغين من ناحية SQL وأن الحالة ضمن القيم المعتمدة، بينما يتحقق المستودع من أن العنوان ليس مسافات فقط. قد تحتاج قيودًا إضافية لطول العنوان أو قواعد العمل، لكن مكانها يجب أن يكون واضحًا وقابلًا للاختبار.
إدخال النص دون تركيب SQL
تستخدم add دالة insert مع Map قيم بدل إدراج عنوان المستخدم داخل سلسلة SQL. بهذا يبقى النص الذي يحتوي علامات اقتباس بيانات عادية، ولا يكسر بنية الاستعلام. راجع المنطق نفسه عند البحث والتعديل والحذف، واستخدم whereArgs للقيم المتغيرة. لا تعالج المشكلة باستبدال بعض علامات الاقتباس يدويًا؛ التمرير المنفصل للمعاملات أوضح وأكثر موثوقية.
حالة تحميل وفشل تحتفظ بالقائمة
يعيد TodoCubit تحميل القائمة بعد نجاح كل عملية. حالة TodoState غير قابلة لتعديل القائمة من الخارج وتحمل loading وerror، مع الاحتفاظ بالمهام السابقة أثناء الانتظار أو الفشل. يمنع busy تنفيذ عمليتين متزامنتين في هذا المثال؛ هذا ليس صفًا مضمونًا لكل استدعاء برمجي، لذلك تتعطل أزرار الواجهة أثناء العمل. إذا احتجت استقبال عمليات متتابعة من مصادر أخرى، صمم صفًا أو سياسة تسلسل واضحة.
نموذج الإدخال ودورة حياة الموارد
يمتلك AddTaskForm متحكم النص ويغلقه في dispose. يتحقق من وجود عنوان قبل الطلب، ثم يمسح الحقل بعد نجاح العملية فقط حتى لا تضيع مدخلات المستخدم عند الفشل. توجد مراجعة ثانية داخل المستودع حتى لا يعتمد التحقق على زر واحد. ضع النموذج داخل مساحة محددة مثل body في Scaffold لأن قائمته تستخدم Expanded، وفر TodoCubit فوقه بدل محاولة البحث عنه من سياق خارجه.
من يملك قاعدة البيانات؟
يفتح جذر التطبيق أو طبقة البيانات القاعدة، ثم يحقن SqliteTaskStore في TodoCubit. يجب أن يغلق المالك القاعدة عند نهاية عمرها المناسب؛ لا تغلقها من تبويب يستخدمه غيره، ولا تفترض أن إغلاق Cubit يغلق تلقائيًا قاعدة شاركتها معه. يمكن بدء التحميل مرة واحدة عند إنشاء المزود باستخدام refresh. إذا كانت لديك أنواع حالة أخرى فراجع تنظيم المزودات.
إكمال التطبيق واختبار الأخطاء
ابدأ بإضافة عنوان عادي وآخر يحتوي اقتباسات، ثم اختبر فشل القراءة والكتابة وحالة قائمة فارغة. أضف الإكمال والأرشفة والحذف بعد التأكد من أن القراءة والإضافة تعملان، واستخدم شريط التنقل لعرض الأقسام من مصدر مشترك. لفشل طلبات الشبكة ومفهوم إعادة المحاولة راجع الدرس المخصص، ولا تنقل إعادة المحاولة التلقائية إلى كتابة قد تتكرر دون سياسة مناسبة.
الإعداد أو عقد التكامل المطلوب
طبّق الجزء المناسب على مشروعك بعد مراجعة إصدار الحزمة والمنصة؛ قيم الإعداد هنا توضيحية وليست مفاتيح صالحة أو خدمة خلفية منشورة.
flutter pub add flutter_bloc sqflite pathالملف المشترك: task_store.dart
احفظ هذا الملف مرة واحدة داخل مجلد lib، واستورده من المثال التالي. لا تجمع تعريفات الملفات في ملف واحد بتكرار الكلاسات.
import 'package:path/path.dart' as paths;
import 'package:sqflite/sqflite.dart';
enum TaskStatus { active, done, archived }
class Task {
const Task(this.id,this.title,this.status);
final int id;
final String title;
final TaskStatus status;
factory Task.fromMap(Map<String,Object?> row)=>Task(
row['id'] as int,row['title'] as String,
TaskStatus.values.byName(row['status'] as String));
}
Future<Database> openTasksDatabase({DatabaseFactory? factory,String? databasePath}) async {
final f=factory??databaseFactory;
final path=databasePath??paths.join(await f.getDatabasesPath(),'geecoders_tasks.db');
return f.openDatabase(path,options:OpenDatabaseOptions(version:1,
onCreate:(db,version)async{
await db.execute("CREATE TABLE tasks(id INTEGER PRIMARY KEY AUTOINCREMENT, "
"title TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('active','done','archived')))");
}));
}
class SqliteTaskStore {
SqliteTaskStore(this.database);
final Database database;
Future<List<Task>> all()async=>(await database.query('tasks',orderBy:'id DESC'))
.map(Task.fromMap).toList(growable:false);
Future<int> add(String title) {
final value=title.trim();
if(value.isEmpty)throw ArgumentError('Task title is required');
return database.insert('tasks',{'title':value,'status':TaskStatus.active.name});
}
Future<void> changeStatus(int id,TaskStatus status)async{
final count=await database.update('tasks',{'status':status.name},where:'id = ?',whereArgs:[id]);
if(count!=1)throw StateError('Task not found');
}
Future<void> remove(int id)async{
final count=await database.delete('tasks',where:'id = ?',whereArgs:[id]);
if(count!=1)throw StateError('Task not found');
}
}
الملف المشترك: todo_cubit.dart
احفظ هذا الملف مرة واحدة داخل مجلد lib، واستورده من المثال التالي. لا تجمع تعريفات الملفات في ملف واحد بتكرار الكلاسات.
import 'package:flutter_bloc/flutter_bloc.dart';
import 'task_store.dart';
class TodoState {
TodoState({Iterable<Task> tasks=const [],this.loading=false,this.error}):tasks=List.unmodifiable(tasks);
final List<Task> tasks;
final bool loading;
final String? error;
List<Task> matching(TaskStatus status)=>tasks.where((t)=>t.status==status).toList(growable:false);
}
class TodoCubit extends Cubit<TodoState> {
TodoCubit(this.store):super(TodoState());
final SqliteTaskStore store;
bool busy=false;
Future<void> _run(Future<void> Function() operation)async{
if(busy || isClosed)return;
busy=true;emit(TodoState(tasks:state.tasks,loading:true));
try{
await operation();final tasks=await store.all();
if(!isClosed)emit(TodoState(tasks:tasks));
}catch(_){if(!isClosed)emit(TodoState(tasks:state.tasks,error:'تعذر حفظ أو تحميل المهام'));}
finally{busy=false;}
}
Future<void> refresh()=>_run(()async{});
Future<void> add(String title)=>_run(()async{await store.add(title);});
Future<void> changeStatus(int id,TaskStatus status)=>_run(()=>store.changeStatus(id,status));
Future<void> remove(int id)=>_run(()=>store.remove(id));
}
المثال التطبيقي المراجع
احفظ المثال في ملف مستقل داخل مشروع تجريبي مع الحزم المذكورة. يوضح الكود نطاق الدرس؛ أضف إعدادات مشروعك واختبر المنصة المستهدفة قبل الاعتماد عليه في تطبيق قائم.
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'todo_cubit.dart';
class AddTaskForm extends StatefulWidget {
const AddTaskForm({super.key});
@override
State<AddTaskForm> createState()=>_AddTaskFormState();
}
class _AddTaskFormState extends State<AddTaskForm>{
final text=TextEditingController();
@override
void dispose(){text.dispose();super.dispose();}
@override
Widget build(BuildContext context)=>BlocBuilder<TodoCubit,TodoState>(builder:(context,state)=>Column(children:[
TextField(controller:text,decoration:const InputDecoration(labelText:'عنوان المهمة')),
ElevatedButton(onPressed:state.loading?null:()async{
if(text.text.trim().isEmpty)return;
final cubit=context.read<TodoCubit>();await cubit.add(text.text);
if(mounted && cubit.state.error==null)text.clear();
},child:const Text('إضافة')),
if(state.loading)const LinearProgressIndicator(),
if(state.error!=null)Text(state.error!),
Expanded(child:ListView(children:[for(final task in state.tasks)ListTile(
key:ValueKey(task.id),title:Text(task.title))])),
]));
}
مراجع التنفيذ الرسمية
مسار تعلم SQLite بعد التطبيق
ابدأ بفتح المخطط مرة واحدة، ثم نفذ الإضافة والقراءة والحذف عبر المتجر المشترك. أمثلة الدروس التفصيلية المرتبطة تستخدم جدولًا تعليميًا منفصلًا؛ لا تجمع مخططين مختلفين في القاعدة نفسها دون ترحيل. واجهة القائمة الفارغة تُعرض بعد اكتمال القراءة ولا تعني أن القاعدة لم تفتح. إذا تغيّر النموذج لاحقًا، اختبر ترقية قاعدة منشورة بدل الاعتماد على تثبيت جديد فقط.
لإكمال هذا الجزء، انتقل إلى تحديث حالة المهام بين صفحات Flutter باستخدام Cubit وSQLite، ثم طبّق الربط الذي يناسب بنية مشروعك.






