хранилище данных

Храните данные асинхронно, последовательно и транзакционно, преодолевая некоторые недостатки SharedPreferences.
Последнее обновление Стабильный выпуск Кандидат на выпуск Бета-версия Альфа-релиз
1 мая 2024 г. 1.1.1 - - -

Объявление зависимостей

Чтобы добавить зависимость от DataStore, необходимо добавить в свой проект репозиторий Google Maven. Для получения дополнительной информации прочтите репозиторий Google Maven .

Существует две реализации DataStore: Preferences и Proto . Выбирайте тот или иной вариант. Вы также можете добавить зависимости без Android к любой реализации.

Добавьте зависимости для нужной вам реализации в файл build.gradle вашего приложения или модуля:

Настройки хранилища данных

классный 

    // 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"
    }

Котлин 

    // 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")
    }

Прото хранилище данных

классный 

    // 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"
    }

Котлин

    // 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

1 мая 2024 г.

Выпущен androidx.datastore:datastore-*:1.1.1 . Версия 1.1.1 содержит эти коммиты .

Исправления ошибок

  • Устранена ложная тревога Linux при возникновении ошибки «Возможна блокировка ресурса» в крайнем случае, когда несколько экземпляров DataStore пытаются выполнить запись из разных процессов, отменив блокировку файла.

Версия 1.1.0

17 апреля 2024 г.

Выпущен androidx.datastore:datastore-*:1.1.0 . Версия 1.1.0 содержит эти коммиты .

Основные изменения с момента выпуска 1.0.0

Пожалуйста, просмотрите примечания к выпуску альфа- и бета-версий 1.1.0 для получения дополнительной информации. Некоторые из основных обновлений версии 1.1.0:

  • DataStore теперь поддерживает несколько процессов, обращающихся к одному и тому же файлу, а также возможность наблюдения за разными процессами.
  • Новый интерфейс хранилища позволяет вам настроить способ хранения или сериализации ваших моделей данных.
  • Теперь вы можете использовать DataStore в мультиплатформенных проектах Kotlin.

Версия 1.1.0-rc01

3 апреля 2024 г.

Выпущен androidx.datastore:datastore-*:1.1.0-rc01 . Версия 1.1.0-rc01 содержит эти коммиты .

Исправления ошибок

  • Исправлено снижение производительности, из-за которого вызовы updateData не оптимизировались при записи на диск, если новые данные совпадают со старыми ( d64cfb5 ).
  • Исправлена ​​ситуация состязания, из-за которой MultiProcess DataStore мог пропустить недействительность во время инициализации. (( б/326141553 ),( 094c2dd ))

Версия 1.1.0-beta02

6 марта 2024 г.

Выпущен androidx.datastore:datastore-*:1.1.0-beta02 . Версия 1.1.0-beta02 содержит эти коммиты .

Исправления ошибок

  • Улучшение производительности в DataStore собирает уведомления об обновлениях только тогда, когда оно наблюдается. ( б / 267792241 )
    • Обратите внимание, что это изменение может вызвать ошибку UncompletedCoroutinesError в ваших тестах, если вы используете библиотеку тестирования Coroutines. Обязательно передайте TestScope.backgroundScope при инициализации DataStore в своих тестах, чтобы избежать этой проблемы.
  • Исправлена ​​проблема, из-за которой вложенные вызовы updateData в одном и том же экземпляре приводили в тупик. ( б/241760537 )
  • DataStore больше не генерирует исключения IOExceptions если не удается удалить SharedPreferences во время миграции. ( р/195553816 )
  • Исправлена ​​проблема, из-за которой не удавалось переименовать файл во время updateData в средах JVM, отличных от Android. ( б / 203087070 )
  • Исправлена ​​проблема, из-за которой CorruptionException не обрабатывалось после инициализации DataStore . ( б/289582516 )

Версия 1.1.0-бета01

10 января 2024 г.

androidx.datastore:datastore-*:1.1.0-beta01 выпущен без изменений с версии 1.1.0-alpha07 . Версия 1.1.0-beta01 содержит эти коммиты.

Версия 1.1.0-альфа07

29 ноября 2023 г.

Выпущен 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-альфа06

1 ноября 2023 г.

Выпущен androidx.datastore:datastore-*:1.1.0-alpha06 . Версия 1.1.0-alpha06 содержит эти коммиты.

Изменения API

  • Фабричный метод createSingleProcessCoordinator теперь получает путь к файлу ( String , java.io.File и okio.Path ), чтобы соответствовать методу createMultiProcessCoordinator . ( I211c8 , б/305755935 )

Версия 1.1.0-альфа05

6 сентября 2023 г.

