DataStore | Jetpack | Android Developers

此页面由 Cloud Translation API 翻译。

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 包含这些提交内容。

bug 修复

缓解了针对“会出现资源死锁”的 Linux 误报在极端情况下，多个 DataStore 实例会尝试通过退避文件锁来从不同进程写入数据。

版本 1.1.0

2024 年 4 月 17 日

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

自 1.0.0 版以来的重要变更

如需了解详情，请参阅 Alpha 版和 Beta 版 1.1.0 的版本说明。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)
修复了 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) <ph type="x-smartling-placeholder">
- 请注意，如果您使用的是协程测试库，此更改可能会在测试中触发 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）

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 工厂方法现在会收到与 createMultiProcessCoordinator 一致的文件路径（String、java.io.File 和 okio.Path）。（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 的大部分缺点。