DataStore
最近更新時間 | 穩定版 | 候選版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
2022 年 11 月 9 日 | 1.0.0 | - | - | 1.1.0-alpha01 |
宣告依附元件
如果要為 DataStore 新增依附元件,您必須將 Google Maven 存放區新增至專案。詳情請參閱 Google 的 Maven 存放區。
DataStore 有兩種實作方式:偏好設定和 Proto。選擇其中一項。您還可以在任一實作方式中新增無 Android 依附元件。
在應用程式或模組的 build.gradle
檔案中,新增您需要實作的依附元件:
Preferences DataStore
Groovy
// Preferences DataStore (SharedPreferences like APIs) dependencies { implementation "androidx.datastore:datastore-preferences:1.0.0" // optional - RxJava2 support implementation "androidx.datastore:datastore-preferences-rxjava2:1.0.0" // optional - RxJava3 support implementation "androidx.datastore:datastore-preferences-rxjava3:1.0.0" } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation "androidx.datastore:datastore-preferences-core:1.0.0" }
Kotlin
// Preferences DataStore (SharedPreferences like APIs) dependencies { implementation("androidx.datastore:datastore-preferences:1.0.0") // optional - RxJava2 support implementation("androidx.datastore:datastore-preferences-rxjava2:1.0.0") // optional - RxJava3 support implementation("androidx.datastore:datastore-preferences-rxjava3:1.0.0") } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation("androidx.datastore:datastore-preferences-core:1.0.0") }
Proto DataStore
Groovy
// Typed DataStore (Typed API surface, such as Proto) dependencies { implementation "androidx.datastore:datastore:1.0.0" // optional - RxJava2 support implementation "androidx.datastore:datastore-rxjava2:1.0.0" // optional - RxJava3 support implementation "androidx.datastore:datastore-rxjava3:1.0.0" } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation "androidx.datastore:datastore-core:1.0.0" }
Kotlin
// Typed DataStore (Typed API surface, such as Proto) dependencies { implementation("androidx.datastore:datastore:1.0.0") // optional - RxJava2 support implementation("androidx.datastore:datastore-rxjava2:1.0.0") // optional - RxJava3 support implementation("androidx.datastore:datastore-rxjava3:1.0.0") } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation("androidx.datastore:datastore-core:1.0.0") }
意見回饋
您的意見可協助我們改善 Jetpack。發現新的問題或有改善這個程式庫的想法時,請告訴我們。建立新的問題之前,請先查看這個程式庫中的現有問題。只要按一下星號按鈕,即可投票給現有的問題。
詳情請參閱 Issue Tracker 文件。
1.1 版本
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 的大多數缺點。