Datastore

Declarar dependências

Para adicionar uma dependência a Datastore, adicione o repositório Maven do Google ao seu projeto. Leia Repositório Maven do Google para ver mais informações.

Há duas implementações de Datastore: Preferências e Proto. Escolha uma delas. Você também pode adicionar dependências sem Android a qualquer uma dessas implementações.

Adicione as dependências para a implementação necessária no arquivo build.gradle do app ou módulo:

Preferences DataStore

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

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

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

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

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

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

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

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

Proto DataStore

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

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

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

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

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

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

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

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

Feedback

Seu feedback ajuda a melhorar o Jetpack. Avise se você descobrir novos problemas ou tiver ideias para melhorar esta biblioteca. Consulte os problemas conhecidos nesta biblioteca antes de criar um novo. Adicione seu voto a um problema clicando no botão de estrela.

Criar novo problema

Consulte a documentação do Issue Tracker para saber mais.

Versão 1.0.0

Versão 1.0.0

4 de agosto de 2021

Lançamento de androidx.datastore:datastore-*:1.0.0. A versão 1.0.0 contém estas confirmações.

Principais recursos da versão 1.0.0

O Jetpack DataStore é uma solução de armazenamento de dados que possibilita armazenar pares de chave-valor ou objetos tipados com buffers de protocolo. O DataStore usa corrotinas e fluxo do Kotlin para armazenar dados de forma assíncrona, consistente e transacional.

Versão 1.0.0-rc02

21 de julho de 2021

Lançamento de androidx.datastore:datastore-*:1.0.0-rc02. A versão 1.0.0-rc02 contém essas confirmações (link em inglês).

Correções de bugs

• Esclarecimento de que a SharedPreferencesMigration não será executada se não houver chaves (Icfa32, b/192824325).
• Correção do bug em que a SharedPreferencesMigration construída com MIGRATE_ALL_KEYS gerava uma exceção se a chave solicitada ainda não existisse (Ie318a, b/192824325).

Versão 1.0.0-rc01

30 de junho de 2021

Lançamento da versão androidx.datastore:datastore-*:1.0.0-rc01. A versão 1.1.0-rc01 contém estas confirmações.

Correções de bugs

• Correção do bug em que o arquivo .java foi adicionado inadvertidamente ao jar final (I65d96, b/188985637)

Versão 1.0.0-beta02

16 de junho de 2021

Lançamento de androidx.datastore:datastore-*:1.0.0-beta02. A versão 1.0.0-beta02 contém estas confirmações.

Correções de bugs

• Correção da ClassVerificationFailure (b/187450483).

Versão 1.0.0-beta01

21 de abril de 2021

Lançamento de androidx.datastore:datastore-*:1.0.0-beta01. A versão 1.0.0-beta01 contém estas confirmações.

Mudanças na API

• Remoção das sobrecargas JVM para métodos somente em Kotlin (I2adc7).

Correções de bugs

• Correção de um bug em que os repositórios de dados delegados podiam resultar em contextos vazados (Ie96fc, b/184415662)

Versão 1.0.0-alpha08

10 de Março de 2021

Lançamento de androidx.datastore:datastore-*:1.0.0-alpha08. A versão 1.0.0-alpha08 contém estas confirmações.

Mudanças na API

• Agora você pode adicionar uma migração que depende do contexto aos seus delegados de propriedade dataStore e preferencesDataStore (I4ef69, b/173726702).
• Foram adicionadas funções auxiliares para acessar o nome do arquivo se você não estiver mais usando o repositório de dados delegado ou context.createDataStore (I60f9a).
• O serializador writeTo e readFrom agora são funções de suspensão. Se você implementou um serializador, precisará atualizar suas funções para serem de suspensão (I1e58e).
• Delegados de propriedade foram adicionados para usuários do RxDataStore (Ied768, b/173726702).

Correções de bugs

• Aplicação de restrições ao uso público de APIs experimentais (I6aa29, b/174531520).

Versão 1.0.0-alpha07

24 de fevereiro de 2021

Lançamento de androidx.datastore:datastore-*:1.0.0-alpha07. A versão 1.0.0-alpha07 contém estas confirmações.

Mudanças na API

• A função de extensão Context.createDataStore foi removida e substituída pelo delegado da propriedade globalDataStore. Chame globalDataStore uma vez no nível superior do arquivo Kotlin. Exemplo:

  val Context.myDataStore by dataStore(...)
  

  Coloque-o no nível superior do seu arquivo Kotlin para que haja apenas uma instância dele (I57215, b/173726702).

• As funções RxDataStore agora estão em uma classe RxDataStore em vez de funções de extensão no DataStore (Idccdb, b/177691248).

• Se você quiser migrar as EncryptedSharedPreferences (ou SharedPreferences de inicialização direta) para o DataStore, faça isso com o novo construtor SharedPreferencesMigration, que permite injetar as SharedPreferences (I8e04e, b/177278510).

Correções de bugs

• O DataStore agora gerará uma exceção se houver vários DataStores ativos para o mesmo arquivo. Se você não estava gerenciando seu DataStore como um Singleton ou não estava garantindo que duas instâncias de DataStore não fossem ativadas simultaneamente para um arquivo, talvez veja exceções ao ler ou gravar no DataStore. Para corrigir isso, gerencie o DataStore como um Singleton (Ib43f4, b/177691248).
• Correção do comportamento de cancelamento quando o escopo do autor da chamada é cancelado (I2c7b3).

Versão 1.0.0-alpha06

13 de janeiro de 2021