Выпущен androidx.datastore:datastore-*:1.1.0-alpha05 . Версия 1.1.0-alpha05 содержит эти коммиты.

Изменения API

  • Datastore FileStorage теперь общедоступен, поэтому клиенты могут предоставлять собственные параметры. ( Icb985 )
  • Изменен конструктор OkioStorage , чтобы он принимал InterProcessCoordinator , чтобы его можно было использовать на Android с MultiProcessCoordinator . ( Иецея3 )

Исправления ошибок

  • Исправлена ​​ошибка, из-за которой MultiProcessCoordinator не мог отслеживать несколько файлов в одном каталоге.
  • Исправлена ​​ошибка, из-за которой невозможно обнаружить дубликаты файлов, если пути к файлам не нормализованы.
  • Исправьте неправильные значения, возвращаемые из RxDataStore#isDisposed .
  • Исправлена ​​отсутствующая конфигурация proguard для артефакта datstore-preferences-core .

Версия 1.1.0-альфа04

5 апреля 2023 г.

Выпущен androidx.datastore:datastore-*:1.1.0-alpha04 . Версия 1.1.0-alpha04 содержит эти коммиты.

Исправления ошибок

  • Улучшите внутреннюю реализацию, чтобы избежать состояния гонки, при котором поток данных DataStore может выдать более старое значение после обновления.

Версия 1.1.0-альфа03

24 марта 2023 г.

Выпущен androidx.datastore:datastore-*:1.1.0-alpha03 .

Исправления ошибок

  • Удалены ограничения зависимостей из артефактов Maven для обхода проблемы сборки в Kotlin Native Targets ( b/274786186 , KT-57531 ).

Версия 1.1.0-альфа02

22 марта 2023 г.

Выпущен androidx.datastore:datastore-*:1.1.0-alpha02 . Версия 1.1.0-alpha02 содержит эти коммиты.

Примечание

Обратите внимание, что эта версия включает важный внутренний рефакторинг, который объединяет реализации однопроцессного и многопроцессного хранилища данных. Пожалуйста, следите за возможными непреднамеренными изменениями поведения (например, временем уведомлений об обновлениях). Вы можете использовать компонент отслеживания проблем, чтобы сообщать о таких изменениях.

Новые возможности

  • Теперь вы можете использовать DataStore в проектах KMM . Обратите внимание, что цели DataStore, отличные от Android, все еще являются экспериментальными, но мы решили объединить версии, чтобы разработчикам было легче их опробовать.
  • Функции нескольких процессов перенесены из androidx.datastore.multiprocess в androidx.datastore.core .
  • Добавьте новый фабричный метод в androidx.datastore.core.MultiProcessDataStoreFactory для создания экземпляров DataStore с объектами Storage для файловых операций.
  • Добавьте новый интерфейс InterProcessCoordinator , который помогает нескольким экземплярам DataStore взаимодействовать между процессами. Обратите внимание, что многопроцессная реализация InterProcessCoordinator доступна только на Android.

Изменения API

  • Добавьте InterProcessCoordinator в StorageConnection в интерфейсе ядра хранилища данных ( I555bb ).
  • Измените API в MultiProcessDataStoreFactory ядра хранилища данных, чтобы использовать Storage. ( Iac02f )
  • Переместить общедоступные API из datastore-multiprocess в datastore-core ( I76d7c ).
  • Открытый PreferencesSerializer из datastore-preferences-core ( I4b788 )
  • Добавление аннотации @JvmDefaultWithCompatibility ( I8f206 )

Версия 1.1.0-альфа01

9 ноября 2022 г.

Выпущен androidx.datastore:datastore-*:1.1.0-alpha01 . Версия 1.1.0-alpha01 содержит эти коммиты.

Новые возможности

  • Поддержка вариантов использования нескольких процессов, при которых гарантируется согласованность данных между экземплярами DataStore во всех процессах. Добавьте MultiProcessDataStoreFactory#create для создания таких экземпляров DataStore .
  • Новый интерфейс хранилища, который позволяет отключить базовый механизм хранения данных для Datastore . Предоставляются реализации для java.io и okio. Фабрики DataStore имеют новые методы, которые принимают этот объект Storage.

Изменения API

  • Измените API в MultiProcessDataStoreFactory ядра хранилища данных, чтобы использовать Storage. ( Iac02f )
  • Переместить общедоступные API из datastore-multiprocess в datastore-core ( I76d7c ).
  • Открытый PreferencesSerializer из datastore-preferences-core ( I4b788 )

Версия 1.0.0

Версия 1.0.0

4 августа 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0 . Версия 1.0.0 содержит эти коммиты.

