DataStore

DataStore

Guía del usuario  Codelab

Referencia de la API
androidx.datastore

Almacena los datos de forma asíncrona, coherente y transaccional, por lo que resuelve algunos de los inconvenientes de SharedPreferences

Actualización más reciente	Versión estable	Versión potencial	Versión beta	Versión alfa
15 de enero de 2025	1.1.2	-	-	-

Cómo declarar dependencias

Para agregar una dependencia en DataStore, debes agregar el repositorio Maven de Google a tu proyecto. Lee el repositorio Maven de Google para obtener más información.

Hay dos implementaciones de DataStore: Preferences y Proto. Elige una de ellas. También puedes agregar dependencias sin Android a cualquiera de las dos implementaciones.

Agrega las dependencias de la implementación que necesites en el archivo build.gradle de tu app o módulo:

Preferences DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

Proto DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

Comentarios

Tus comentarios ayudan a mejorar Jetpack. Avísanos si descubres nuevos errores o tienes ideas para mejorar esta biblioteca. Consulta los errores existentes de esta biblioteca antes de crear uno nuevo. Puedes agregar tu voto a un error existente haciendo clic en el botón de la estrella.

Crear un error nuevo

Consulta la documentación sobre la Herramienta de seguimiento de errores para obtener más información.

Versión 1.1

Versión 1.1.2

15 de enero de 2025

Lanzamiento de androidx.datastore:datastore-*:1.1.2. La versión 1.1.2 contiene estas confirmaciones.

Correcciones de errores

• Mejora la latencia de lectura activa (DataStore.data.first()) 8 veces. (22b8a40).
• ReplaceFileCorruptionHandler se puede crear a partir del código común de KMP. (7632e839).

Versión 1.1.1

1 de mayo de 2024

Lanzamiento de androidx.datastore:datastore-*:1.1.1. La versión 1.1.1 contiene estas confirmaciones.

Correcciones de errores

• Se mitigó la falsa alarma de Linux en el error "Se produciría un interbloqueo de recursos" en un caso extremo en el que varias instancias de DataStore intentan escribir desde diferentes procesos a través de la anulación del bloqueo de archivos.

Versión 1.1.0

17 de abril de 2024

Lanzamiento de androidx.datastore:datastore-*:1.1.0. La versión 1.1.0 contiene estas confirmaciones.

Cambios importantes desde la versión 1.0.0

Revisa las notas de la versión alfa y beta de 1.1.0 para obtener más información. Estas son algunas de las actualizaciones principales de la versión 1.1.0:

• DataStore ahora admite varios procesos que acceden al mismo archivo, con compatibilidad con la observabilidad en todos los procesos.
• La nueva interfaz de Storage te permite personalizar la forma de almacenar o serializar tus modelos de datos.
• Ahora puedes usar DataStore en proyectos de Kotlin multiplataforma.

Versión 1.1.0-rc01

3 de abril de 2024

Lanzamiento de androidx.datastore:datastore-*:1.1.0-rc01. La versión 1.1.0-rc01 contiene estas confirmaciones.

Correcciones de errores

• Se corrigió la degradación del rendimiento en la que las llamadas a updateData no optimizaban las operaciones de escritura en el disco si los datos nuevos eran los mismos que los anteriores (d64cfb5).
• Se corrigió una condición de carrera en la que MultiProcess DataStore podría perder invalidaciones durante la inicialización. ((b/326141553),(094c2dd))

Versión 1.1.0-beta02

6 de marzo de 2024

Lanzamiento de androidx.datastore:datastore-*:1.1.0-beta02. La versión 1.1.0-beta02 contiene estas confirmaciones.

Correcciones de errores

• La mejora del rendimiento en DataStore solo recopila notificaciones de actualización cuando se observa. (b/267792241)
  • Ten en cuenta que este cambio podría activar UncompletedCoroutinesError en tus pruebas si usas la biblioteca de pruebas de corrutinas. Asegúrate de pasar el TestScope.backgroundScope cuando inicialices DataStore en tus pruebas para evitar este problema.
