با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
با استفاده از قسمت Room Android Jetpack داده ها را در یک پایگاه داده محلی ذخیره کنید.
برنامههایی که مقادیر غیر جزئی دادههای ساختاریافته را مدیریت میکنند، میتوانند از ماندگاری آن دادهها به صورت محلی سود زیادی ببرند. رایجترین مورد استفاده، ذخیره اطلاعات مربوطه در حافظه پنهان است تا زمانی که دستگاه نمیتواند به شبکه دسترسی داشته باشد، کاربر همچنان بتواند آن محتوا را در حالی که آفلاین است مرور کند.
کتابخانه تداوم اتاق یک لایه انتزاعی را روی SQLite فراهم می کند تا در عین استفاده از قدرت کامل SQLite، به پایگاه داده روان دسترسی داشته باشد. به طور خاص، Room مزایای زیر را ارائه می دهد:
تأیید زمان کامپایل پرس و جوهای SQL.
حاشیه نویسی راحت که کد دیگ بخار تکراری و مستعد خطا را به حداقل می رساند.
برای استفاده از Room در برنامه خود، وابستگی های زیر را به فایل build.gradle برنامه خود اضافه کنید.
کاتلین
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")}
شیار
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"}
اجزای اولیه
سه جزء اصلی در اتاق وجود دارد:
کلاس پایگاه داده ای که پایگاه داده را نگه می دارد و به عنوان نقطه دسترسی اصلی برای اتصال زیربنایی به داده های پایدار برنامه شما عمل می کند.
اشیاء دسترسی به داده (DAO) که روشهایی را ارائه میدهند که برنامه شما میتواند از آنها برای جستجو، بهروزرسانی، درج و حذف دادهها در پایگاه داده استفاده کند.
کلاس پایگاه داده نمونه هایی از DAO های مرتبط با آن پایگاه داده را به برنامه شما ارائه می دهد. به نوبه خود، برنامه می تواند از DAO ها برای بازیابی داده ها از پایگاه داده به عنوان نمونه هایی از اشیاء موجودیت داده مرتبط استفاده کند. این برنامه همچنین می تواند از موجودیت های داده تعریف شده برای به روز رسانی ردیف ها از جداول مربوطه یا ایجاد ردیف های جدید برای درج استفاده کند. شکل 1 رابطه بین اجزای مختلف اتاق را نشان می دهد.
شکل 1. نمودار معماری کتابخانه اتاق.
اجرای نمونه
این بخش نمونه ای از اجرای یک پایگاه داده اتاق با یک موجودیت داده و یک DAO را ارائه می دهد.
موجودیت داده
کد زیر یک موجودیت داده User را تعریف می کند. هر نمونه از User نشان دهنده یک ردیف در جدول user در پایگاه داده برنامه است.
کد زیر یک DAO به نام UserDao را تعریف می کند. UserDao روش هایی را ارائه می دهد که بقیه برنامه برای تعامل با داده های جدول user استفاده می کند.
کاتلین
@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)}
جاوا
@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 باید از الگوی طراحی singleton پیروی کنید. هر نمونه RoomDatabase نسبتاً گران است و به ندرت نیاز به دسترسی به چندین نمونه در یک فرآیند واحد دارید.
اگر برنامه شما در چندین فرآیند اجرا می شود، enableMultiInstanceInvalidation() در فراخوانی سازنده پایگاه داده خود قرار دهید. به این ترتیب، هنگامی که در هر فرآیند یک نمونه از AppDatabase دارید، می توانید فایل پایگاه داده مشترک را در یک فرآیند باطل کنید و این عدم اعتبار به طور خودکار به نمونه های AppDatabase در سایر فرآیندها منتشر می شود.
استفاده
پس از اینکه موجودیت داده، DAO و شی پایگاه داده را تعریف کردید، می توانید از کد زیر برای ایجاد یک نمونه از پایگاه داده استفاده کنید:
سپس می توانید از روش های انتزاعی از AppDatabase برای دریافت نمونه ای از DAO استفاده کنید. به نوبه خود، می توانید از روش های نمونه DAO برای تعامل با پایگاه داده استفاده کنید:
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و 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)"]]