تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
حفظ البيانات في قاعدة بيانات محلية باستخدام Room
جزء من Android Jetpack.
يمكن للتطبيقات التي تتعامل مع كميات كبيرة من البيانات المنظَّمة الاستفادة بشكل كبير من
تخزين هذه البيانات على الجهاز. وأكثر حالات الاستخدام شيوعًا هي تخزين مقتطفات البيانات ذات الصلة مؤقتًا لكي يظل بإمكان المستخدم تصفّح هذا المحتوى بلا إنترنت عندما يتعذّر على الجهاز الوصول إلى الشبكة.
توفّر مكتبة Room للحفاظ على البيانات طبقة تجريدية فوق SQLite للسماح
بالوصول إلى قاعدة البيانات بسلاسة مع الاستفادة من الإمكانات الكاملة لـ SQLite. على وجه الخصوص، يقدّم
Room المزايا التالية:
التحقّق من طلبات لغة الاستعلامات البنيوية (SQL) في وقت الترجمة
التعليقات التوضيحية الملائمة التي تقلّل من النصوص النموذجية المتكرّرة والمعرضة للأخطاء
لاستخدام Room في تطبيقك، أضِف الملحقات التالية إلى ملف
build.gradle في تطبيقك.
Kotlin
dependencies{valroom_version="2.7.2"implementation("androidx.room:room-runtime:$room_version")// If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)// See Add the KSP plugin to your projectksp("androidx.room:room-compiler:$room_version")// If this project only uses Java source, use the Java annotationProcessor// No additional plugins are necessaryannotationProcessor("androidx.room:room-compiler:$room_version")// optional - Kotlin Extensions and Coroutines support for Roomimplementation("androidx.room:room-ktx:$room_version")// optional - RxJava2 support for Roomimplementation("androidx.room:room-rxjava2:$room_version")// optional - RxJava3 support for Roomimplementation("androidx.room:room-rxjava3:$room_version")// optional - Guava support for Room, including Optional and ListenableFutureimplementation("androidx.room:room-guava:$room_version")// optional - Test helperstestImplementation("androidx.room:room-testing:$room_version")// optional - Paging 3 Integrationimplementation("androidx.room:room-paging:$room_version")}
Groovy
dependencies{defroom_version="2.7.2"implementation"androidx.room:room-runtime:$room_version"// If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)// See KSP Quickstart to add KSP to your buildksp"androidx.room:room-compiler:$room_version"// If this project only uses Java source, use the Java annotationProcessor// No additional plugins are necessaryannotationProcessor"androidx.room:room-compiler:$room_version"// optional - RxJava2 support for Roomimplementation"androidx.room:room-rxjava2:$room_version"// optional - RxJava3 support for Roomimplementation"androidx.room:room-rxjava3:$room_version"// optional - Guava support for Room, including Optional and ListenableFutureimplementation"androidx.room:room-guava:$room_version"// optional - Test helperstestImplementation"androidx.room:room-testing:$room_version"// optional - Paging 3 Integrationimplementation"androidx.room:room-paging:$room_version"}
المكونات الأساسية
هناك ثلاثة مكوّنات رئيسية في Room:
فئة قاعدة البيانات التي تحتوي على
قاعدة البيانات وتعمل بمثابة نقطة الوصول الرئيسية للاتصال الأساسي
ببيانات تطبيقك الثابتة
عناصر الوصول إلى البيانات (DAO) التي توفّر methods يمكن لتطبيقك استخدامها لطلب طلبات بحث عن data في قاعدة البيانات وتعديلها وإدراجها وحذفها
توفّر فئة قاعدة البيانات لتطبيقك مثيلات لـ DAO المرتبطة
بقاعدة البيانات هذه. في المقابل، يمكن للتطبيق استخدام واجهة DAO لاسترداد البيانات من قاعدة بيانات كمثيلات لكائنات عناصر البيانات المرتبطة. يمكن للتطبيق أيضًا
استخدام كيانات البيانات المحدّدة لتعديل الصفوف من الجداول المقابلة، أو
لإنشاء صفوف جديدة لإدراجها. يوضّح الشكل 1 العلاقة بين
المكوّنات المختلفة لـ Room.
الشكل 1. مخطّط بياني لبنية مكتبة Room
مثال على التنفيذ
يقدّم هذا القسم مثالاً على تنفيذ قاعدة بيانات Room باستخدام كينان data واحد وDAO واحد.
عنصر البيانات
تحدِّد التعليمة البرمجية التالية عنصر بيانات User. يمثّل كل مثيل من User
صفًا في جدول user في قاعدة بيانات التطبيق.
تحدِّد التعليمة البرمجية التالية DAO باسم UserDao. يوفّر UserDao methods التي تستخدمها بقية أجزاء التطبيق للتفاعل مع البيانات في جدول user.
Kotlin
@DaointerfaceUserDao{@Query("SELECT * FROM user")fungetAll():List<User>@Query("SELECT * FROM user WHERE uid IN (:userIds)")funloadAllByIds(userIds:IntArray):List<User>@Query("SELECT * FROM user WHERE first_name LIKE :first AND "+"last_name LIKE :last LIMIT 1")funfindByName(first:String,last:String):User@InsertfuninsertAll(varargusers:User)@Deletefundelete(user:User)}
Java
@DaopublicinterfaceUserDao{@Query("SELECT * FROM user")List<User>getAll();@Query("SELECT * FROM user WHERE uid IN (:userIds)")List<User>loadAllByIds(int[]userIds);@Query("SELECT * FROM user WHERE first_name LIKE :first AND "+"last_name LIKE :last LIMIT 1")UserfindByName(Stringfirst,Stringlast);@InsertvoidinsertAll(User...users);@Deletevoiddelete(Useruser);}
تحدِّد التعليمة البرمجية التالية فئة AppDatabase لتخزين قاعدة البيانات.
تحدِّد AppDatabase إعدادات قاعدة البيانات وتُستخدَم كنقطة
وصول التطبيق الرئيسية إلى البيانات الثابتة. يجب أن تستوفي فئة قاعدة البيانات الشروط التالية:
يجب أن يكون الصفّ مُعلَقًا بتعليق توضيحي
@Database يحتوي على
مصفوفة entities
تسرد جميع كيانات البيانات المرتبطة بقاعدة البيانات.
يجب أن تكون الفئة فئة مجردة تمديدًا لمحاولة
RoomDatabase.
بالنسبة إلى كل فئة DAO مرتبطة بقاعدة البيانات، يجب أن تحدِّد فئة قاعدة البيانات
طريقة مجردة لا تحتوي على أيّ وسيطات وتُعيد مثيلًا
لفئة DAO.
ملاحظة: إذا كان تطبيقك يعمل في عملية واحدة، عليك اتّباع
نمط التصميم للعنصر الفردي عند إنشاء مثيل لعنصر AppDatabase. إنّ كلّ نسخة من RoomDatabase باهظة التكلفة إلى حدٍّ ما، وقلّما تحتاج
إلى الوصول إلى نُسخ متعدّدة ضمن عملية واحدة.
إذا كان تطبيقك يعمل في عمليات متعددة، أدرِج enableMultiInstanceInvalidation() في استدعاء enableMultiInstanceInvalidation() لإنشاء قاعدة البيانات. بهذه الطريقة، عندما يكون لديك مثيل من AppDatabase
في كل عملية، يمكنك إلغاء صلاحية ملف قاعدة البيانات المشترَكة في عملية واحدة،
ويتم نشر هذا الإلغاء تلقائيًا إلى نُسخ AppDatabase
في العمليات الأخرى.
الاستخدام
بعد تحديد عنصر البيانات وDAO وعنصر قاعدة البيانات،
يمكنك استخدام الرمز البرمجي التالي لإنشاء مثيل لقاعدة البيانات:
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Save data in a local database using Room\nPart of [Android Jetpack](/jetpack).\n\nApps that handle non-trivial amounts of structured data can benefit greatly from\npersisting that data locally. The most common use case is to cache relevant\npieces of data so that when the device cannot access the network, the user can\nstill browse that content while they are offline.\n\nThe Room persistence library provides an abstraction layer over SQLite to allow\nfluent database access while harnessing the full power of SQLite. In particular,\nRoom provides the following benefits:\n\n- Compile-time verification of SQL queries.\n- Convenience annotations that minimize repetitive and error-prone boilerplate code.\n- Streamlined database migration paths.\n\nBecause of these considerations, we highly recommend that you use Room instead\nof [using the SQLite APIs directly](/training/data-storage/sqlite).\n\nSetup\n\nTo use Room in your app, add the following dependencies to your app's\n`build.gradle` file.\n**Note:** Choose only one of `ksp` or `annotationProcessor`. Don't include both. \n\nKotlin \n\n```kotlin\ndependencies {\n val room_version = \"2.7.2\"\n\n implementation(\"androidx.room:room-runtime:$room_version\")\n\n // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)\n // See /build/migrate-to-ksp#add-ksp\n ksp(\"androidx.room:room-compiler:$room_version\")\n\n // If this project only uses Java source, use the Java annotationProcessor\n // No additional plugins are necessary\n annotationProcessor(\"androidx.room:room-compiler:$room_version\")\n\n // optional - Kotlin Extensions and Coroutines support for Room\n implementation(\"androidx.room:room-ktx:$room_version\")\n\n // optional - RxJava2 support for Room\n implementation(\"androidx.room:room-rxjava2:$room_version\")\n\n // optional - RxJava3 support for Room\n implementation(\"androidx.room:room-rxjava3:$room_version\")\n\n // optional - Guava support for Room, including Optional and ListenableFuture\n implementation(\"androidx.room:room-guava:$room_version\")\n\n // optional - Test helpers\n testImplementation(\"androidx.room:room-testing:$room_version\")\n\n // optional - Paging 3 Integration\n implementation(\"androidx.room:room-paging:$room_version\")\n}\n```\n\nGroovy \n\n```groovy\ndependencies {\n def room_version = \"2.7.2\"\n\n implementation \"androidx.room:room-runtime:$room_version\"\n\n // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)\n // See https://kotlinlang.org/docs/ksp-quickstart.html to add KSP to your build\n ksp \"androidx.room:room-compiler:$room_version\"\n\n // If this project only uses Java source, use the Java annotationProcessor\n // No additional plugins are necessary\n annotationProcessor \"androidx.room:room-compiler:$room_version\"\n\n // optional - RxJava2 support for Room\n implementation \"androidx.room:room-rxjava2:$room_version\"\n\n // optional - RxJava3 support for Room\n implementation \"androidx.room:room-rxjava3:$room_version\"\n\n // optional - Guava support for Room, including Optional and ListenableFuture\n implementation \"androidx.room:room-guava:$room_version\"\n\n // optional - Test helpers\n testImplementation \"androidx.room:room-testing:$room_version\"\n\n // optional - Paging 3 Integration\n implementation \"androidx.room:room-paging:$room_version\"\n}\n```\n\nPrimary components\n\nThere are three major components in Room:\n\n- The [database class](/reference/kotlin/androidx/room/Database) that holds the database and serves as the main access point for the underlying connection to your app's persisted data.\n- [Data entities](/training/data-storage/room/defining-data) that represent tables in your app's database.\n- [Data access objects (DAOs)](/training/data-storage/room/accessing-data) that provide methods that your app can use to query, update, insert, and delete data in the database.\n\nThe database class provides your app with instances of the DAOs associated with\nthat database. In turn, the app can use the DAOs to retrieve data from the\ndatabase as instances of the associated data entity objects. The app can also\nuse the defined data entities to update rows from the corresponding tables, or\nto create new rows for insertion. Figure 1 illustrates the relationship between\nthe different components of Room.\n**Figure 1.** Diagram of Room library architecture.\n\nSample implementation\n\nThis section presents an example implementation of a Room database with a single\ndata entity and a single DAO.\n\nData entity\n\nThe following code defines a `User` data entity. Each instance of `User`\nrepresents a row in a `user` table in the app's database. \n\nKotlin \n\n```kotlin\n@Entity\ndata class User(\n @PrimaryKey val uid: Int,\n @ColumnInfo(name = \"first_name\") val firstName: String?,\n @ColumnInfo(name = \"last_name\") val lastName: String?\n)\n```\n\nJava \n\n```java\n@Entity\npublic class User {\n @PrimaryKey\n public int uid;\n\n @ColumnInfo(name = \"first_name\")\n public String firstName;\n\n @ColumnInfo(name = \"last_name\")\n public String lastName;\n}\n```\n\nTo learn more about data entities in Room, see [Defining data using Room\nentities](/training/data-storage/room/defining-data).\n\nData access object (DAO)\n\nThe following code defines a DAO called `UserDao`. `UserDao` provides the\nmethods that the rest of the app uses to interact with data in the `user` table. \n\nKotlin \n\n```kotlin\n@Dao\ninterface UserDao {\n @Query(\"SELECT * FROM user\")\n fun getAll(): List\u003cUser\u003e\n\n @Query(\"SELECT * FROM user WHERE uid IN (:userIds)\")\n fun loadAllByIds(userIds: IntArray): List\u003cUser\u003e\n\n @Query(\"SELECT * FROM user WHERE first_name LIKE :first AND \" +\n \"last_name LIKE :last LIMIT 1\")\n fun findByName(first: String, last: String): User\n\n @Insert\n fun insertAll(vararg users: User)\n\n @Delete\n fun delete(user: User)\n}\n```\n\nJava \n\n```java\n@Dao\npublic interface UserDao {\n @Query(\"SELECT * FROM user\")\n List\u003cUser\u003e getAll();\n\n @Query(\"SELECT * FROM user WHERE uid IN (:userIds)\")\n List\u003cUser\u003e loadAllByIds(int[] userIds);\n\n @Query(\"SELECT * FROM user WHERE first_name LIKE :first AND \" +\n \"last_name LIKE :last LIMIT 1\")\n User findByName(String first, String last);\n\n @Insert\n void insertAll(User... users);\n\n @Delete\n void delete(User user);\n}\n```\n\nTo learn more about DAOs, see [Accessing data using Room\nDAOs](/training/data-storage/room/accessing-data).\n\nDatabase\n\nThe following code defines an `AppDatabase` class to hold the database.\n`AppDatabase` defines the database configuration and serves as the app's main\naccess point to the persisted data. The database class must satisfy the\nfollowing conditions:\n\n- The class must be annotated with a [`@Database`](/reference/kotlin/androidx/room/Database) annotation that includes an [`entities`](/reference/kotlin/androidx/room/Database#entities) array that lists all of the data entities associated with the database.\n- The class must be an abstract class that extends [`RoomDatabase`](/reference/kotlin/androidx/room/RoomDatabase).\n- For each DAO class that is associated with the database, the database class must define an abstract method that has zero arguments and returns an instance of the DAO class.\n\nKotlin \n\n```kotlin\n@Database(entities = [User::class], version = 1)\nabstract class AppDatabase : RoomDatabase() {\n abstract fun userDao(): UserDao\n}\n```\n\nJava \n\n```java\n@Database(entities = {User.class}, version = 1)\npublic abstract class AppDatabase extends RoomDatabase {\n public abstract UserDao userDao();\n}\n``` \n**Note:** If your app runs in a single process, you should follow the\nsingleton design pattern when instantiating an `AppDatabase`\nobject. Each `RoomDatabase` instance is fairly expensive, and you\nrarely need access to multiple instances within a single process.\n\nIf your app runs in multiple processes, include\n`enableMultiInstanceInvalidation()` in your database builder\ninvocation. That way, when you have an instance of `AppDatabase`\nin each process, you can invalidate the shared database file in one process,\nand this invalidation automatically propagates to the instances of\n`AppDatabase` within other processes.\n\nUsage\n\nAfter you have defined the data entity, the DAO, and the database object, you\ncan use the following code to create an instance of the database: \n\nKotlin \n\n```kotlin\nval db = Room.databaseBuilder(\n applicationContext,\n AppDatabase::class.java, \"database-name\"\n ).build()\n```\n\nJava \n\n```java\nAppDatabase db = Room.databaseBuilder(getApplicationContext(),\n AppDatabase.class, \"database-name\").build();\n```\n\nYou can then use the abstract methods from the `AppDatabase` to get an instance\nof the DAO. In turn, you can use the methods from the DAO instance to interact\nwith the database: \n\nKotlin \n\n```kotlin\nval userDao = db.userDao()\nval users: List\u003cUser\u003e = userDao.getAll()\n```\n\nJava \n\n```java\nUserDao userDao = db.userDao();\nList\u003cUser\u003e users = userDao.getAll();\n```\n\nAdditional resources\n\nTo learn more about Room, see the following additional resources:\n\nSamples\n\nCodelabs\n\n- Android Room with a View [(Java)](/codelabs/android-room-with-a-view) [(Kotlin)](/codelabs/android-room-with-a-view-kotlin)\n\nBlogs\n\n- [7 Pro-tips for\n Room](https://medium.com/androiddevelopers/7-pro-tips-for-room-fbadea4bfbd1)\n- [Incrementally migrate from SQLite to\n Room](https://medium.com/androiddevelopers/incrementally-migrate-from-sqlite-to-room-66c2f655b377)"]]