• ​Se corrigió el problema por el que se producía un interbloqueo en las llamadas updateData anidadas en la misma instancia. (b/241760537).
• Se hizo que DataStore ya no arroje IOExceptions si no borra SharedPreferences durante la migración. (b/195553816).
• Se corrigió el problema por el que fallaba el cambio de nombre de archivo durante updateData en entornos de JVM que no son de Android. (b/203087070).
• Se corrigió el problema por el que CorruptionException no se controlaba después de la inicialización de DataStore. (b/289582516).

Versión 1.1.0-beta01

10 de enero de 2024

Lanzamiento de androidx.datastore:datastore-*:1.1.0-beta01 sin cambios desde 1.1.0-alpha07. La versión 1.1.0-beta01 contiene estas confirmaciones.

Versión 1.1.0-alpha07

29 de noviembre de 2023

Lanzamiento de androidx.datastore:datastore-*:1.1.0-alpha07. La versión 1.1.0-alpha07 contiene estas confirmaciones.

Cambios en la API

• Los métodos MultiProcessDataStoreFactory ya no son experimentales.La anotación @ExperimentalMultiProcessDataStore se quitó por completo. (Ieee54, I8e607)

Correcciones de errores

• Lanzamiento de la eliminación de las anotaciones @ExperimentalMultiProcessDataStore a la versión 1.1.0-alpha07. (I8e607).

Versión 1.1.0-alpha06

1 de noviembre de 2023

Lanzamiento de androidx.datastore:datastore-*:1.1.0-alpha06. La versión 1.1.0-alpha06 contiene estas confirmaciones.

Cambios en la API

• El método de fábrica createSingleProcessCoordinator ahora recibe una ruta de acceso al archivo (String, java.io.File y okio.Path) para ser coherente con createMultiProcessCoordinator. (I211c8, b/305755935).

Versión 1.1.0-alpha05

6 de septiembre de 2023

Lanzamiento de androidx.datastore:datastore-*:1.1.0-alpha05. La versión 1.1.0-alpha05 contiene estas confirmaciones.

Cambios en la API

• Datastore FileStorage ahora está disponible de forma pública, por lo que los clientes pueden proporcionar parámetros personalizados. (Icb985)
• Se cambió el constructor OkioStorage para que acepte un InterProcessCoordinator, de modo que se pueda usar en Android con MultiProcessCoordinator. (Iecea3).

Correcciones de errores

• Se corrigió el problema por el que MultiProcessCoordinator no podía supervisar varios archivos en el mismo directorio.
• Se corrigió el error que no podía detectar archivos duplicados si las rutas de acceso a los archivos no estaban normalizadas.
• Se corrigieron los valores incorrectos que se mostraban desde RxDataStore#isDisposed.
• Se corrigió la configuración de Proguard faltante para el artefacto datstore-preferences-core.

Versión 1.1.0-alpha04

5 de abril de 2023

Lanzamiento de androidx.datastore:datastore-*:1.1.0-alpha04. La versión 1.1.0-alpha04 contiene estas confirmaciones.

Correcciones de errores

• Se mejoró la implementación interna para evitar una condición de carrera en la que el flujo de datos de DataStore podría emitir un valor más antiguo después de una actualización.

Versión 1.1.0-alpha03

24 de marzo de 2023

Lanzamiento de androidx.datastore:datastore-*:1.1.0-alpha03.

Correcciones de errores

• Se quitaron las restricciones de dependencia de los artefactos de Maven para solucionar un problema de compilación en los destinos nativos de Kotlin (b/274786186, KT-57531).

Versión 1.1.0-alpha02

22 de marzo de 2023

Lanzamiento de androidx.datastore:datastore-*:1.1.0-alpha02. La versión 1.1.0-alpha02 contiene estas confirmaciones.

Nota

Ten en cuenta que esta versión incluye una refactorización interna importante que combina las implementaciones de DataStore de un solo proceso y de varios procesos. Presta atención a posibles cambios de comportamiento no deseados (p.ej., el tiempo de las notificaciones de actualización). Puedes usar el componente de seguimiento de problemas para informar estos cambios.

Nuevas funciones

