DataStore

宣告依附元件

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

DataStore 有兩種實作方式：偏好設定和 Proto。選擇其中一項。您還可以在任一實作方式中新增無 Android 依附元件。

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

Preferences DataStore

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.1.6"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.1.6"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.1.6"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.1.6"
    }
    

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.1.6")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.1.6")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.1.6")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.1.6")
    }
    

Proto DataStore

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.1.6"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.1.6"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.1.6"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.1.6"
    }
    

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.1.6")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.1.6")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.1.6")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.1.6")
    }
    

意見回饋

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

建立新問題

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

1.2 版本

1.2.0-alpha02 版本

2025 年 5 月 7 日

發布 androidx.datastore:datastore-*:1.2.0-alpha02。1.2.0-alpha02 版包含這些修訂版本。

API 變更

• 在 GuavaDataStore 中新增多程序支援。(e0d608a)。
• 新增輔助方法，可從 DataStore 建立 GuavaDataStore。(9af26f4)
• 使用 Kotlin 2.0 發布的專案需要使用 KGP 2.0.0 以上版本。(Idb6b5)。
• 將現有的 datastore 超載替換為委派方法，以便在直接啟動期間初始化 DataStore。(If71b9)。

1.2.0-alpha01 版本

2025 年 3 月 26 日

發布 androidx.datastore:datastore-*:1.2.0-alpha01。1.2.0-alpha01 版包含這些修訂版本。

新功能

• 新增 datastore-guava 模組，透過 GuavaDataStore 公開對 Java 和 Guava ListenableFuture 使用者友善的 API。(Iadd5e0)
• DirectBoot 模式現在支援 DataStore 用法。如要建立在直接啟動模式下使用的資料儲存庫，則必須在裝置保護儲存空間中建立。您可以使用下列新的 DataStore API 達成此目標：DataStoreFactory 中的 createInDeviceProtectedStorage() 和 DataStoreDelegate 中的 deviceProtectedDataStore()。(Ib90e56)

API 變更

• 新增實作 androidx.datastore.core.Serializer 介面的 PreferencesFileSerializer，可與 FileStorage 搭配使用。(I4c71f3)。

修正錯誤

• 在啟動時解決 OkioStorage 中的 FileNotFoundException 問題，方法是在競爭狀態下新增第二次嘗試讀取資料的動作。(I43b3fb、b/337870543)。
• 為 ReplaceFileCorruptionHandler 定義預設建構函式，以便用於常見的程式碼用途。(I795b05、b/358138957)。

1.1 版本

1.1.6 版

2025 年 5 月 7 日

發布 androidx.datastore:datastore-*:1.1.6。1.1.6 版包含這些修訂項目。

修正錯誤

• 解決 Gradle 中繼資料在 1.1.5 版本中損毀的問題。這個問題是因為新的 AGP KMP 外掛程式 DSL 發生錯誤，導致系統無法自動納入所有目標平台的中繼資料。這個錯誤會導致部分 DataStore Android 方法不再顯示在用戶端版本中。修正方式是在 build.gradle 中使用較舊的 android DSL，而非 androidLibrary。(7801abf)

1.1.5 版

2025 年 4 月 23 日

發布 androidx.datastore:datastore-*:1.1.5。1.1.5 版包含這些修訂項目。

修正錯誤

• 為減少 PreferencesDataStore 中的 CorruptionException 問題，預設儲存空間已從 OkioStorage 變更為 FileStorage。這項變更是透過導入 PreferencesFileSerializer 實施。b/346197747

1.1.4 版

2025 年 3 月 26 日

發布 androidx.datastore:datastore-*:1.1.4。1.1.4 版包含這些修訂版本。

修正錯誤

• 將預設儲存空間從 OkioStorage 替換為 FileStorage，藉由減少 CorruptionException 來提高穩定性。(I71181、b/346197747)

1.1.3 版本

2025 年 2 月 26 日

發布 androidx.datastore:datastore-*:1.1.3。1.1.3 版包含這些修訂項目。

修正錯誤

• 解決應用程式啟動時在 OkioStorage 中遇到的 FileNotFoundException 問題。如果初始檔案讀取嘗試失敗，系統會再次嘗試，以防檔案在初始讀取期間由其他程序建立，導致競爭狀態發生。(I43b3f、b/337870543)。

1.1.2 版本

2025 年 1 月 15 日

發布 androidx.datastore:datastore-*:1.1.2。1.1.2 版包含這些修訂項目。

