Room 3.0

توفر مكتبة Room للبيانات الثابتة طبقة تجريد فوق SQLite للسماح بالوصول إلى قاعدة البيانات بشكل أكثر فعالية مع الاستفادة من إمكانات SQLite الكاملة.

آخر الأخبار	الإصدار الثابت	إصدار محتمل	الإصدار التجريبي	الإصدار الأولي
‫11 مارس 2026	-	-	-	3.0.0-alpha01

تحديد الاعتماديات

لإضافة اعتمادية على Room3، يجب تضمين مستودع Google Maven في مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.

أضِف الاعتماديات الخاصة بالعناصر التي تحتاج إليها في ملف build.gradle لتطبيقك أو وحدتك:

Kotlin

dependencies {
    val room_version = ""

    implementation("androidx.room3:room3-runtime:$room_version")
    ksp("androidx.room3:room3-compiler:$room_version")
}

Groovy

dependencies {
    def room_version = ""

    implementation "androidx.room3:room3-runtime:$room_version"

    ksp "androidx.room3:room3-compiler:$room_version"
}

للحصول على معلومات حول استخدام المكوّن الإضافي KSP، يُرجى الاطّلاع على مستندات البدء السريع في KSP.

لمزيد من المعلومات حول الاعتماديات، يُرجى الاطّلاع على إضافة اعتماديات الإصدار.

استخدام المكوّن الإضافي لنظام Gradle المتوافق مع Room

يمكنك استخدام Room Gradle Plugin لضبط خيارات برنامج Room البرمجي. تضبط الإضافة المشروع بحيث يتم ضبط المخططات التي تم إنشاؤها (وهي ناتج مهام التجميع ويتم استخدامها في عمليات النقل التلقائي) بشكل صحيح لإنشاء إصدارات قابلة للتكرار والتخزين المؤقت.

لإضافة المكوّن الإضافي، حدِّد المكوّن الإضافي وإصداره في ملف تصميم Gradle ذي المستوى الأعلى.

Groovy

plugins {
    id 'androidx.room3' version "$room_version" apply false
}

Kotlin

plugins {
    id("androidx.room3") version "$room_version" apply false
}

في ملف تصميم Gradle على مستوى الوحدة، طبِّق المكوّن الإضافي واستخدِم إضافة room3.

Groovy

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

Kotlin

plugins {
    id("androidx.room3")
}

room3 {
    schemaDirectory("$projectDir/schemas")
}

يجب ضبط schemaDirectory عند استخدام مكوّن Room الإضافي في Gradle. سيؤدي ذلك إلى ضبط برنامج Room المجمّع ومهام التجميع المختلفة وبرامج الخلفية (kotlinc وKSP) لإخراج ملفات المخطط إلى مجلدات ذات إصدارات مختلفة، مثل schemas/flavorOneDebug/com.package.MyDatabase/1.json. يجب إيداع هذه الملفات في المستودع لاستخدامها في عمليات التحقّق والترحيل التلقائي.

الملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إعلامنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مشكلة جديدة. يمكنك إضافة صوتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء مشكلة جديدة

يُرجى الاطّلاع على مستندات Issue Tracker للحصول على مزيد من المعلومات.

الإصدار ‎‏‎3.0

الإصدار 3.0.0-alpha01

‫11 مارس 2026

تم طرح androidx.room3:room3-*:3.0.0-alpha01.

‫Room 3.0 (الحزمة androidx.room3) هو تحديث رئيسي لإصدار حزمة Room 2.x (androidx.room) يركّز على Kotlin Multiplatform (KMP).

تم الإبقاء على واجهات برمجة التطبيقات الأساسية الخاصة بالتعليقات التوضيحية كما هي، بالإضافة إلى المكوّنات الرئيسية:

الفئة المجردة التي توسّع androidx.room3.RoomDatabase ويتم إضافة تعليق توضيحي إليها باستخدام @Database هي نقطة الدخول إلى معالج التعليقات التوضيحية في Room.
يحتوي تعريف قاعدة البيانات على فئة بيانات واحدة أو أكثر تصف مخطط قاعدة البيانات، ويتم إضافة التعليق التوضيحي @Entity إليها.
يتم تحديد عمليات قاعدة البيانات في تصريحات @Dao التي تحتوي على دوال استعلام يتم تحديد عبارات SQL الخاصة بها من خلال التعليق التوضيحي @Query.
أثناء وقت التشغيل، يمكن الحصول على تنفيذ قاعدة البيانات من خلال RoomDatabase.Builder الذي يُستخدم أيضًا لضبط قاعدة البيانات.