• Ahora puedes usar DataStore en proyectos de KMM. Ten en cuenta que los destinos de DataStore que no son de Android aún son experimentales, pero decidimos combinar las versiones para que los desarrolladores puedan probarlas con mayor facilidad.
• Las funciones de varios procesos se movieron de androidx.datastore.multiprocess a androidx.datastore.core.
• Se agregó un nuevo método de fábrica en androidx.datastore.core.MultiProcessDataStoreFactory para crear instancias de DataStore con objetos Storage para operaciones de archivos.
• Se agregó una nueva interfaz InterProcessCoordinator que ayuda a que varias instancias de DataStore se comuniquen entre procesos. Ten en cuenta que la implementación de varios procesos de InterProcessCoordinator solo está disponible en Android.

Cambios en la API

• Se agregó InterProcessCoordinator a StorageConnection en la interfaz de datastore-core (I555bb).
• Se cambiaron las APIs en MultiProcessDataStoreFactory de datastore-core para usar Storage (Iac02f).
• Se movieron las APIs públicas de datastore-multiprocess a datastore-core (I76d7c).
• Se expuso PreferencesSerializer de datastore-preferences-core (I4b788).
• Se agregó la anotación @JvmDefaultWithCompatibility (I8f206).

Versión 1.1.0-alpha01

9 de noviembre de 2022

Se lanzó androidx.datastore:datastore-*:1.1.0-alpha01. La versión 1.1.0-alpha01 contiene estas confirmaciones.

Nuevas funciones

• Se admitieron casos de uso de procesos múltiples en los que se garantiza la coherencia de los datos entre las instancias de DataStore en todos los procesos. Se agregó MultiProcessDataStoreFactory#create para crear esas instancias de DataStore.
• Nueva interfaz de Storage, que permite cambiar el mecanismo de almacenamiento subyacente de Datastore. Se proporcionaron implementaciones para java.io y okio. Las fábricas de DataStore tienen métodos nuevos que aceptan este objeto de Storage.

Cambios en la API

• Se cambiaron las APIs en MultiProcessDataStoreFactory de datastore-core para usar Storage (Iac02f).
• Se movieron las APIs públicas de datastore-multiprocess a datastore-core (I76d7c).
• Se expuso PreferencesSerializer de datastore-preferences-core (I4b788).

Versión 1.0.0

Versión 1.0.0

4 de agosto de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0. La versión 1.0.0 contiene estas confirmaciones.

Funciones principales de la versión 1.0.0

Jetpack Datastore es una solución de almacenamiento de datos que te permite almacenar pares clave-valor u objetos escritos con búferes de protocolo. Datastore usa corrutinas y Flow de Kotlin para almacenar datos de manera asíncrona, coherente y transaccional.

Versión 1.0.0-rc02

21 de julio de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-rc02. La versión 1.0.0-rc02 contiene estas confirmaciones.

Correcciones de errores

• Aclara que SharedPreferencesMigration no se ejecuta si no hay claves (Icfa32, b/192824325).
• Corrige el error por el que SharedPreferencesMigration construido con MIGRATE_ALL_KEYS arrojaba una excepción si la clave solicitada aún no existía (Ie318a, b/192824325).

Versión 1.0.0-rc01

30 de junio de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-rc01. La versión 1.0.0-rc01 contiene estas confirmaciones.

Correcciones de errores

• Se corrigió un error por el que se agregaba inadvertidamente el archivo java jar final (I65d96, b/188985637).

Versión 1.0.0-beta02

16 de junio de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-beta02. La versión 1.0.0-beta02 contiene estas confirmaciones.

Correcciones de errores

• Se corrigió ClassVerificationFailure (b/187450483).

Versión 1.0.0-beta01

21 de abril de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-beta01. La Versión 1.0.0-beta01 contiene estas confirmaciones.

Cambios en la API

• Se quitaron las sobrecargas de JVM para métodos exclusivos de Kotlin (I2adc7).

Correcciones de errores

• Se corrigió un error por el que, en ocasiones, los delegados del almacén de datos generaban fugas de contextos (Ie96fc, b/184415662).

Versión 1.0.0-alpha08

10 de marzo de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-alpha08. La versión 1.0.0-alpha08 contiene estas confirmaciones.

Cambios en la API