修正錯誤

• 將暖讀延遲時間 (DataStore.data.first()) 縮短 8 倍。(22b8a40)。
• ReplaceFileCorruptionHandler 可透過 KMP 通用程式碼建立。(7632e839)。

1.1.1 版

2024 年 5 月 1 日

發布 androidx.datastore:datastore-*:1.1.1。1.1.1 版包含這些修訂項目。

修正錯誤

• 在極端情況下，當多個 DataStore 例項嘗試透過檔案鎖定功能從不同程序寫入時，緩解 Linux 系統的「Resource deadlock would occur」錯誤的誤報。

1.1.0 版本

2024 年 4 月 17 日

發布 androidx.datastore:datastore-*:1.1.0。1.1.0 版包含這些修訂版本。

自 1.0.0 版以來的重大異動

如需更多資訊，請參閱 1.1.0 的 Alpha 版和 Beta 版版本資訊。1.1.0 的部分重要更新如下：

• DataStore 現已支援多個程序存取同一個檔案，並支援跨程序的可觀察性。
• 新的儲存空間介面可讓您自訂資料模型的儲存或序列化方式。
• 您現在可以在 Kotlin Multiplatform 專案中使用 DataStore。

1.1.0-rc01 版本

2024 年 4 月 3 日

發布 androidx.datastore:datastore-*:1.1.0-rc01。1.1.0-rc01 版包含這些修訂版本。

修正錯誤

• 修正效能降級的問題，當新資料與舊資料相同時，updateData 呼叫不會對磁碟寫入作業進行最佳化 (d64cfb5)
• 修正競爭狀況，即 MultiProcess DataStore 可能在初始化期間遺漏無效項目。((b/326141553)、(094c2dd))

1.1.0-beta02 版

2024 年 3 月 6 日

發布 androidx.datastore:datastore-*:1.1.0-beta02。1.1.0-beta02 版包含這些修訂項目。

修正錯誤

• DataStore 的效能改善功能只會在觀察到更新通知時收集更新通知。(b/267792241)
  • 請注意，如果您使用協同程式測試程式庫，這項變更可能會在測試中觸發 UncompletedCoroutinesError。請務必在測試中初始化 DataStore 時傳遞 TestScope.backgroundScope，以免發生這個問題。
• 修正在同一例項上巢狀 updateData 呼叫會發生死結的問題。(b/241760537)。
• 如果在遷移期間無法刪除 SharedPreferences，DataStore 不會再擲回 IOExceptions。(b/195553816)
• 修正在非 Android JVM 環境中，updateData 期間檔案重新命名失敗的問題。(b/203087070)
• 修正 DataStore 初始化後未處理 CorruptionException 的問題。(b/289582516)

1.1.0-beta01 版本

2024 年 1 月 10 日

androidx.datastore:datastore-*:1.1.0-beta01 自 1.1.0-alpha07起沒有變更。1.1.0-beta01 版本包含以下修訂項目。

1.1.0-alpha07 版本

2023 年 11 月 29 日

發布 androidx.datastore:datastore-*:1.1.0-alpha07。查看 1.1.0-alpha07 版的修訂項。

API 變更

• MultiProcessDataStoreFactory 方法不再是實驗性質，@ExperimentalMultiProcessDataStore 註解已完全移除。(Ieee54、I8e607)

修正錯誤

• 將 @ExperimentalMultiProcessDataStore 註解移除功能推送至 1.1.0-alpha07。(I8e607)

1.1.0-alpha06 版本

2023 年 11 月 1 日

發布 androidx.datastore:datastore-*:1.1.0-alpha06。查看 1.1.0-alpha06 版的修訂項。

API 變更

• createSingleProcessCoordinator 工廠方法現在會接收檔案路徑 (String、java.io.File 和 okio.Path)，以便與 createMultiProcessCoordinator 保持一致。(I211c8、b/305755935)。

1.1.0-alpha05 版本

2023 年 9 月 6 日

發布 androidx.datastore:datastore-*:1.1.0-alpha05。查看 1.1.0-alpha05 版的修訂項。

API 變更

• Datastore FileStorage 現已公開，因此用戶端可以提供自訂參數。(Icb985)
• 變更 OkioStorage 建構函式，讓其接受 InterProcessCoordinator，以便在 Android 上搭配 MultiProcessCoordinator 使用。(Iecea3)。

修正錯誤

• 修正 MultiProcessCoordinator 無法監控同一個目錄中的多個檔案。
• 修正檔案路徑未經過標準化處理時，無法偵測重複檔案的問題。
• 修正 RxDataStore#isDisposed 傳回的錯誤值。
• 修正 datstore-preferences-core 構件缺少 ProGuard 設定的問題。

1.1.0-alpha04 版本

2023 年 4 月 5 日

發布 androidx.datastore:datastore-*:1.1.0-alpha04。1.1.0-alpha04 版包含此連結所列的修訂項目。

修正錯誤

• 改善內部實作方式，避免 DataStore 的資料流在更新後可能會發出較舊值的競爭狀態。

1.1.0-alpha03 版本

2023 年 3 月 24 日

發布 androidx.datastore:datastore-*:1.1.0-alpha03。

修正錯誤

• 從 Maven 構件中移除依附元件限制，以解決 Kotlin 原生目標中的建構問題 (b/274786186、KT-57531)。

1.1.0-alpha02 版本

2023 年 3 月 22 日

發布 androidx.datastore:datastore-*:1.1.0-alpha02。查看 1.1.0-alpha02 版的修訂項。

附註

請注意，這個版本包含重要的內部重構，可合併單一程序和多程序 DataStore 實作項目。請留意可能發生的非預期行為變更 (例如更新通知的時間)。您可以使用問題追蹤工具元件回報這類變更。

新功能

• 您現在可以在 KMM 專案中使用 DataStore。請注意，DataStore 的非 Android 目標仍處於實驗階段，但我們決定合併版本，方便開發人員試用。
• 多進程功能已從 androidx.datastore.multiprocess 移至 androidx.datastore.core。
• 在 androidx.datastore.core.MultiProcessDataStoreFactory 中新增工廠方法，使用 Storage 物件建立 DataStore 例項，用於檔案作業。
• 新增介面 InterProcessCoordinator，協助多個 DataStore 例項在不同程序間進行通訊。請注意，InterProcessCoordinator 的多程序實作功能僅適用於 Android。

API 變更

• 在 datastore-core 介面中將 InterProcessCoordinator 新增至 StorageConnection (I555bb)
• 變更 datastore-core MultiProcessDataStoreFactory 中的 API 以使用儲存空間。(Iac02f)
• 將 datastore-multiprocess 中的公用 API 移至 datastore-core (I76d7c)
• 從 datastore-preferences-core 公開 PreferencesSerializer (I4b788)
• 新增 @JvmDefaultWithCompatibility 註解 (I8f206)

1.1.0-alpha01 版本

2022 年 11 月 9 日

發布 androidx.datastore:datastore-*:1.1.0-alpha01。1.1.0-alpha01 版包含以下修訂項目。

新功能

• 支援多程序用途，保證在不同程序 DataStore 執行個體之間的資料一致性。新增 MultiProcessDataStoreFactory#create 以建立此類 DataStore 例項。
• 推出新的儲存介面，從而允許退出 Datastore 的基礎儲存機制。針對 java.io 和 okio 提供實作功能。DataStore 工廠的新方法可接受這個儲存介面物件。

API 變更

• 變更 datastore-core MultiProcessDataStoreFactory 中的 API 以使用儲存空間。(Iac02f)
• 將 datastore-multiprocess 中的公用 API 移至 datastore-core (I76d7c)
• 從 datastore-preferences-core 公開 PreferencesSerializer (I4b788)

1.0.0 版本

1.0.0 版本

2021 年 8 月 4 日

androidx.datastore:datastore-*:1.0.0 發布。1.0.0 版包含此連結所列的修訂項目。

1.0.0 的主要功能

Jetpack DataStore 是一項資料儲存解決方案，可讓您使用通訊協定緩衝區儲存鍵/值組合或已輸入的物件。DataStore 使用 Kotlin 協同程式和「流程」，以非同步、一致且交易方式儲存資料。

1.0.0-rc02 版

2021 年 7 月 21 日

發布 androidx.datastore:datastore-*:1.0.0-rc02。查看 1.0.0-rc02 版的修訂項。

修正錯誤

• 清楚說明沒有索引鍵時不會執行 SharedPreferencesMigration。(Icfa32、b/192824325)
• 修正根據 MIGRATE_ALL_KEYS 建構的 SharedPreferencesMigration 時，如果要求的索引鍵還不存在，就會擲回例外狀況。(Ie318a、b/192824325)

