Salvar dados chave-valor

Caso você tenha uma coleção relativamente pequena de valores-chave para salvar, use as APIs SharedPreferences. Um objeto SharedPreferences indica um arquivo que contém pares de valores-chave 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 leitura e gravação de pares de valor-chave e não podem ser confundidas com as APIs Preference, que ajudam a criar uma interface de usuário para as configurações do seu app (embora também usem SharedPreferences para salvar as configurações do usuário). Para ver informações sobre as APIs Preference, consulte o Guia do desenvolvedor de 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 de qualquer Context no app.
  • getPreferences(): use esse método a partir de 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 recursos R.string.preference_file_key e abre o arquivo usando o modo privado para que ele fique acessível somente para seu 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 é usando o ID do aplicativo como prefixo do nome do arquivo. Por exemplo: "com.example.myapp.PREFERENCE_FILE_KEY"

Alternativamente, caso precise de apenas um arquivo de preferências compartilhadas para sua atividade, você pode usar 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 do Android 7.0 (API de nível 24), o Android lança uma SecurityException se você usá-los. Se seu app precisar compartilhar arquivos privados 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 você estiver usando a API SharedPreferences para salvar as configurações do app, em vez disso, use getDefaultSharedPreferences() para conseguir o arquivo de preferências compartilhadas padrão para todo o app. Para ver mais informações, consulte o Guia do desenvolvedor de configurações.

Gravar em preferências compartilhadas

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

Observação: você pode 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 alterações. 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 o objeto SharedPreferences na memória imediatamente, mas grava as atualizações no disco de forma assíncrona. Alternativamente, você pode usar commit() para gravar os dados no disco de forma síncrona. Contudo, como commit() é síncrono, evite chamá-lo a partir da linha de execução principal, porque ele pode pausar a renderização de IU.

Ler a partir 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 ser retornado 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);