DataStore

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

最新更新	稳定版	候选版本	Beta 版本	Alpha 版本
2024年5月1日	1.1.1	-	-	-

声明依赖项

要添加对 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.1"

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

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

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

Kotlin

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

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

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

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

Proto DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

反馈

您的反馈有助于改进 Jetpack。如果您发现新的问题或有改进此库的想法，请告诉我们。在创建新的问题之前，请查看此库中现有问题。您可以通过点击星号按钮为现有问题投票。

创建新的问题

查看问题跟踪器文档以了解更多信息。

1.1 版

1.1.1 版

2024年5月1日

androidx.datastore:datastore-*:1.1.1 已发布。1.1.1 版包含这些提交。

错误修复

在极端情况下，多个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 多平台项目中使用 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)
使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 方法不再是实验性的。@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，以便它可以与 MultiProcessCoordinator 一起在 Android 上使用。（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 Native Targets 中的构建问题（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 版本

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 版本包含这些提交。

错误修复

阐明如果没有任何键，则 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 版本包含这些提交。

错误修复

修复了意外将 .java 文件添加到最终 jar 文件中的错误（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，您现在可以使用新的 SharedPreferencesMigration 构造函数来注入 SharedPreferences。(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 工件包含一个构建器，用于构建 Preferences DataStore。

API 变更

隐藏 CorruptionHandler 接口。它没有理由是公开的，因为 DataStore 工厂只接受 ReplaceFileCorruptionHandler。(I0b3b3, b/176032264)
preferencesKey<T>(name: String): Key<T> 方法已被移除，并替换为针对每种支持类型的方法，例如 preferencesKey<Int>("int") 现在是 intPreferencesKey("int")(Ibcfac, b/170311106)

错误修复

修复了 DataStoreFactory 的文档，该文档遗漏了数据存储文件是在“datastore/”子目录中创建的事实。(Ica222)

1.0.0-alpha05 版本

2020 年 12 月 2 日

androidx.datastore:datastore-*:1.0.0-alpha05 已发布。1.0.0-alpha05 版本包含这些提交。

错误修复

改进了有关数据存储并发写入的文档和异常。(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 版本包含这些提交。

错误修复

修复了导致 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)

错误修复

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 版本包含这些提交。

错误修复

在 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 协程和 Flow，提供两种不同的实现：

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

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