لا يزال معظم المحتوى في دليل حفظ البيانات في قاعدة بيانات محلية باستخدام Room مناسبًا لإصدار Room 3.0.

في ما يلي الاختلافات الرئيسية التي تتسبّب في حدوث أعطال بين Room 2.x:

حزمة جديدة، androidx.room3
لم تعُد واجهات برمجة التطبيقات SupportSQLite متوافقة، إلا إذا كنت تستخدم androidx.room3:room3-sqlite-wrapper.
تستند جميع عمليات قاعدة البيانات الآن إلى واجهات برمجة تطبيقات Coroutine.
إنشاء رموز Kotlin البرمجية فقط
يجب استخدام أداة Kotlin Symbol Processing (KSP).

بالإضافة إلى التغييرات غير المتوافقة، يوفّر الإصدار 3.0 من Room وظائف جديدة مقارنةً بالإصدار 2.x:

التوافق مع JavaScript وWasmJS
أنواع العائدات المخصّصة من DAO

حزمة جديدة

لمنع حدوث مشاكل في التوافق مع عمليات التنفيذ الحالية للإصدار 2.x من Room ومع المكتبات التي تتضمّن تبعيات متعدّية إلى Room (مثل WorkManager)، يتوفّر الإصدار 3.0 من Room في حزمة جديدة، ما يعني أنّه يتضمّن أيضًا مجموعة Maven ومعرّفات عناصر جديدة. على سبيل المثال، أصبح androidx.room:room-runtime androidx.room3:room3-runtime، وسيتم نقل الصفوف مثل androidx.room.RoomDatabase إلى androidx.room3.RoomDatabase.

عدم توفّر واجهات برمجة تطبيقات SupportSQLite

يستند الإصدار 3.0 من Room بالكامل إلى واجهات برمجة التطبيقات SQLiteDriver ولم يعُد يشير إلى أنواع SupportSQLite مثل SupportSQLiteDatabase أو أنواع Android مثل Cursor. هذا هو التغيير الأهم بين الإصدارين 3.0 و2.x من Room، وذلك بعد إزالة واجهات برمجة التطبيقات RoomDatabase التي كانت تحاكي SupportSQLiteDatabase، بالإضافة إلى واجهة برمجة التطبيقات التي كانت تستخدم للحصول على SupportSQLiteOpenHelper. يجب الآن توفير SQLiteDriver لإنشاء RoomDatabase.

على سبيل المثال، يتم استبدال واجهات برمجة التطبيقات الخاصة بعمليات قواعد البيانات المباشرة بمكافئاتها في برنامج التشغيل:

// Room 2.x
roomDatabase.runInTransaction { ... }

// Room 3.x
roomDatabase.withWriteTransaction { ... }

// Room 2.x
roomDatabase.query("SELECT * FROM Song").use { cursor -> ... }

// Room 3.x
roomDatabase.useReaderConnection { connection ->
  connection.usePrepared("SELECT * FROM Song") { stmt -> ... }
}

تم أيضًا استبدال واجهات برمجة التطبيقات التي تتضمّن SupportSQLiteDatabase كمعلَمة بواجهات برمجة تطبيقات مكافئة تتضمّن SQLiteConnection كمعلَمة. وهي دوالّ عمليات إعادة الاستدعاء الخاصة بعمليات النقل، مثل Migration.onMigrate() وAutoMigrationSpec.onPostMigrate()، بالإضافة إلى عمليات إعادة الاستدعاء الخاصة بقاعدة البيانات، مثل RoomDatabase.Callback.onCreate() وRoomDatabase.Callback.onOpen() وما إلى ذلك.

إذا كان يتم استخدام Room في مشروع KMP، سيكون الانتقال إلى الإصدار 3.0 أبسط لأنّه يتضمّن بشكل أساسي تعديل مراجع الاستيراد، وإلا سيتم تطبيق استراتيجية النقل نفسها من Room في Android فقط إلى KMP، راجِع دليل نقل بيانات Room إلى KMP.

