O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Salvar dados chave-valor

Caso você tenha um conjunto relativamente pequeno de chaves-valor para salvar, use as APIs SharedPreferences. Um objeto SharedPreferences indica um arquivo que contém pares de chave-valor e fornece métodos simples para leitura e gravação. Cada arquivo SharedPreferences é gerenciado pelo framework e pode ser privado ou compartilhado.

Esta página mostra como usar as APIs SharedPreferences para armazenar e recuperar valores simples.

Observação: as APIs SharedPreferences são usadas para ler e gravar pares de chave-valor, diferente das APIs Preference, que ajudam a criar uma interface do usuário para as configurações do app, embora também usem SharedPreferences para salvar as configurações do usuário. Para ver mais informações sobre as APIs Preference, consulte o Guia do desenvolvedor para configurações.

Conseguir um manipulador para as preferências compartilhadas

É possível criar um novo arquivo de preferências compartilhadas ou acessar um já existente chamando um dos seguintes métodos:

  • getSharedPreferences(): use esse método se precisar de vários arquivos de preferências compartilhadas identificados por nome, que são especificados com o primeiro parâmetro. É possível chamá-lo em qualquer Context no app.
  • getPreferences(): use esse método por uma Activity se precisar usar apenas um arquivo de preferências compartilhadas para a atividade. Como ele recupera um arquivo padrão de preferências compartilhadas que pertence à atividade, não é necessário fornecer um nome.

Por exemplo, o código a seguir acessa o arquivo de preferências compartilhadas identificado pela string de recurso R.string.preference_file_key e abre o arquivo usando o modo privado para que o arquivo fique acessível somente para o app:

Kotlin

    val sharedPref = activity?.getSharedPreferences(
            getString(R.string.preference_file_key), Context.MODE_PRIVATE)
    

Java

Context context = getActivity();
    SharedPreferences sharedPref = context.getSharedPreferences(
            getString(R.string.preference_file_key), Context.MODE_PRIVATE);

Ao nomear os arquivos de preferências compartilhadas, use um nome que seja identificável de forma exclusiva para o app. Uma maneira fácil de fazer isso é usar o ID do aplicativo como prefixo para o nome do arquivo. Por exemplo: "com.example.myapp.PREFERENCE_FILE_KEY"

Como alternativa, caso precise apenas de um arquivo de preferências compartilhadas para sua atividade, use o método getPreferences():

Kotlin

    val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE)
    

Java

    SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
    

Cuidado: os modos MODE_WORLD_READABLE e MODE_WORLD_WRITEABLE estão obsoletos desde a API de nível 17. A partir da versão 7.0 (API de nível 24), o Android vai gerar uma SecurityException se você usá-los. Caso o app precise compartilhar arquivos particulares com outros apps, ele poderá usar um FileProvider com a FLAG_GRANT_READ_URI_PERMISSION. Para ver mais informações, consulte também Como compartilhar arquivos.

Se a API SharedPreferences for usada para salvar as configurações do app, será preciso usar getDefaultSharedPreferences() para ter o arquivo de preferências compartilhadas padrão para todo o app. Saiba mais no Guia do desenvolvedor para configurações.

Gravar em preferências compartilhadas

Para gravar em um arquivo de preferências compartilhadas, crie um SharedPreferences.Editor chamando edit() nas suas SharedPreferences.

Observação: é possível editar as preferências compartilhadas de forma mais segura chamando o método edit() em um objeto EncryptedSharedPreferences em vez de em um objeto SharedPreferences. Para saber mais, consulte o guia sobre como trabalhar com dados de forma mais segura.

Transmita as chaves e os valores que você quer gravar com métodos como putInt() e putString(). Em seguida, chame apply() ou commit() para salvar as mudanças. Exemplo:

Kotlin

    val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return
    with (sharedPref.edit()) {
        putInt(getString(R.string.saved_high_score_key), newHighScore)
        commit()
    }
    

Java

    SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
    SharedPreferences.Editor editor = sharedPref.edit();
    editor.putInt(getString(R.string.saved_high_score_key), newHighScore);
    editor.commit();

apply() muda imediatamente o objeto SharedPreferences na memória, mas grava as atualizações no disco de forma assíncrona. Ou você pode usar commit() para gravar os dados no disco de forma síncrona. Contudo, como commit() é síncrono, evite chamá-lo pela linha de execução principal, porque ele pode pausar a renderização da IU.

Ler de preferências compartilhadas

Para recuperar valores de um arquivo de preferências compartilhadas, chame métodos como getInt() e getString(), fornecendo a chave para o valor que você quer recuperar e, opcionalmente, um valor padrão para retornar caso a chave não esteja presente. Exemplo:

Kotlin

    val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return
    val defaultValue = resources.getInteger(R.integer.saved_high_score_default_key)
    val highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue)
    

Java

    SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
    int defaultValue = getResources().getInteger(R.integer.saved_high_score_default_key);
    int highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue);