يمكن للتطبيقات التي تعالج كميات كبيرة من البيانات المنظَّمة أن تستفيد بشكل كبير من الاحتفاظ بهذه البيانات على الجهاز. وأكثر حالات الاستخدام شيوعًا هي تخزين أجزاء البيانات ذات الصلة مؤقتًا، حتى يتمكّن المستخدم من تصفّح هذا المحتوى بلا إنترنت عندما يتعذّر على الجهاز الوصول إلى الشبكة.
توفر مكتبة 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) التي توفّر طرقًا يمكن لتطبيقك استخدامها للاستعلام عن البيانات وتعديلها وإدراجها وحذفها في قاعدة البيانات
يوفر فئة قاعدة البيانات لتطبيقك مثيلات من عناصر الوصول إلى البيانات (DAO) المرتبطة بقاعدة البيانات هذه. وبدورها، يمكن للتطبيق استخدام كائنات الوصول إلى البيانات لاسترداد البيانات من قاعدة البيانات كعناصر من كائنات كيانات البيانات المرتبطة. يمكن للتطبيق أيضًا استخدام كيانات البيانات المحدّدة لتعديل الصفوف من الجداول ذات الصلة أو لإنشاء صفوف جديدة لإدراجها. يوضّح الشكل 1 العلاقة بين المكوّنات المختلفة لمكتبة Room.
الشكل 1. مخطّط لبنية مكتبة Room
مثال على التنفيذ
يعرض هذا القسم مثالاً على تنفيذ قاعدة بيانات Room تتضمّن كيان بيانات واحدًا وDAO واحدًا.
كيان البيانات
تحدّد التعليمة البرمجية التالية كيان بيانات User. يمثّل كل مثيل من User
صفًا في جدول user في قاعدة بيانات التطبيق.
يحدّد الرمز التالي كائن الوصول إلى البيانات (DAO) باسم UserDao. يوفر UserDao الطرق التي يستخدمها بقية التطبيق للتفاعل مع البيانات في جدول 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() في استدعاء أداة إنشاء قاعدة البيانات. بهذه الطريقة، عندما يكون لديك مثيل من AppDatabase
في كل عملية، يمكنك إبطال ملف قاعدة البيانات المشتركة في إحدى العمليات،
وسيتم نشر عملية الإبطال هذه تلقائيًا إلى مثيلات
AppDatabase في العمليات الأخرى.
الاستخدام
بعد تحديد كيان البيانات وDAO وكائن قاعدة البيانات، يمكنك استخدام الرمز التالي لإنشاء مثيل لقاعدة البيانات:
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-09-01 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-09-01 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],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)"]]