Room لـ Kotlin: دليل شامل مع أمثلة

ما هو Room ولماذا هو مطلوب؟

\n\n

Room هي مكتبة للعمل مع قواعد البيانات في تطبيقات Android المكتوبة بلغة Kotlin أو Java. توفر طبقة تجريد فوق SQLite، مما يسمح بالعمل مع قاعدة البيانات من خلال نهج كائني التوجه بدلاً من استعلامات SQL الخام.

\n\n

المزايا الرئيسية لـ Room:

\n

\n
• تقليل الكود النمطي — يقوم Room تلقائيًا بتوليد الكود للعمل مع SQLite بناءً على التعليقات التوضيحية (annotations).
\n
• التحقق من استعلامات SQL في مرحلة التجميع — يتم اكتشاف الأخطاء في الاستعلامات قبل تشغيل التطبيق.
\n
• التكامل مع Coroutines و Flow — دعم البرمجة التفاعلية والعمليات غير المتزامنة.
\n
• ترحيل قاعدة البيانات — آليات مدمجة لتحديث المخطط دون فقدان البيانات.
\n
• TypeConverters — إمكانية تخزين أنواع البيانات المعقدة (مثل Date، List) في قاعدة البيانات.
\n

\n\n

Room مثالي للتطبيقات التي تحتاج إلى تخزين محلي للبيانات المنظمة: الملاحظات، التخزين المؤقت، إعدادات المستخدم، وضع عدم الاتصال، إلخ.

\n\n

تثبيت Room

\n\n

لا يتم تثبيت Room عبر pip أو npm، لأنه مكتبة خاصة بـ Android. تتم الإضافة إلى المشروع من خلال ملف build.gradle (على مستوى الوحدة).

\n\n

الخطوة 1: أضف إضافة KSP (Kotlin Symbol Processing)

\n

في ملف build.gradle الجذر، أضف إضافة KSP:

\n

plugins {\n    id 'com.google.devtools.ksp' version '1.9.0-1.0.13' apply false\n}

\n\n

الخطوة 2: قم بتوصيل Room في وحدة التطبيق

\n

في ملف build.gradle للوحدة app، أضف:

\n

plugins {\n    id 'com.android.application'\n    id 'org.jetbrains.kotlin.android'\n    id 'com.google.devtools.ksp'\n}\n\nandroid {\n    // ... إعداداتك\n}\n\ndependencies {\n    def room_version = "2.6.1"\n\n    implementation "androidx.room:room-runtime:$room_version"\n    ksp "androidx.room:room-compiler:$room_version"\n    implementation "androidx.room:room-ktx:$room_version" // لـ Coroutines\n}

\n\n

بعد مزامنة Gradle، تصبح المكتبة جاهزة للاستخدام.

\n\n

بداية سريعة مع مثال كود

\n\n

لنقم بإنشاء تطبيق بسيط لتخزين قائمة المهام (Todo).

\n\n

الخطوة 1: تعريف الكيان (Entity)

\n

import androidx.room.Entity\nimport androidx.room.PrimaryKey\n\n@Entity(tableName = "tasks")\ndata class Task(\n    @PrimaryKey(autoGenerate = true)\n    val id: Int = 0,\n    val title: String,\n    val description: String,\n    val isCompleted: Boolean = false\n)

\n\n

الخطوة 2: إنشاء DAO (Data Access Object)

\n

import androidx.room.*\nimport kotlinx.coroutines.flow.Flow\n\n@Dao\ninterface TaskDao {\n    @Query("SELECT * FROM tasks ORDER BY id DESC")\n    fun getAllTasks(): Flow<List<Task>>\n\n    @Insert\n    suspend fun insertTask(task: Task)\n\n    @Update\n    suspend fun updateTask(task: Task)\n\n    @Delete\n    suspend fun deleteTask(task: Task)\n}

\n\n

الخطوة 3: إنشاء قاعدة البيانات

\n

import android.content.Context\nimport androidx.room.Database\nimport androidx.room.Room\nimport androidx.room.RoomDatabase\n\n@Database(entities = [Task::class], version = 1)\nabstract class AppDatabase : RoomDatabase() {\n    abstract fun taskDao(): TaskDao\n\n    companion object {\n        @Volatile\n        private var INSTANCE: AppDatabase? = null\n\n        fun getDatabase(context: Context): AppDatabase {\n            return INSTANCE ?: synchronized(this) {\n                val instance = Room.databaseBuilder(\n                    context.applicationContext,\n                    AppDatabase::class.java,\n                    "app_database"\n                ).build()\n                INSTANCE = instance\n                instance\n            }\n        }\n    }\n}

\n\n

الخطوة 4: استخدم