Lançamento do androidx.datastore:datastore-*:1.0.0-alpha06. A versão 1.0.0-alpha06 contém estas confirmações.

Novos recursos

• Adição de wrappers RxJava para DataStore. Os artefatos datastore-rxjava2/3 contêm os wrappers para as principais APIs DataStore (RxDataStore, RxDataStoreBuilder e RxDataMigration). Os artefatos datastore-preferences-rxjava2/3 contêm um builder para construir um Preferences DataStore.

Mudanças na API

• Oculte a interface CorruptionHandler. Não é necessário que ela seja pública porque a fábrica do DataStore só aceita um ReplaceFileCorrionHandler (I0b3b3, b/176032264).
• O método preferencesKey<T>(name: String): Key<T> foi removido e substituído por métodos específicos de cada tipo suportado. Por exemplo, preferencesKey<Int>("int") agora é intPreferencesKey("int") (Ibcfac b/170311106).

Correções de bugs

• Corrige a documentação no DataStoreFactory, que deixou de fora o fato de que o arquivo de armazenamento de dados é criado no subdiretório "datastoredatastore/" (Ica222).

Versão 1.0.0-alpha05

2 de dezembro de 2020

Lançamento de androidx.datastore:datastore-*:1.0.0-alpha05. A versão 1.0.0-alpha05 contém estas confirmações.

Correções de bugs

• Adição de documentação e exceções melhores em gravações simultâneas de armazenamentos de dados (Ia98a2, b/173522155, b/173726702).
• Agora é permitido, mas não obrigatório, que o OutputStream transmitido para Serializer.writeTo() seja fechado (I5c9bf, b/173037611).

Versão 1.0.0-alpha04

17 de novembro de 2020

androidx.datastore:datastore-*:1.0.0-alpha04 é lançado. A versão 1.0.0-alpha04 contém estas confirmações.

Correções de bugs

• Correção de um problema de empacotamento que causava a seguinte falha no Datastore de preferências 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences
  • A falha foi relatada originalmente aqui: b/173036843.
  • (I4712d, b/173036843).

Versão 1.0.0-alpha03

11 de novembro de 2020

androidx.datastore:datastore-*:1.0.0-alpha03 é lançado. A versão 1.0.0-alpha03 contém estas confirmações.

Novos recursos

• As preferências agora são compatíveis com valores duplos, o que é útil se for necessário ter uma precisão maior do que pontos flutuantes (I5be8f, b/169471808).

Mudanças na API

• Uma dependência de Kotlin puro foi criada para o armazenamento de dados para permitir uma compilação mais rápida. O androidx.datastore:datastore-core contém as APIs essenciais somente do Kotlin, e o androidx.datastore:datastore contém as APIs que dependem do Android, incluindo SharedPreferencesMigration e o construtor Context.createDataStore (I42d75, b/168512698).
• Divisão de destinos do armazenamento de dados de preferências para compilação mais rápida em Kotlin (Ia3c19).

• Agora, os serializadores precisam de uma nova propriedade para o valor padrão que será usado se não houver dados no disco. Isso facilita a implementação de serializadores personalizados para que os usuários não tenham que aplicar casos especiais para fluxos de entrada vazios, que não podem ser analisados com JSON.

  • Além disso, agora há uma verificação para confirmar que o fluxo de saída fornecido para writeTo() não está fechado. Se estiver, exceções serão geradas (I16e29).

• Transformação do construtor para SharedPreferencesView em um elemento interno. Originalmente, ele era público para permitir testes. Agora, os testes precisam construir um SharedPreferencesMigration e fazer um teste comparativo (I93891).

Correções de bugs

• O parâmetro produceFile em DataStoreFactory e PreferenceDataStoreFactory agora é o último parâmetro na lista e permite que você use a sintaxe lambda no final do Kotlin (Ibe7f1, b/169425442).
• Os novos requisitos explícitos de API para o Kotlin agora são seguidos (I5ae1e).

Problemas conhecidos

• O Datastore de preferências falha com java.lang.NoClassDefFoundError (b/173036843).

Versão 1.0.0-alpha02

14 de outubro de 2020

Lançamento de androidx.datastore:datastore-core:1.0.0-alpha02 e androidx.datastore:datastore-preferences:1.0.0-alpha02. A versão 1.0.0-alpha02 contém essas confirmações.

Correções de bugs

• Adição de uma proteção contra mutação no armazenamento de dados principal. A mutação interrompe o uso do armazenamento de dados para pessoas que o usam com tipos não proto/não preferências (I6aa84).
• Adição do método toString a Preferences.kt para facilitar a depuração do estado atual (I96006).
• Adição de uma exceção para proteger contra o uso indevido de DataStore.Preferences (I1134d).
• Correção de um bug que fazia o app falhar na inicialização (I69237, b/168580258).

Versão 1.0.0-alpha01

2 de setembro de 2020

Lançamento de androidx.datastore:datastore-core:1.0.0-alpha01 e androidx.datastore:datastore-preferences:1.0.0-alpha01. A versão 1.0.0-alpha01 contém estas confirmações.

Novos recursos

O Jetpack Datastore é uma solução de armazenamento de dados nova e aprimorada que visa substituir SharedPreferences. Criado com fluxo e corrotinas de Kotlin, o DataStore oferece duas implementações diferentes:

• DataStore de .proto, que permite armazenar objetos tipados, protegidos por buffers de protocolo.
• Datastore de preferências, que armazena pares de chave-valor.

Os dados são armazenados de forma assíncrona, consistente e transacional, superando a maioria das desvantagens de SharedPreferences.