1.0.0-rc01 版

2021 年 6 月 30 日

androidx.datastore:datastore-*:1.0.0-rc01 發布。1.0.0-rc01 版包含以下修訂項目。

修正錯誤

• 修正不慎在最終 jar 檔案中加入 .java 檔案的錯誤。(I65d96、b/188985637)

1.0.0-beta02 版

2021 年 6 月 16 日

androidx.datastore:datastore-*:1.0.0-beta02 發布。查看 1.0.0-beta02 版的修訂項。

修正錯誤

• 修正 ClassVerificationFailure (b/187450483)

1.0.0-beta01　版

2021 年 4 月 21 日

androidx.datastore:datastore-*:1.0.0-beta01 發布。1.0.0-beta01 版包含此連結所列的修訂項目。

API 變更

• 移除僅限 kotlin 的 JVM 超載方法 (I2adc7)

修正錯誤

• 已修正 DataStore 委派可能導致結構定義外洩的錯誤 (Ie96fc、b/184415662)

1.0.0-alpha08 版本

2021 年 3 月 10 日

androidx.datastore:datastore-*:1.0.0-alpha08 發布。1.0.0-alpha08 版包含此連結所列的修訂項目。

API 變更

• 您現在可以新增根據 dataStore 和 preferencesDataStore 資源委派結構定義的遷移作業。(I4ef69、b/173726702)
• 新增輔助函式，如果已不再使用 DataStore 委派或 context.createDataStore，即可取得檔案名稱 (I60f9a)
• 序列化程式 writeTo 和 readFrom 現已暫停。如果您實作了序列化程式，則必須更新函式才能暫停函式。(I1e58e)
• 已為 RxDataStore 使用者新增資源委派。(Ied768、b/173726702)

修正錯誤

• 強制限制實驗 API 的公開使用行為 (I6aa29、b/174531520)

1.0.0-alpha07 版本

2021 年 2 月 24 日

androidx.datastore:datastore-*:1.0.0-alpha07 發布。查看 1.0.0-alpha07 版的修訂項。

API 變更

• Context.createDataStore 的擴充功能函式已移除，並替換為 globalDataStore 資源委派。請在 kotlin 檔案中的頂層呼叫 globalDataStore 一次。例如：

  val Context.myDataStore by dataStore(...)
  

  請將此項目置於 Kotlin 檔案的頂層，這樣就只有一個執行個體。(I57215、b/173726702)

• RxDataStore 函式現在屬於 RxDataStore 類別，而非 DataStore 中的擴充功能函式。(Idccdb、b/177691248)

• 如果您想要將 EncryptedSharedPreferences (或直接啟動 SharedPreferences) 遷移至 DataStore，現在可以使用可讓您插入 SharedPreferences 的新 SharedPreferencesMigration 建構函式來完成這項作業。(I8e04e、b/177278510)

修正錯誤

• 如果同一個檔案有多個有效的 DataStore，則 DataStore 現在會擲回例外狀況。如果您並非以單例模式管理 DataStore，或不確定某個檔案沒有兩個 DataStore 執行個體同時處於有效狀態，那麼在讀取或寫入 DataStore 時，可能會看到例外狀況。只要以單例模式管理 DataStore 即可修正此問題。(Ib43f4、b/177691248)
• 修正取消呼叫端範圍時的取消行為。(I2c7b3)

1.0.0-alpha06 版本

2021 年 1 月 13 日

androidx.datastore:datastore-*:1.0.0-alpha06 發布。1.0.0-alpha06 版本包含以下修訂項目。

新功能

• 已為 DataStore 新增 RxJava 包裝函式。datastore-rxjava2/3 構件包含核心 DataStore API (RxDataStore、RxDataStoreBuilder 和 RxDataMigration) 的包裝函式。datastore-preferences-rxjava2/3 構件包含建構偏好設定 DataStore 的建構工具。

API 變更

• 隱藏 CorruptionHandler 介面。由於 DataStore 工廠只接受 ReplaceFileCorruptionHandler，因此不對外公開。(I0b3b3、b/176032264)
• preferencesKey<T>(name: String): Key<T> 方法已移除，並替換成各個支援類型的專屬方法，例如：preferencesKey<Int>("int")現為 intPreferencesKey("int")。(Ibcfac、b/170311106)

修正錯誤

• 修正 DataStoreFactory 的說明文件，原文件中遺漏 DataStore 檔案是在「datastore/」子目錄中建立的資訊。(Ica222)

