此页面由 Cloud Translation API 翻译。

DataStore

以异步、一致的事务方式存储数据，克服了 SharedPreferences 的一些缺点

最近更新时间	稳定版	候选版	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 和 Guava ListenableFuture 用户友好的 API。(Iadd5e0)
现在支持在 DirectBoot 模式下使用 DataStore。如需创建要在直接启动模式下使用的存储区，必须在设备受保护存储空间中创建该存储区。您可以通过以下新的 DataStore API 实现此目的：DataStoreFactory 中的 createInDeviceProtectedStorage() 和 DataStoreDelegate 中的 deviceProtectedDataStore()。(Ib90e56)

API 变更

添加了实现 androidx.datastore.core.Serializer 接口的 PreferencesFileSerializer，以便与 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 修复

解决了 Gradle 元数据在版本 1.1.5 中损坏的问题。此问题是由新版 AGP KMP 插件 DSL 中的 bug 导致的，该 bug 会阻止自动包含所有目标平台的元数据。此 bug 会导致某些 DataStore Android 方法不再显示在客户端 build 中。修复方法涉及在 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 修复

在极端情况下，多个 DataStore 实例尝试通过撤消文件锁定从不同的进程写入时，减少了 Linux 对“将发生资源死锁”错误的误报。

版本 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 Multiplatform 项目中使用 DataStore。

版本 1.1.0-rc01

2024 年 4 月 3 日

发布了 androidx.datastore:datastore-*:1.1.0-rc01。版本 1.1.0-rc01 包含这些提交内容。

bug 修复

修复了以下性能下降问题：如果新数据与旧数据相同，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 包含这些提交内容。

bug 修复

DataStore 的性能改进功能仅在观察到更新通知时收集更新通知。(b/267792241)
- 请注意，如果您使用的是协程测试库，此更改可能会在测试中触发 UncompletedCoroutinesError。在测试中初始化 DataStore 时，请务必传递 TestScope.backgroundScope，以避免此问题。
修复了对同一实例进行嵌套 updateData 调用会导致死锁的问题。(b/241760537)
使 DataStore 在迁移期间无法删除 SharedPreferences 时不再抛出 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 方法不再是实验性 API。@ExperimentalMultiProcessDataStore 注解已被完全移除。（Ieee54、I8e607）

bug 修复

在 1.1.0-alpha07 中移除了 @ExperimentalMultiProcessDataStore 注解。(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 原生目标中的构建问题 (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 实例。
新增了存储接口，可切换 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

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）
修复了如下 bug：当请求的密钥尚不存在时，使用 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 修复

修复了以下 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 修复

修复了数据存储区委托可能会导致泄露上下文的问题（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）
如果您不再使用数据存储区委托或 context.createDataStore，请添加辅助函数以获取文件的名称 (I60f9a)
序列化器 writeTo 和 readFrom 现在处于挂起状态如果您已实现序列化器，则需要将函数更新为挂起函数。(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 文件的顶层，以便 globalDataStore 只有一个实例。（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 变更

为数据存储区创建了纯 Kotlin 依赖项，以加快编译速度。androidx.datastore:datastore-core 包含仅适用于 Kotlin 的核心 API，androidx.datastore:datastore 包含依赖 Android 的 API（包括 SharedPreferencesMigration 和 Context.createDataStore 构造函数。）（I42d75、b/168512698）
拆分 Preferences DataStore 的目标，以加快 Kotlin 编译速度 (Ia3c19)
序列化器现在需要将新的属性作为默认值，系统会在磁盘上没有任何数据时使用该值。这样可以更轻松地实现自定义序列化器，用户不必将空输入流作为特例处理（对于空输入流，无法使用 json 进行解析）。
- 此外，现在还会进行一项检查，以确认提供给 writeTo() 的输出流未关闭，以及关闭时是否会抛出异常 (I16e29)
将 SharedPreferencesView 的构造函数变为内部构造函数。为了进行测试，该构造函数最初处于公开状态。测试应改为构造一个 SharedPreferencesMigration，然后对其进行测试。(I93891)

bug 修复

DataStoreFactory 和 PreferenceDataStoreFactory 上的 produceFile 参数现在是列表中的最后一个参数，因此您可以使用 Kotlin 尾随 lambda 语法。（Ibe7f1、b/169425442）
遵循明确的 API 新要求（适用于 Kotlin）(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/非偏好类型的用户而言，突变会破坏数据存储区的使用 (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 协程和流程构建而成，提供两种不同的实现：

Proto DataStore，它允许您存储类型化的对象（由协议缓冲区提供支持）
Preferences DataStore，用于存储键值对

以异步、一致的事务方式存储数据，克服了 SharedPreferences 的大部分缺点。