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，以便它可以在 Android 上与 MultiProcessCoordinator 一起使用。（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 目标中的构建问题（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 包含这些提交。

错误修复

  • 阐明如果不存在键，则 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 包含这些提交。

错误修复

版本 1.0.0-beta02

2021 年 6 月 16 日

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

错误修复

版本 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)
  • Serializer 的 writeTo 和 readFrom 现在是挂起的。如果您已实现 Serializer，则需要将您的函数更新为挂起函数。（I1e58e)

  • 为 RxDataStore 用户添加了属性委托。 (Ied768, b/173726702)

错误修复

版本 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 文件是在“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 包含以下提交。

错误修复

  • 修复了导致 Preference Datastore 1.0.0-alpha03 中出现以下崩溃的打包问题： java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

版本 1.0.0-alpha03

2020年11月11日

androidx.datastore:datastore-*:1.0.0-alpha03 已发布。 版本 1.0.0-alpha03 包含以下提交。

新功能

  • Preferences 现在支持双精度值（如果您需要比浮点数更高的精度，这很有用） (I5be8f, b/169471808)

API 更改

  • 创建了一个纯 Kotlin 依赖项以供 datastore 使用，以加快编译速度。 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)

已知问题

  • 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 的大多数缺点。