Основные особенности версии 1.0.0

Jetpack DataStore — это решение для хранения данных, которое позволяет хранить пары ключ-значение или типизированные объекты с помощью буферов протокола. DataStore использует сопрограммы Kotlin и Flow для асинхронного, последовательного и транзакционного хранения данных.

Версия 1.0.0-rc02

21 июля 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-rc02 . Версия 1.0.0-rc02 содержит эти коммиты.

Исправления ошибок

  • Уточните, что SharedPreferencesMigration не запускается, если нет ключей. ( Icfa32 , б/192824325 )
  • Исправлена ​​ошибка, из-за которой SharedPreferencesMigration , созданная с помощью MIGRATE_ALL_KEYS выдавала исключение, если запрошенный ключ еще не существует. ( Ие318а , б/192824325 )

Версия 1.0.0-rc01

30 июня 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-rc01 . Версия 1.0.0-rc01 содержит эти коммиты.

Исправления ошибок

  • Исправлена ​​ошибка, из-за которой файл .java был случайно добавлен в финальный jar-файл ( I65d96 , b/188985637 ).

Версия 1.0.0-бета02

16 июня 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-beta02 . Версия 1.0.0-beta02 содержит эти коммиты.

Исправления ошибок

  • Исправить ClassVerificationFailure ( b/187450483 )

Версия 1.0.0-бета01

21 апреля 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-beta01 . Версия 1.0.0-beta01 содержит эти коммиты.

Изменения API

  • Удалить перегрузки JVM для методов только Kotlin ( I2adc7 )

Исправления ошибок

  • Исправлена ​​ошибка, из-за которой делегаты хранилища данных могли привести к утечке контекстов ( Ie96fc , b/184415662 ).

Версия 1.0.0-альфа08

10 марта 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-alpha08 . Версия 1.0.0-alpha08 содержит эти коммиты.

Изменения API

  • Теперь вы можете добавить миграцию, которая зависит от контекста, к делегату свойств dataStore и preferencesDataStore . ( I4ef69 , б/173726702 )
  • Добавляет вспомогательные функции для получения имени файла, если вы больше не используете делегат хранилища данных или context.createDataStore ( I60f9a ).
  • Сериализатор writeTo и readFrom теперь приостанавливаются. Если вы внедрили сериализатор, вам нужно будет обновить ваши функции, чтобы они стали функциями приостановки. ( I1e58e )
  • Добавлены делегаты свойств для пользователей RxDataStore. ( Иед768 , р/173726702 )

Исправления ошибок

  • Ввести ограничения на публичное использование экспериментальных API ( I6aa29 , b/174531520 ).

Версия 1.0.0-альфа07

24 февраля 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-alpha07 . Версия 1.0.0-alpha07 содержит эти коммиты.

Изменения API

  • Функция расширения Context.createDataStore была удалена и заменена делегатом свойства globalDataStore. Вызовите globalDataStore один раз на верхнем уровне вашего файла Kotlin. Например:

    val Context.myDataStore by dataStore(...)

    Поместите это на верхний уровень вашего файла Kotlin, чтобы существовал только один экземпляр. ( I57215 , б / 173726702 )

  • Функции RxDataStore теперь находятся в классе RxDataStore, а не в функциях расширения в DataStore. ( Idccdb , б/177691248 )

  • Если вы хотите перенести EncryptedSharedPreferences (или SharedPreferences с прямой загрузкой) в DataStore, теперь вы можете сделать это с помощью нового конструктора SharedPreferencesMigration, который позволяет вам внедрить SharedPreferences. ( I8e04e , б/177278510 )

Исправления ошибок

  • DataStore теперь будет выдавать исключение, если для одного и того же файла имеется несколько активных DataStore. Если вы не управляли своим DataStore как Singleton или не гарантировали, что никакие два экземпляра DataStore не будут одновременно активны для файла, теперь вы можете увидеть исключения при чтении или записи в DataStore. Это можно исправить, управляя хранилищем данных как синглтоном. ( Ib43f4 , б/177691248 )
  • Исправлено поведение отмены при отмене области вызывающего абонента. ( I2c7b3 )

Версия 1.0.0-альфа06

13 января 2021 г.

Выпущен androidx.datastore:datastore-*:1.0.0-alpha06 . Версия 1.0.0-alpha06 содержит эти коммиты.

Новые возможности

  • Добавлены оболочки RxJava для DataStore. Артефакты datastore-rxjava2/3 содержат оболочки для основных API DataStore ( RxDataStore , RxDataStoreBuilder и RxDataMigration ). Артефакты datastore-preferences-rxjava2/3 содержат построитель для создания хранилища данных предпочтений.