• Ahora puedes agregar una migración que dependa del contexto para el delegado de tu propiedad dataStore y preferencesDataStore (I4ef69, b/173726702).
• Agrega funciones auxiliares para obtener el nombre del archivo si ya no usas el delegado del almacén de datos o contexto.createDataStore (I60f9a).
• Las serializaciones WriteTo y ReadFrom se encuentran suspendidas. Si implementaste un serializador, deberás actualizar tus funciones para que sean funciones de suspensión (I1e58e).
• Se agregaron delegados de propiedad para los usuarios de RxDataStore (Ied768, b/173726702).

Correcciones de errores

• Se aplicaron restricciones sobre el uso público de APIs experimentales (I6aa29, b/174531520).

Versión 1.0.0-alpha07

24 de febrero de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-alpha07. La versión 1.0.0-alpha07 contiene estas confirmaciones.

Cambios en la API

• Se quitó la función de la extensión Context.createDataStore y se la reemplazó por el delegado de la propiedad globalDataStore. Llama a globalDataStore una sola vez en el nivel superior de tu archivo de Kotlin. Por ejemplo:

  val Context.myDataStore by dataStore(...)
  

  Coloca esta línea en el nivel superior de tu archivo de Kotlin a fin de que haya solo una instancia (I57215, b/173726702).

• Las funciones de RxDataStore ahora se encuentran en una clase de RxDataStore, en lugar de considerarse funciones de extensión en DataStore (Idccdb, b/177691248).

• Si deseas migrar EncryptedSharedPreferences (o SharedPreferences con inicio directo) a DataStore, ahora puedes hacerlo con el nuevo constructor SharedPreferencesMigration, que te permite insertar SharedPreferences (I8e04e, b/177278510).

Correcciones de errores

• DataStore ahora generará una excepción si hay varios DataStore activos para el mismo archivo. Si tu DataStore no estaba configurado como un singleton, o no estabas comprobando si había dos instancias de DataStore activas para un mismo archivo en simultáneo, es posible que ahora veas excepciones durante la lectura o escritura de DataStore. Para solucionar estos problemas, configura tu DataStore como un singleton (Ib43f4, b/177691248).
• Se corrigió el comportamiento de cancelación cuando se cancelaba el alcance del emisor (I2c7b3).

Versión 1.0.0-alpha06

13 de enero de 2021

Lanzamiento de androidx.datastore:datastore-*:1.0.0-alpha06. La versión 1.0.0-alpha06 contiene estas confirmaciones.

Nuevas funciones

• Se agregaron wrappers de RxJava para DataStore. Los artefactos datastore-rxjava2/3 contienen los wrappers para las APIs principales de DataStore (RxDataStore, RxDataStoreBuilder y RxDataMigration). Los artefactos datastore-preferences-rxjava2/3 contienen un compilador para construir la implementación Preferences Datastore.

Cambios en la API

• Se ocultó la interfaz de CorruptionHandler. No hay motivo para que sea pública, porque la fábrica de DataStore solo acepta un ReplaceFileCorruptionHandler (I0b3b3, b/176032264).
• Se quitó el método preferencesKey<T>(name: String): Key<T> y se lo reemplazó por métodos específicos para cada tipo admitido; por ejemplo, preferencesKey<Int>("int") ahora es intPreferencesKey("int") (Ibcfac, b/170311106).

Correcciones de errores

• Se corrigió la documentación sobre DataStoreFactory que no mencionaba que el archivo de almacén de datos se crea en el subdirectorio “datastore/” (Ica222).

Versión 1.0.0-alpha05

2 de diciembre de 2020

Lanzamiento de androidx.datastore:datastore-*:1.0.0-alpha05. La versión 1.0.0-alpha05 contiene estas confirmaciones.

Correcciones de errores

• Se agregaron mejores documentaciones y excepciones sobre escrituras simultáneas de almacenes de datos (Ia98a2, b/173522155, b/173726702).
• Ahora se permite cerrar el elemento OutputStream que se pasa a Serializer.writeTo() (aunque no es un requisito) (I5c9bf, b/173037611).

Versión 1.0.0-alpha04

17 de noviembre de 2020

Lanzamiento de androidx.datastore:datastore-*:1.0.0-alpha04. La versión 1.0.0-alpha04 contiene estas confirmaciones.

