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 qualquerContext
no app.getPreferences()
: use esse método em umaActivity
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:
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 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()
:
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
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:
Kotlin
val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return with (sharedPref.edit()) { putInt(getString(R.string.saved_high_score_key), newHighScore) apply() }
Java
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:
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);