Изменения API

  • Скройте интерфейс CorruptionHandler. Не было никаких причин публиковать его публично, поскольку фабрика DataStore принимает только replaceFileCorruptionHandler. ( I0b3b3 , б/176032264 )
  • Метод preferencesKey<T>(name: String): Key<T> был удален и заменен методами, специфичными для каждого поддерживаемого типа, например, preferencesKey<Int>("int") теперь является intPreferencesKey("int") ( Ibcfac , б/170311106 )

Исправления ошибок

  • Исправляет документацию DataStoreFactory, в которой не учитывается тот факт, что файл хранилища данных создается в подкаталоге «datastore/». ( Ica222 )

Версия 1.0.0-альфа05

2 декабря 2020 г.

Выпущен androidx.datastore:datastore-*:1.0.0-alpha05 . Версия 1.0.0-alpha05 содержит эти коммиты.

Исправления ошибок

  • Добавьте улучшенную документацию и исключения для одновременной записи из хранилищ данных. ( Я98а2 , б/173522155 , б/173726702 )
  • Теперь мы разрешаем (но не требуем) закрытие OutputStream, переданного в Serializer.writeTo() . ( I5c9bf , б/173037611 )

Версия 1.0.0-альфа04

17 ноября 2020 г.

Выпущен androidx.datastore:datastore-*:1.0.0-alpha04 . Версия 1.0.0-alpha04 содержит эти коммиты.

Исправления ошибок

  • Исправлена ​​проблема с упаковкой, приводившая к следующему сбою в хранилище данных предпочтений 1.0.0-alpha03 : java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Версия 1.0.0-альфа03

11 ноября 2020 г.

Выпущен androidx.datastore:datastore-*:1.0.0-alpha03 . Версия 1.0.0-alpha03 содержит эти коммиты.

Новые возможности

  • Настройки теперь поддерживают двойные значения (что полезно, если вам нужна большая точность, чем числа с плавающей запятой) ( I5be8f , b/169471808 )

Изменения API

  • Создана чистая зависимость Kotlin для хранилища данных, чтобы обеспечить более быструю компиляцию. androidx.datastore:datastore-core содержит основные API-интерфейсы Kotlin, а androidx.datastore:datastore содержит API-интерфейсы, которые зависят от Android (включая SharedPreferencesMigration и конструктор Context.createDataStore .) ( I42d75 , b/168512698 )
  • Разделение целей для хранилища данных настроек для более быстрой компиляции Kotlin ( Ia3c19 )

  • Сериализаторам теперь требуется новое свойство для значения по умолчанию, которое будет использоваться, если на диске нет данных. Это упрощает реализацию пользовательских сериализаторов, поэтому пользователям не нужно выделять пустые входные потоки в особый регистр (пустые входные потоки не анализируются с помощью json).

    • Также теперь есть проверка, подтверждающая, что выходной поток, предоставленный writeTo(), не закрыт, и если он закрыт, он выдает исключения ( I16e29 ).

  • Создание внутреннего конструктора SharedPreferencesView. Первоначально он был общедоступным, чтобы можно было проводить тестирование. Вместо этого тесты должны создавать SharedPreferencesMigration и проверять его. ( I93891 )

Исправления ошибок

  • Параметр produceFile в DataStoreFactory и PreferenceDataStoreFactory теперь является последним параметром в списке, поэтому он позволяет использовать конечный лямбда-синтаксис Kotlin. ( Ibe7f1 , б/169425442 )
  • Следуя новым явным требованиям API для Kotlin ( I5ae1e )

Известные проблемы

  • Сбой хранилища данных предпочтений с ошибкой java.lang.NoClassDefFoundError . ( б / 173036843 )

Версия 1.0.0-альфа02

14 октября 2020 г.

Выпущены androidx.datastore:datastore-core:1.0.0-alpha02 и androidx.datastore:datastore-preferences:1.0.0-alpha02 . Версия 1.0.0-alpha02 содержит эти коммиты.

Исправления ошибок

  • Добавлена ​​защита от мутаций в ядре хранилища данных. Мутация нарушает использование хранилища данных для людей, использующих хранилище данных с типами, не являющимися прото/не предпочтениями ( I6aa84 ).
  • В Preferences.kt добавлен метод toString , чтобы упростить отладку текущего состояния ( I96006 ).
  • Добавлено исключение для защиты от неправильного использования DataStore.Preferences ( I1134d ).
  • Исправлена ​​ошибка, приводившая к сбою приложения при запуске ( I69237 , b/168580258 ).

Версия 1.0.0-альфа01

2 сентября 2020 г.

Выпущены 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.