SupportSQLite Wrapper

يحتفظ الإصدار 3.x من Room بغلاف SupportSQLite الذي تم إنشاؤه في الإصدار 2.x لتسهيل عمليات نقل البيانات ويتم الآن تخزينه في العنصر الجديد androidx.room3:room3-sqlite-wrapper. تتيح لك واجهة برمجة التطبيقات المتوافقة تحويل RoomDatabase إلى SupportSQLiteDatabase. يمكن استبدال استدعاءات roomDatabase.openHelper.writableDatabase باستدعاءات roomDatabase.getSupportWrapper().

التركيز على Kotlin وCoroutines أولاً

ولتحسين المكتبة، لا ينشئ الإصدار 3.0 من Room سوى رموز Kotlin البرمجية، وهو عبارة عن أداة Kotlin Symbol Processor (KSP) فقط. مقارنةً بالإصدار 2.x من Room، لن يكون هناك إنشاء لرمز Java أو ضبط لمعالج التعليقات التوضيحية من خلال KAPT أو JavaAP في الإصدار 3.0 من Room. يُرجى العِلم أنّ KSP يمكنه معالجة مصادر Java، وأنّ برنامج Room المترجِم سينشئ رمزًا برمجيًا لقاعدة البيانات أو الكيانات أو عناصر الوصول إلى البيانات (DAO) التي تكون بيانات المصدر الخاصة بها بتنسيق Java. ننصحك بإنشاء مشروع يتضمّن عدّة وحدات يتم فيه تركيز استخدام Room، ويمكن تطبيق إضافة Kotlin Gradle وKSP بدون التأثير في بقية قاعدة الرموز البرمجية.

يتطلّب الإصدار 3.0 من Room أيضًا استخدام الروتينات الفرعية، وبشكل أكثر تحديدًا، يجب أن تكون دوال الكائن الوصول إلى البيانات (DAO) قابلة للتعليق ما لم تعرض نوع القيمة التي تم إرجاعها تفاعليًا، مثل Flow أو نوع القيمة التي تم إرجاعها مخصّصًا للكائن الوصول إلى البيانات. تكون واجهات برمجة التطبيقات الخاصة بمكتبة Room التي تنفّذ عمليات قاعدة البيانات أيضًا دوال معلّقة، مثل RoomDatabase.useReaderConnection وRoomDatabase.useWriterConnection.

على عكس الإصدار 2.x من Room، لم يعُد من الممكن ضبط RoomDatabase باستخدام Executor، بل يمكن توفير CoroutineContext مع أداة إرسال من خلال أداة إنشاء قاعدة البيانات.

تستند واجهات برمجة التطبيقات InvalidationTracker في Room 3.0 إلى Flow، تمت إزالة InvalidationTracker.Observer مع واجهات برمجة التطبيقات ذات الصلة addObserver وremoveObserver. تتم آلية الاستجابة لعملية قاعدة البيانات من خلال Coroutine Flows التي يمكن إنشاؤها عبر واجهة برمجة التطبيقات createFlow() في InvalidationTracker.

مثال على الاستخدام:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
    return db.invalidationTracker.createFlow("Artist").map { _ ->
        val artists = artistsDao.getAllArtists()
        val tours = tourService.fetchStates(artists.map { it.id })
        associateTours(artists, tours, from, to)
    }
}

دعم الويب

يضيف إصدار Room 3.0 JavaScript وWasmJs كاستهدافات في KMP. بالإضافة إلى إصدار واجهات SQLiteDriver (androidx.sqlite:sqlite) التي تستهدف أيضًا JavaScript وWasmJs وبرنامج تشغيل جديد WebWorkerSQLiteDriver مضمّن في العنصر الجديد androidx.sqlite:sqlite-web، يمكن استخدام Room في الرمز المشترك الذي يستهدف جميع منصات KMP الرئيسية.

