Enregistrer des paires clé/valeur

Si vous souhaitez enregistrer une collection de clés/valeurs dont la taille est relativement petite, utilisez les API SharedPreferences. Un objet SharedPreferences renvoie vers un fichier contenant des paires clé/valeur et fournit des méthodes simples pour les lire et les écrire. Chaque fichier SharedPreferences est géré par le framework. Il peut être privé ou partagé.

Cette page vous explique comment utiliser les API SharedPreferences pour stocker et récupérer des valeurs simples.

Remarque : Les API SharedPreferences sont destinées à la lecture et à l'écriture de paires clé/valeur. Ne les confondez avec les API Preference, qui vous permettent de créer une interface utilisateur pour les paramètres de votre application (bien qu'elles utilisent également SharedPreferences pour enregistrer les paramètres utilisateur). Pour en savoir plus sur les API Preference, consultez le guide du développeur spécifique aux paramètres.

Générer un handle vers les préférences partagées

Vous pouvez créer un fichier de préférences partagées ou accéder à un fichier existant en appelant l'une des méthodes suivantes :

• getSharedPreferences() : utilisez cette option si vous avez besoin de plusieurs fichiers de préférences partagées identifiés par leur nom, que vous spécifierez avec le premier paramètre. Vous pouvez appeler celle option à partir de n'importe quel objet Context dans votre application.
• getPreferences() : utilisez cette option à partir d'un élément Activity si vous n'avez besoin que d'un seul fichier de préférences partagées pour l'activité. Étant donné que cette option récupère un fichier de préférences partagées par défaut appartenant à l'activité, vous n'avez pas besoin de fournir un nom.

Par exemple, le code suivant accède au fichier de préférences partagées identifié par la chaîne de ressources R.string.preference_file_key et l'ouvre en mode privé, de sorte que le fichier ne soit accessible que par votre application :

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

Lorsque vous nommez des fichiers de préférences partagées, vous devez attribuer un nom unique à votre application. Pour ce faire, il vous suffit de faire précéder le nom de votre fichier de l'ID d'application ("com.example.myapp.PREFERENCE_FILE_KEY", par exemple).

Si vous n'avez besoin que d'un seul fichier de préférences partagées pour votre activité, vous pouvez également utiliser la méthode getPreferences() :

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

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

Attention : Les modes MODE_WORLD_READABLE et MODE_WORLD_WRITEABLE sont obsolètes depuis le niveau d'API 17. À partir d'Android 7.0 (niveau d'API 24), Android génère une exception SecurityException si vous les utilisez. Si votre application doit partager des fichiers privés avec d'autres applications, elle peut utiliser FileProvider avec FLAG_GRANT_READ_URI_PERMISSION. Pour en savoir plus, consultez également Partager des fichiers.

Si vous enregistrez les paramètres de l'application avec l'API SharedPreferences, utilisez plutôt getDefaultSharedPreferences() afin d'obtenir le fichier de préférences partagées par défaut pour l'ensemble de votre application. Pour en savoir plus, consultez le guide du développeur spécifique aux paramètres.

Écrire dans les préférences partagées

Pour écrire dans un fichier de préférences partagées, créez un élément SharedPreferences.Editor en appelant edit() au niveau de SharedPreferences.

Remarque : Pour modifier les préférences partagées de manière plus sécurisée, appelez la méthode edit() au niveau d'un objet EncryptedSharedPreferences et non au niveau d'un objet SharedPreferences. Pour en savoir plus, consultez le guide sur l'utilisation sécurisée des données.

Transmettez les clés et les valeurs que vous souhaitez écrire à l'aide de méthodes telles que putInt() et putString(). Appelez ensuite apply() ou commit() pour enregistrer les modifications. Exemple :

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() modifie immédiatement l'objet SharedPreferences en mémoire, mais écrit les mises à jour sur le disque de manière asynchrone. Vous pouvez également utiliser commit() pour écrire les données sur le disque de manière synchrone. Cependant, comme commit() est synchrone, évitez de l'appeler à partir de votre thread principal, car cela pourrait suspendre le rendu de l'interface utilisateur.

Lire à partir des préférences partagées

Pour récupérer les valeurs d'un fichier de préférences partagées, appelez des méthodes telles que getInt() et getString(), en fournissant la clé correspondant à la valeur souhaitée, et éventuellement une valeur par défaut à renvoyer si cette clé est absente. Exemple :

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