DataStore
最新更新 | 稳定版 | 发布候选版 | Beta 版 | Alpha 版 |
---|---|---|---|---|
2025 年 5 月 20 日 | 1.1.7 | - | - | 1.2.0-alpha02 |
声明依赖项
要添加 DataStore 依赖项,您必须将 Google Maven 仓库添加到您的项目中。如需了解更多信息,请阅读Google 的 Maven 仓库。
DataStore 有两种实现:Preferences 和 Proto。请选择其中一种。您也可以为任一实现添加不依赖 Android 的依赖项。
在您的应用或模块的 build.gradle
文件中添加所需实现的依赖项
Preferences DataStore
Groovy
// Preferences DataStore (SharedPreferences like APIs) dependencies { implementation "androidx.datastore:datastore-preferences:1.1.7" // optional - RxJava2 support implementation "androidx.datastore:datastore-preferences-rxjava2:1.1.7" // optional - RxJava3 support implementation "androidx.datastore:datastore-preferences-rxjava3:1.1.7" } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation "androidx.datastore:datastore-preferences-core:1.1.7" }
Kotlin
// Preferences DataStore (SharedPreferences like APIs) dependencies { implementation("androidx.datastore:datastore-preferences:1.1.7") // optional - RxJava2 support implementation("androidx.datastore:datastore-preferences-rxjava2:1.1.7") // optional - RxJava3 support implementation("androidx.datastore:datastore-preferences-rxjava3:1.1.7") } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation("androidx.datastore:datastore-preferences-core:1.1.7") }
Proto DataStore
Groovy
// Typed DataStore (Typed API surface, such as Proto) dependencies { implementation "androidx.datastore:datastore:1.1.7" // optional - RxJava2 support implementation "androidx.datastore:datastore-rxjava2:1.1.7" // optional - RxJava3 support implementation "androidx.datastore:datastore-rxjava3:1.1.7" } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation "androidx.datastore:datastore-core:1.1.7" }
Kotlin
// Typed DataStore (Typed API surface, such as Proto) dependencies { implementation("androidx.datastore:datastore:1.1.7") // optional - RxJava2 support implementation("androidx.datastore:datastore-rxjava2:1.1.7") // optional - RxJava3 support implementation("androidx.datastore:datastore-rxjava3:1.1.7") } // Alternatively - use the following artifact without an Android dependency. dependencies { implementation("androidx.datastore:datastore-core:1.1.7") }
反馈
您的反馈有助于改进 Jetpack。如果您发现新问题或有改进此库的想法,请告诉我们。在创建新问题之前,请先查看此库中的现有问题。您可以通过点击星形按钮为您关注的现有问题投票。
如需了解更多信息,请参阅问题跟踪器文档。
版本 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 和 GuavaListenableFuture
用户公开友好的 API。(Iadd5e0) - 现在支持在
DirectBoot
模式下使用DataStore
。要在直接启动模式下创建数据存储,必须在设备保护存储中创建。这可以通过以下新的 DataStore API 实现:`DataStoreFactory` 中的createInDeviceProtectedStorage()
和DataStoreDelegate
中的deviceProtectedDataStore()
。(Ib90e56)
API 变更
- 添加了
PreferencesFileSerializer
,它实现了androidx.datastore.core.Serializer
接口,可与FileStorage
配合使用。(I4c71f3)
Bug 修复
- 通过在竞争条件下添加第二次尝试读取数据,解决了
OkioStorage
在启动时出现的FileNotFoundException
问题。(I43b3fb、b/337870543) - 为
ReplaceFileCorruptionHandler
定义了默认构造函数,以便通用代码使用。(I795b05、b/358138957)
版本 1.1
版本 1.1.7
2025 年 5 月 20 日
androidx.datastore:datastore-*:1.1.7
已发布。版本 1.1.7 包含这些提交。
Bug 修复
- 修复了
datastore-preferences-core
的 Android 工件中 Proguard 规则缺失的问题。(3f3f6e、b/413078297)
版本 1.1.6
2025 年 5 月 7 日
androidx.datastore:datastore-*:1.1.6
已发布。版本 1.1.6 包含这些提交。
Bug 修复
- 解决了 1.1.5 版本中 Gradle 元数据损坏的问题。此问题是由于新的 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 包含这些提交。
Bug 修复
- 为了缓解
PreferencesDataStore
中的CorruptionException
问题,默认存储已从OkioStorage
更改为FileStorage
。此更改通过引入PreferencesFileSerializer
来实现。b/346197747
版本 1.1.4
2025 年 3 月 26 日
androidx.datastore:datastore-*:1.1.4
已发布。版本 1.1.4 包含这些提交。
Bug 修复
- 将默认存储从
OkioStorage
替换为FileStorage
,以通过减少CorruptionException
来提高可靠性。(I71181、b/346197747)
版本 1.1.3
2025 年 2 月 26 日
androidx.datastore:datastore-*:1.1.3
已发布。版本 1.1.3 包含这些提交。
Bug 修复
- 解决了应用启动时
OkioStorage
中遇到的FileNotFoundException
问题。如果初始文件读取尝试失败,则会在发生竞争条件(由于文件在初始读取期间由其他进程创建)的情况下进行第二次尝试。(I43b3f、b/337870543)
版本 1.1.2
2025 年 1 月 15 日
androidx.datastore:datastore-*:1.1.2
已发布。版本 1.1.2 包含这些提交。
Bug 修复
- 将热读取延迟 (
DataStore.data.first()
) 提高 8 倍。(22b8a40) ReplaceFileCorruptionHandler
可以从 KMP 公共代码中创建。(7632e839)
版本 1.1.1
2024 年 5 月 1 日
androidx.datastore:datastore-*:1.1.1
已发布。版本 1.1.1 包含这些提交。
Bug 修复
- 缓解了 Linux 在极端情况下报告的“资源死锁”错误假警报,即当多个
DataStore
实例尝试从不同进程写入时,通过回退文件锁来解决。
版本 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 现在支持多个进程访问同一文件,并支持跨进程的可观察性。
- 新的 Storage 接口允许您自定义如何存储或序列化数据模型。
- 您现在可以在 Kotlin 多平台项目中使用 DataStore。
版本 1.1.0-rc01
2024 年 4 月 3 日
androidx.datastore:datastore-*:1.1.0-rc01
已发布。版本 1.1.0-rc01 包含这些提交。
Bug 修复
- 修复了性能下降问题,即当新数据与旧数据相同时,
updateData
调用不会优化磁盘写入(d64cfb5) - 修复了多进程
DataStore
在初始化期间可能遗漏失效通知的竞争条件。((b/326141553)、(094c2dd))
版本 1.1.0-beta02
2024 年 3 月 6 日
androidx.datastore:datastore-*:1.1.0-beta02
已发布。版本 1.1.0-beta02 包含这些提交。
Bug 修复
- DataStore 性能改进:仅当被观察时才收集更新通知。(b/267792241)
- 请注意,如果您使用 Coroutines 测试库,此更改可能会在您的测试中触发
UncompletedCoroutinesError
。请确保在测试中初始化DataStore
时传入TestScope.backgroundScope
以避免此问题。
- 请注意,如果您使用 Coroutines 测试库,此更改可能会在您的测试中触发
- 修复了同一实例上嵌套的
updateData
调用会导致死锁的问题。(b/241760537) - 修复了 DataStore 在迁移过程中删除
SharedPreferences
失败时不再抛出IOException
的问题。(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 变更
Bug 修复
- 将
@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)
Bug 修复
- 修复了
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 包含这些提交。
Bug 修复
- 改进内部实现,以避免在更新后
DataStore
的数据流可能发出旧值的竞争条件。
版本 1.1.0-alpha03
2023 年 3 月 24 日
androidx.datastore:datastore-*:1.1.0-alpha03
已发布。
Bug 修复
- 移除了 Maven 工件的依赖项约束,以解决 Kotlin Native 目标中的构建问题(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
接口中的StorageConnection
中添加InterProcessCoordinator
(I555bb) - 更改
datastore-core
中的MultiProcessDataStoreFactory
API 以使用 Storage。(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
实例。 - 新的 Storage 接口允许更换
Datastore
的底层存储机制。提供了java.io
和okio
的实现。DataStore 工厂有新的方法接受此 Storage 对象。
API 变更
- 更改
datastore-core
中的MultiProcessDataStoreFactory
API 以使用 Storage。(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 协程和 Flow 异步、一致且事务性地存储数据。
版本 1.0.0-rc02
2021 年 7 月 21 日
androidx.datastore:datastore-*:1.0.0-rc02
已发布。版本 1.0.0-rc02 包含这些提交。
Bug 修复
- 澄清如果不存在任何键,
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 包含这些提交。
Bug 修复
- 修复了 .java 文件意外添加到最终 jar 包中的错误(I65d96、b/188985637)
版本 1.0.0-beta02
2021 年 6 月 16 日
androidx.datastore:datastore-*:1.0.0-beta02
已发布。版本 1.0.0-beta02 包含这些提交。
Bug 修复
- 修复
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)
Bug 修复
- 修复了 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) Serializer
的writeTo
和readFrom
现在是挂起函数。如果您已实现 `Serializer`,则需要将您的函数更新为挂起函数。(I1e58e)- 为 RxDataStore 用户添加了属性委托。(Ied768、b/173726702)
Bug 修复
- 对实验性 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,您现在可以使用新的
SharedPreferencesMigration
构造函数,该构造函数允许您注入 SharedPreferences。(I8e04e、b/177278510)
Bug 修复
- 如果同一文件有多个活跃的 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
工件包含用于构建 Preferences DataStore 的构建器。
API 变更
- 隐藏
CorruptionHandler
接口。它没有理由公开,因为 DataStore 工厂只接受ReplaceFileCorruptionHandler
。(I0b3b3、b/176032264) preferencesKey<T>(name: String): Key<T>
方法已被移除,并替换为每种支持类型特定的方法,例如preferencesKey<Int>("int")
现在是intPreferencesKey("int")
(Ibcfac、b/170311106)
Bug 修复
- 修复了
DataStoreFactory
文档中遗漏了 datastore 文件在“datastore/”子目录中创建的事实。(Ica222)
版本 1.0.0-alpha05
2020 年 12 月 2 日
androidx.datastore:datastore-*:1.0.0-alpha05
已发布。版本 1.0.0-alpha05 包含这些提交。
Bug 修复
- 增加了关于来自数据存储的并发写入的更好文档和异常。(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 包含这些提交。
Bug 修复
- 修复了一个打包问题,该问题导致 Preference 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 包含这些提交。
新功能
- Preferences 现在支持双精度浮点值(如果您需要比浮点数更高的精度,这会很有用)(I5be8f、b/169471808)
API 变更
- 为 datastore 创建了纯 Kotlin 依赖项,以加快编译速度。
androidx.datastore:datastore-core
包含核心仅 Kotlin API,androidx.datastore:datastore
包含依赖于 Android 的 API(包括SharedPreferencesMigration
和Context.createDataStore
构造函数)。(I42d75、b/168512698) - 拆分 preferences data store 的目标以加快 Kotlin 编译(Ia3c19)
序列化器现在需要一个新属性来指定磁盘上没有数据时将使用的默认值。这使得实现自定义序列化器变得更容易,因此用户不必对空输入流进行特殊处理(空输入流无法用 json 解析)。
- 此外,现在有一个检查,以确认提供给
writeTo()
的输出流未关闭,如果已关闭,则会抛出异常(I16e29)
- 此外,现在有一个检查,以确认提供给
将
SharedPreferencesView
的构造函数设置为内部。它最初是公开的,以允许测试。测试应改为构造SharedPreferencesMigration
并对其进行测试。(I93891)
Bug 修复
DataStoreFactory
和PreferenceDataStoreFactory
上的produceFile
参数现在是列表中的最后一个参数,因此它允许您使用 Kotlin 尾随 lambda 语法。(Ibe7f1、b/169425442)- 遵循 Kotlin 的新显式 API 要求(I5ae1e)
已知问题
- Preference 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 包含这些提交。
Bug 修复
- 在
datastore-core
中添加了针对变异的保护。变异会破坏使用非 proto/非 preferences 类型的 datastore 的用户对 datastore 的使用。(I6aa84) - 在
Preferences.kt
中添加了toString
方法,以便轻松调试当前状态。(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,允许您存储类型化对象(由协议缓冲区支持)
- Preferences DataStore,存储键值对
数据以异步、一致和事务性的方式存储,克服了 SharedPreferences 的大部分缺点。