1.0.0-alpha05 版本

2020 年 12 月 2 日

androidx.datastore:datastore-*:1.0.0-alpha05 發布。1.0.0-alpha05 版本包含以下修訂項目。

修正錯誤

• 針對 DataStore 的並行寫入作業新增更詳盡的說明文件和例外狀況。(Ia98a2、b/173522155、b/173726702)
• 我們現在允許 (但不要求) 關閉傳遞至 Serializer.writeTo() 的 OutputStream。(I5c9bf、b/173037611)

1.0.0-alpha04 版本

2020 年 11 月 17 日

androidx.datastore:datastore-*:1.0.0-alpha04 發布。查看 1.0.0-alpha04 版的修訂項。

修正錯誤

• 已修正導致偏好設定 DataStore 1.0.0-alpha03 發生以下異常終止狀況的包裝問題：java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences
  • 異常終止的原報告位置：b/173036843
  • (I4712d、b/173036843)

1.0.0-alpha03 版本

2020 年 11 月 11 日

發布 androidx.datastore:datastore-*:1.0.0-alpha03。查看 1.0.0-alpha03 版的修訂項。

新功能

• 偏好設定現在支援雙精度值 (如果需要比浮點值更高的精確度，這會非常實用。(I5be8f、b/169471808)

API 變更

• 為　Datastore 建立純 Kotlin 依附元件，以加快編譯速度。androidx.datastore:datastore-core 包含僅限核心 kotlin 的　API，而 androidx.datastore:datastore 則包含需要 Android 的 API (包括 SharedPreferencesMigration 和 Context.createDataStore 建構函式)。(I42d75、b/168512698)
• 分割偏好設定資料存放區，加快 Kotlin 編譯作業 (Ia3c19)

• 如果磁碟上沒有資料，序列化程式現在會要求新的資源以使用預設值。這有助於輕鬆導入自訂序列化程式，讓使用者不必特別設定空白的輸入串流 (空白的輸入串流不會以 JSON 剖析)。

  • 此外，系統現在也會檢查確認提供給　writeTo() 的輸出串流未關閉，若關閉則擲回例外狀況 (I16e29)

• 將 SharedPreferencesView 的建構函式設為內部函式。此項目原本為公開性質，允許測試。測試時應改為建立 SharedPreferencesMigration 並對此進行測試。(I93891)

修正錯誤

• DataStoreFactory 和 PreferenceDataStoreFactory 上的 produceFile 參數現是清單中的最後一個參數，可讓您使用 kotlin 結尾 lambda 語法。(Ibe7f1、b/169425442)
• 遵循 kotlin 新的明確 API 要求 (I5ae1e)

已知問題

• 偏好設定 Datastore 發生 java.lang.NoClassDefFoundError 異常終止。(b/173036843)

1.0.0-alpha02 版

2020 年 10 月 14 日

發布 androidx.datastore:datastore-core:1.0.0-alpha02 和 androidx.datastore:datastore-preferences:1.0.0-alpha02。1.0.0-alpha02 版包含此連結所列的修訂項目。

修正錯誤

• 在 datastore-core 中新增了保護措施以防止發生變化。對於 DataStore 非 proto/非偏好設定類型的使用者而言，變化會打斷 DataStore 的使用 (I6aa84)
• 已將 toString 方法新增至 Preferences.kt，輕鬆對目前狀態進行偵錯 (I96006)
• 已新增例外狀況，避免 DataStore.Preferences 遭到濫用 (I1134d)
• 已修正會導致應用程式啟動時異常終止的錯誤 (I69237、b/168580258)

1.0.0-alpha01 版

2020 年 9 月 2 日

發布 androidx.datastore:datastore-core:1.0.0-alpha01 和 androidx.datastore:datastore-preferences:1.0.0-alpha01。1.0.0-alpha01 版包含此連結所列的修訂項目。

新功能

Jetpack DataStore 是全新的進階資料儲存解決方案，旨在取代 SharedPreferences。DataStore 以 Kotlin 協同程式和 Flow 為基礎而設計，可以提供兩種不同的實作方式：

• Proto DataStore 可讓您儲存已輸入的物件 (由通訊協定緩衝區支援)
• 用於儲存鍵/值組合的偏好設定 DataStore

資料會以非同步、一致且交易方式儲存，克服 SharedPreferences 的大多數缺點。