Room 3.0

宣告依附元件

如要新增 Room3 的依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。

在應用程式或模組的 build.gradle 檔案中，新增您需要的構件依附元件：

dependencies {
    val room_version = ""

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

dependencies {
    def room_version = ""

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

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

如要瞭解如何使用 KSP 外掛程式，請參閱 KSP 快速入門說明文件。

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

使用 Room Gradle 外掛程式

您可以使用 Room Gradle 外掛程式設定 Room 編譯器的選項。 外掛程式會設定專案，確保產生的結構定義 (編譯工作的輸出內容，用於自動遷移) 正確設定，可重現且可快取建構作業。

如要新增外掛程式，請在頂層 Gradle 建構檔案中定義外掛程式及其版本。

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

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

在模組層級的 Gradle 建構檔案中，套用外掛程式並使用 room3 擴充功能。

plugins {
    id 'androidx.room3'
}

room3 {
    schemaDirectory "$projectDir/schemas"
}

plugins {
    id("androidx.room3")
}

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

使用 Room Gradle 外掛程式時，必須設定 schemaDirectory。這會設定 Room 編譯器和各種編譯工作及其後端 (kotlinc、KSP)，將結構定義檔案輸出至變種版本資料夾，例如 schemas/flavorOneDebug/com.package.MyDatabase/1.json。這些檔案應簽入存放區，以用於驗證和自動遷移。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

3.0 版

3.0.0-alpha01 版本

2026 年 3 月 11 日

發布 androidx.room3:room3-*:3.0.0-alpha01。

Room 3.0 (套件 androidx.room3) 是 Room 2.x 套件 (androidx.room) 的重大版本更新，著重於 Kotlin Multiplatform (KMP)。

核心註解 API 和主要元件維持不變：

• 擴充 androidx.room3.RoomDatabase 並以 @Database 註解標註的抽象類別，是 Room 註解處理工具的進入點。
• 資料庫宣告有一或多個資料類別，用於描述資料庫結構定義，並以 @Entity 註解。
• 資料庫作業是在 @Dao 宣告中定義，其中包含查詢函式，這些函式的 SQL 陳述式是透過 @Query 註解定義。
• 在執行階段，資料庫實作項目可透過 RoomDatabase.Builder 取得，這也用於設定資料庫。

「使用 Room 將資料儲存在本機資料庫」指南中的大部分文件，仍適用於 Room 3.0。

Room 2.x 的重大差異如下：

• 新套件：androidx.room3。
• 除非您使用 androidx.room3:room3-sqlite-wrapper，否則系統不再支援 SupportSQLite API。
• 所有資料庫作業現在都以協同程式 API 為基礎。
• 僅產生 Kotlin 程式碼。
• 必須使用 Kotlin Symbol Processing (KSP)。

除了重大變更外，與 2.x 版相比，Room 3.0 還帶來了新功能：

• 支援 JS 和 WasmJS
• 自訂 DAO 傳回型別

新套裝組合

為避免與現有 Room 2.x 實作項目發生相容性問題，以及與具有 Room 遞移依附元件的程式庫 (例如 WorkManager) 發生相容性問題，Room 3.0 位於新套件中，因此也有新的 Maven 群組和構件 ID。舉例來說，androidx.room:room-runtime 已變成 androidx.room3:room3-runtime，而 androidx.room.RoomDatabase 等類別現在位於 androidx.room3.RoomDatabase。

沒有 SupportSQLite API

Room 3.0 完全以 SQLiteDriver API 為基礎，不再參照 SupportSQLite 型別 (例如 SupportSQLiteDatabase) 或 Android 型別 (例如 Cursor)。這是 Room 3.0 和 2.x 之間最重大的變更，因為與 SupportSQLiteDatabase 對應的 RoomDatabase API，以及用於取得 SupportSQLiteOpenHelper 的 API 都已移除。現在必須提供 SQLiteDriver，才能建構 RoomDatabase。

舉例來說，直接資料庫作業的 API 會由對應的驅動程式取代：

// 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 做為引數的回呼 API 也已替換為以 SQLiteConnection 做為引數的對等 API。這些是遷移回呼函式，例如 Migration.onMigrate() 和 AutoMigrationSpec.onPostMigrate()，以及資料庫回呼，例如 RoomDatabase.Callback.onCreate()、RoomDatabase.Callback.onOpen() 等。

如果 KMP 專案使用 Room，則遷移至 3.0 版會比較簡單，因為主要涉及更新匯入參照，否則適用於從僅限 Android 的 Room 遷移至 KMP 的相同策略，請參閱 Room KMP 遷移指南。

SupportSQLite 包裝函式

Room 3.x 會保留 2.x 中建立的 SupportSQLite 包裝函式，方便遷移，且現在位於新的構件 androidx.room3:room3-sqlite-wrapper 中。相容性 API 可將 RoomDatabase 轉換為 SupportSQLiteDatabase。roomDatabase.openHelper.writableDatabase 的呼叫可以替換為 roomDatabase.getSupportWrapper()。

以 Kotlin 和協同程式為優先

為進一步發展程式庫，Room 3.0 只會產生 Kotlin 程式碼，而且只會是 Kotlin 符號處理器 (KSP)。與 Room 2.x 相比，Room 3.0 不會產生 Java 程式碼，且無法再透過 KAPT 或 JavaAP 設定註解處理工具。請注意，KSP 可以處理 Java 來源，而 Room 編譯器會為來源宣告位於 Java 中的資料庫、實體或 DAO 產生程式碼。建議您使用多模組專案，集中使用 Room，並套用 Kotlin Gradle 外掛程式和 KSP，而不影響其餘程式碼集。

Room 3.0 也需要使用協同程式，更具體來說，除非 DAO 函式傳回反應式型別 (例如 Flow 或自訂 DAO 傳回型別)，否則必須暫停。Room API (用於執行資料庫作業) 也是暫停函式，例如 RoomDatabase.useReaderConnection 和 RoomDatabase.useWriterConnection。

與 Room 2.x 不同，您無法再使用 Executor 設定 RoomDatabase，而是透過資料庫的建構工具提供 CoroutineContext 和調度器。

Room 3.0 中的 InvalidationTracker API 是以 Flow 為基礎，InvalidationTracker.Observer 會連同相關 API addObserver 和 removeObserver 一併移除。如要對資料庫作業做出反應，請透過 InvalidationTracker 中的 createFlow() API 建立協同程式流程。

使用範例：

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 為目標，以及位於新構件 androidx.sqlite:sqlite-web 的新驅動程式 WebWorkerSQLiteDriver，您可以在以所有主要 KMP 平台為目標的通用程式碼中使用 Room。

由於網頁平台具有非同步性質，因此以 SQLiteStatement 做為引數的 Room API 現在是暫停函式。例如 Migration.onMigrate()、RoomDatabase.Callback.onCreate()、PooledConnection.usePrepared() 等。在驅動程式 API 中，非同步 API 在所有平台上都很常見，同步 API 則常見於非網頁目標。因此，如果專案並非以網頁為目標，仍可在通用程式碼中使用同步 API (SQLiteDriver.open()、SQLiteConnection.prepare() 和 SQLiteStatement.step())。同時，僅以網頁為目標的專案必須使用非同步 API (SQLiteDriver.openAsync()、SQLiteConnection.prepareAsync() 和 SQLiteStatement.stepAsync())。

為方便起見，androidx.sqlite 套件也新增了暫停擴充功能，並使用上述 API 的同步名稱 (新增 SQLiteConnection.executeSQL)，如果專案同時以網頁和非網頁平台為目標，建議使用這些 API，因為這些 API 是預期 / 實際的宣告，會根據平台呼叫正確的變體。這些是 Room 執行階段使用的 API，可讓所有支援平台的通用程式碼使用驅動程式。

使用範例：

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 通訊，在主要執行緒外執行資料庫作業，並將資料庫儲存在 Origin Private File System (OPFS)。如要例項化驅動程式，必須有實作簡單通訊協定的工作站，該協定說明請參閱 WebWorkerSQLiteDriver KDoc。

目前 WebWorkerSQLiteDriver 不會隨附實作通訊協定的預設工作者，但舉例來說，androidx 程式碼集包含可供專案使用的工作者實作。這項功能使用 SQLite 的 WASM，並將資料庫儲存在 OPFS 中。範例工作站會發布為本機 NPM 套件，並透過 Kotlin 對 NPM 依附元件的支援，建立小型 KMP 模組來提供工作站服務。

請參閱下列 GitHub 專案，瞭解如何使用 Room 的本機網頁工作人員。

在專案中設定工作人員後，設定網頁版 Room 的方式與其他平台類似：

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 驅動程式版本可能會包含發布在 NPM 中的預設工作站，讓 Web 設定更簡單。

自訂 DAO 傳回型別

各種 DAO 傳回型別整合 (例如 RxJava 和 Paging 的整合) 已轉換為使用 Room 3.0 中的新 API，稱為 DAO 傳回型別轉換器。DAO 傳回類型轉換器函式 (@DaoReturnTypeConverter) 可將 DAO 函式的結果轉換為註解函式定義的自訂型別。這些函式可讓您參與 Room 產生的程式碼，將查詢結果轉換為資料物件。含有 DAO 傳回型別轉換器的類別必須透過 @Database 或 @Dao 宣告中的 @DaoReturnTypeConverters 註解註冊。

舉例來說，如要讓 DAO 查詢傳回 PagingSource，現在必須註冊位於 androidx.room3:room3-paging 的轉換器類別：

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

現有整合項目已移至 DAO 傳回類型轉換器：

與資料欄類型轉換器類似，DAO 傳回類型轉換器可由應用程式定義。舉例來說，應用程式可以為網頁類型 kotlin.js.Promise 宣告 @DaoReturnTypeConverter。

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>：(選用) 包含查詢存取的資料表，與 Room 的 InvalidationTracker.createFlow() API 搭配使用時，有助於支援可觀測 / 反應式型別。
• rawQuery: RoomRawQuery：(選用) 在執行階段包含查詢的執行個體，可啟用轉換，例如 PagingSourceDaoReturnTypeConverter 實作的 LIMIT / OFFSET 策略。
• executeAndConvert: suspend () -> T：(必要) Room 產生的函式，用於執行查詢並將結果剖析為資料物件。

如要進一步瞭解建立 DAO 回傳型別轉換器的規定，請參閱 API 的 @DaoReturnTypeConverter KDoc。