Correcciones de errores

• Se corrigió un problema de empaquetado que causaba la siguiente falla en Preference Datastore 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences
  • La falla se informó originalmente aquí: b/173036843
  • (I4712d, b/173036843).

Versión 1.0.0-alpha03

11 de noviembre de 2020

Lanzamiento de androidx.datastore:datastore-*:1.0.0-alpha03. La versión 1.0.0-alpha03 contiene estas confirmaciones.

Precaución: En su lugar, usa la versión 1.0.0-alpha04. Se encontró un error crítico en la versión 1.0.0-alpha03, que causaba que Preference Datastore falle con java.lang.NoClassDefFoundError (b/173036843)

.

Nuevas funciones

• Preferences ahora admite valores dobles (lo que resulta útil si necesitas más precisión que la de los números de punto flotante) (I5be8f, b/169471808).

Cambios en la API

• Se creó una dependencia pura de Kotlin para que el almacén de datos permita una compilación más rápida. androidx.datastore:datastore-core contiene las APIs principales de Kotlin, y androidx.datastore:datastore contiene las APIs que dependen de Android (incluido el constructor de Context.createDataStore y SharedPreferencesMigration) (I42d75, b/168512698).
• Se dividieron los objetivos del almacén de datos de preferencias para lograr una compilación de Kotlin más rápida (Ia3c19).

• Los serializadores ahora requieren una nueva propiedad para el valor predeterminado que se usará si no hay datos en el disco. Esto facilita la implementación de serializadores personalizados de modo que los usuarios no tengan que tratar las transmisiones de entrada vacías de modo especial (ya que estas no se analizan con json).

  • Ahora también existe una verificación para confirmar que la transmisión de salida suministrada a writeTo() no está cerrada, y, si lo está, arroja excepciones (I16e29).

• El constructor de SharedPreferencesView se volvió interno. Originalmente, era público para permitir la realización de pruebas. Ahora, se debe construir un objeto SharedPreferencesMigration y realizar las pruebas con él (I93891).

Correcciones de errores

• El parámetro produceFile en DataStoreFactory, y PreferenceDataStoreFactory ahora es el último parámetro de la lista, por lo que te permite usar la sintaxis de expresión lambda final de Kotlin (Ibe7f1, b/169425442).
• Se siguen los nuevos requisitos explícitos de la API para Kotlin (I5ae1e).

Errores conocidos

• Preference Datastore falla con java.lang.NoClassDefFoundError (b/173036843).

Versión 1.0.0-alpha02

14 de octubre de 2020

Lanzamiento de androidx.datastore:datastore-core:1.0.0-alpha02 y androidx.datastore:datastore-preferences:1.0.0-alpha02. La versión 1.0.0-alpha02 contiene estas confirmaciones.

Correcciones de errores

• Se agregó una protección contra la mutación en el núcleo del almacén de datos. La mutación interrumpe el uso del almacén de datos para las personas que no usan Preferences o Proto DataStore (I6aa84).
• Se agregó un método toString a Preferences.kt para que el estado actual sea fácil de depurar (I96006).
• Se agregó una excepción para proteger contra el uso inadecuado de DataStore.Preferences (I1134d).
• Se corrigió un error que hacía que la app fallara al iniciarse (I69237, b/168580258).

Versión 1.0.0-alpha01

2 de septiembre de 2020

Lanzamiento de androidx.datastore:datastore-core:1.0.0-alpha01 y androidx.datastore:datastore-preferences:1.0.0-alpha01. La versión 1.0.0-alpha01 contiene estas confirmaciones.

Nuevas funciones

Jetpack DataStore es una solución nueva y mejorada de almacenamiento de datos que apunta a reemplazar SharedPreferences. DataStore, que se basa en corrutinas y flujo de Kotlin, proporciona dos implementaciones diferentes:

• Proto DataStore, que te permite almacenar objetos escritos (respaldado por búferes de protocolo)
• Preferences DataStore, que almacena pares clave-valor

Los datos se almacenan de forma asíncrona, coherente y transaccional, por lo que resuelve la mayoría de los inconvenientes de SharedPreferences.