Salvar dados de 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 particular ou compartilhado.

Esta página mostra como usar as APIs SharedPreferences para armazenar e acessar 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 para desenvolvedores sobre configurações.

Processar preferências compartilhadas

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

• 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 o chamar em qualquer Context no app.
• getPreferences(): use esse método em uma Activity se precisar usar apenas um arquivo de preferências compartilhadas para a atividade. Como ele recupera um arquivo padrão de compartilhadas que pertence à atividade, não é necessário fornecer um nome.

Por exemplo, o código abaixo 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 ao app:

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

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 claramente identificado para o app. Uma maneira fácil de fazer isso é usar o ID do aplicativo como prefixo do 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():

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

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

Cuidado: os modos MODE_WORLD_READABLE e MODE_WORLD_WRITEABLE foram descontinuados desde o nível 17 da API. A partir da versão 7.0 (nível 24 da API), o Android vai gerar uma SecurityException se você os usar. Caso o app precise compartilhar arquivos particulares com outros apps, ele pode 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, é preciso usar getDefaultSharedPreferences() a fim de acessar o arquivo de preferências compartilhadas padrão de todo o app. Veja mais informações no Guia para desenvolvedores sobre configurações.

Gravar em preferências compartilhadas

Para gravar em um arquivo de preferências compartilhadas, crie um SharedPreferences.Editor chamando edit() nas 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:

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

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

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

Ler de preferências compartilhadas

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

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)

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);