بسبب الطبيعة غير المتزامنة للمنصات على الويب، أصبحت واجهات برمجة التطبيقات Room التي كانت تأخذ SQLiteStatement كمعلَمة هي الآن دوال معلَّقة. من الأمثلة على هذه الدوال Migration.onMigrate() وRoomDatabase.Callback.onCreate() وPooledConnection.usePrepared() وغيرها. في واجهات برمجة التطبيقات الخاصة ببرامج التشغيل، تكون واجهات برمجة التطبيقات غير المتزامنة شائعة على جميع المنصات، بينما تكون واجهات برمجة التطبيقات المتزامنة شائعة مع الاستهدافات غير المستندة إلى الويب. لذلك، يمكن لمشروع لا يستهدف الويب مواصلة استخدام واجهات برمجة التطبيقات المتزامنة (SQLiteDriver.open() وSQLiteConnection.prepare() وSQLiteStatement.step()) في الرمز البرمجي المشترك. في الوقت نفسه، يجب أن يستخدم المشروع الذي يستهدف الويب فقط واجهات برمجة التطبيقات غير المتزامنة (SQLiteDriver.openAsync() وSQLiteConnection.prepareAsync() وSQLiteStatement.stepAsync()).

لتسهيل الأمر، أضافت حزمة androidx.sqlite أيضًا دوال تعليق مع أسماء متزامنة لواجهات برمجة التطبيقات المذكورة (مع إضافة SQLiteConnection.executeSQL)، ويُنصح باستخدام واجهات برمجة التطبيقات هذه عندما يستهدف المشروع كلاً من المنصات على الويب وغير الويب، لأنّ واجهات برمجة التطبيقات هي تصريحات متوقّعة / فعلية ستطلب النوع المناسب استنادًا إلى المنصات. هذه هي واجهات برمجة التطبيقات التي يستخدمها وقت التشغيل في Room وتتيح استخدام برنامج التشغيل في الرمز البرمجي الشائع لجميع الأنظمة الأساسية المتوافقة.

مثال على الاستخدام:

import androidx.sqlite.executeSQL
import androidx.sqlite.step

roomDatabase.useWriterConnection { connection ->
    val deletedSongs = connection.usePrepared(
        "SELECT count(*) FROM Song"
    ) { stmt ->
        stmt.step()
        stmt.getLong(0)
    }
    connection.executeSQL("DELETE FROM Song")
    deletedSongs
}

WebWorkerSQLiteDriver هي عملية تنفيذ SQLiteDriver تتواصل مع Web Worker لتنفيذ عملية قاعدة البيانات خارج سلسلة التعليمات الرئيسية، وتتيح تخزين قاعدة البيانات في نظام ملفات خاص بالمصدر (OPFS). لتنفيذ برنامج التشغيل، يجب توفير عامل ينفّذ بروتوكول تواصل بسيط، ويتم وصف البروتوكول في WebWorkerSQLiteDriver KDoc.

في الوقت الحالي، لا يتم شحن WebWorkerSQLiteDriver مع عامل تلقائي ينفّذ بروتوكول الاتصال، ولكن على سبيل المثال، يحتوي رمز قاعدة بيانات androidx على تنفيذ عامل يمكن استخدامه في مشروعك. يستخدم WASM من SQLite ويخزّن قاعدة البيانات في نظام ملفات المصدر الخاص (OPFS). يتم نشر عامل المثال كحزمة NPM محلية، وبفضل إتاحة Kotlin لتوابع NPM، يمكن إنشاء وحدة KMP صغيرة لتوفير العامل.

اطّلِع على مشروع GitHub التالي الذي يوضّح كيفية استخدام عامل ويب محلي مع Room.

بعد إعداد عامل في المشروع، يكون ضبط Room for the Web مشابهًا للأنظمة الأساسية الأخرى:

fun createDatabase(): MusicDatabase {
    return Room.databaseBuilder<MusicDatabase>("music.db")
        .setDriver(WebWorkerSQLiteDriver(createWorker()))
        .build()
}

fun createWorker() =
    Worker(js("""new URL("sqlite-web-worker/worker.js", import.meta.url)"""))

قد يحتوي إصدار مستقبلي من Web driver على عامل تلقائي منشور في NPM، ما يسهّل عملية إعداد الويب.

أنواع الإرجاع المخصّصة لكائن الوصول إلى البيانات (DAO)

تم تحويل عمليات دمج أنواع الإرجاع المختلفة الخاصة بكائنات الوصول إلى البيانات (DAO)، مثل عمليات الدمج الخاصة بـ RxJava وPaging، لاستخدام واجهة برمجة تطبيقات جديدة في Room 3.0 تُسمى محوّلات أنواع القيمة التي تم إرجاعها الخاصة بكائنات الوصول إلى البيانات (DAO). تتيح دالة محوّل نوع القيمة التي تم إرجاعها الخاصة بـ DAO (@DaoReturnTypeConverter) تحويل نتيجة دالة DAO إلى نوع مخصّص محدّد بواسطة الدالة التي تمّت إضافة التعليقات التوضيحية إليها. تتيح هذه الدوال المشاركة في الرمز البرمجي الذي ينشئه Room والذي يحوّل نتائج طلب البحث إلى عناصر بيانات. يجب تسجيل الفئات التي تحتوي على محوّلات أنواع القيمة التي تم إرجاعها الخاصة بكائنات الوصول إلى البيانات (DAO) من خلال التعليقات التوضيحية @DaoReturnTypeConverters في بيانات @Database أو @Dao.

على سبيل المثال، لكي يعرض طلب بحث DAO القيمة PagingSource، يجب الآن تسجيل فئة المحوّل الموجودة في androidx.room3:room3-paging:

@Dao
@DaoReturnTypeConverters(PagingSourceDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song)
    fun getSongsPaginated(): PagingSource<Int, Song>
}

تم نقل عمليات الدمج الحالية إلى محوّلات نوع القيمة التي تم إرجاعها في DAO:

نوع القيمة التي يتم إرجاعها	فئة المحوّل	العناصر
PagingSource	PagingSourceDaoReturnTypeConverter	androidx.room3:room3-paging
Observable وFlowable وCompletable وSingle وMaybe	RxDaoReturnTypeConverters	androidx.room3:room3-rxjava3
ListenableFuture	GuavaDaoReturnTypeConverter	androidx.room3:room3-guava
LiveData	LiveDataDaoReturnTypeConverter	androidx.room3:room3-livedata

مثل محوّلات أنواع الأعمدة، يمكن تحديد محوّلات نوع القيمة التي تم إرجاعها الخاصة بكائنات الوصول إلى البيانات (DAO) من خلال التطبيق. على سبيل المثال، يمكن أن يعرّف التطبيق @DaoReturnTypeConverter لنوع الويب kotlin.js.Promise.

object PromiseDaoReturnTypeConverter {
    @DaoReturnTypeConverter([OperationType.READ, OperationType.WRITE])
    fun <T> convert(
        db: RoomDatabase,
        executeAndConvert: suspend () -> T
    ): Promise<T> {
        return db.getCoroutineScope().promise { executeAndConvert() }
    }
}

يسمح المحوّل أعلاه بعد ذلك لوظائف طلبات البحث في DAO بعرض Promise:

@Dao
@DaoReturnTypeConverters(PromiseDaoReturnTypeConverter::class)
interface MusicDao {
    @Query("SELECT * FROM Song")
    fun getAllSongs(): Promise<List<Song>>
}

تتضمّن الدالة @DaoReturnTypeConverter بعض المتطلبات المتعلقة بعدد المَعلمات وأنواعها. المَعلمات المحتملة هي:

db: RoomDatabase: (اختياري) يتيح الوصول إلى RoomDatabase النسخة، ما قد يكون مفيدًا لتنفيذ عمليات إضافية على قاعدة البيانات أو الوصول إلى نطاق الروتين الفرعي.
‫tableNames: Array<String>: (اختياري) يحتوي على الجداول التي تم الوصول إليها في طلب البحث، وهو مفيد في دعم الأنواع القابلة للمراقبة / التفاعلية عند دمجه مع واجهة برمجة التطبيقات InvalidationTracker.createFlow() في Room.
‫rawQuery: RoomRawQuery: (اختياري) يحتوي في وقت التشغيل على مثيل لطلب البحث، ما يتيح إجراء عمليات تحويل مثل استراتيجية LIMIT / OFFSET التي تنفّذها PagingSourceDaoReturnTypeConverter.
‫executeAndConvert: suspend () -> T: (مطلوب) الدالة التي تم إنشاؤها في Room والتي ستنفّذ طلب البحث وتحلّل نتيجته إلى عناصر بيانات.

لمزيد من المعلومات حول متطلبات إنشاء محوّل لنوع القيمة التي تم إرجاعها الخاص بـ DAO، يُرجى الاطّلاع على KDoc على واجهة برمجة التطبيقات @DaoReturnTypeConverter.