Utiliser les valeurs de préférence enregistrées Inclus dans Android Jetpack.

Ce document explique comment stocker et utiliser Les valeurs Preference enregistrées par la bibliothèque des préférences.

Stockage des données des préférences

Cette section décrit comment un Preference peut conserver des données.

SharedPreferences

Par défaut, un Preference utilise SharedPreferences pour économiser valeurs. L'API SharedPreferences permet de lire et d'écrire à partir d'un fichier enregistré lors des sessions d'application. La La bibliothèque de préférences utilise une instance SharedPreferences privée afin que seules vos données application peut y accéder.

Par exemple, supposons que SwitchPreferenceCompat:

<SwitchPreferenceCompat
        app:key="notifications"
        app:title="Enable message notifications"/>

Lorsqu'un utilisateur active cet interrupteur le fichier SharedPreferences les mises à jour avec une paire clé-valeur "notifications" : "true". La clé utilisée est la identique à celle définie pour Preference.

Pour en savoir plus sur l'API SharedPreferences, consultez la section Enregistrer une clé-valeur données.

Pour en savoir plus sur les différentes manières de stocker des données sur Android, consultez la section Données et le stockage de fichiers.

PreferenceDataStore

Bien que la bibliothèque Preference conserve les données avec SharedPreferences par défaut, les SharedPreferences ne sont pas toujours une solution idéale. Par exemple, si votre application nécessite qu'un utilisateur se connecte, vous pouvez conserver les paramètres de l'application dans le cloud afin qu'ils soient répercutés d'autres appareils et plates-formes. De même, si votre application dispose d'une configuration spécifiques à l'appareil, chaque utilisateur de l'appareil dispose de paramètres distincts, ce qui fait de SharedPreferences une solution qui n'est pas idéale.

Un PreferenceDataStore vous permet d'utiliser un backend de stockage personnalisé pour conserver les valeurs Preference. Pour plus plus d'informations, consultez la section Utiliser un datastore personnalisé.

Lire les valeurs des préférences

Pour récupérer l'objet SharedPreferences utilisé, appelez PreferenceManager.getDefaultSharedPreferences() Bien que cette méthode fonctionne partout dans votre application, nous vous recommandons vous divisez votre application en couches. Pour en savoir plus, consultez la section Données calque.

Par exemple, pour un EditTextPreference dont la clé est "signature", comme ce qui suit:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

Vous pouvez récupérer la valeur enregistrée pour ce Preference de manière globale, comme suit:

val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this /* Activity context */)
val name = sharedPreferences.getString("signature", "")

SharedPreferences sharedPreferences =
        PreferenceManager.getDefaultSharedPreferences(this /* Activity context */);
String name = sharedPreferences.getString("signature", "");

Écouter les modifications apportées aux valeurs des préférences

Pour écouter les modifications apportées aux valeurs Preference, vous avez le choix entre deux interfaces:

• Preference.OnPreferenceChangeListener
• SharedPreferences.OnSharedPreferenceChangeListener

Le tableau suivant montre les différences entre les deux interfaces:

Implémenter OnPreferenceChangeListener

L'implémentation d'un OnPreferenceChangeListener vous permet d'écouter un événement en attente la valeur d'un Preference. Vous pouvez ensuite vérifier si la modification se produit. Par exemple, le code suivant montre comment écouter une modification apportée au Valeur d'un EditTextPreference avec une clé de "name":

override fun onPreferenceChange(preference: Preference, newValue: Any): Boolean {
    Log.e("preference", "Pending Preference value is: $newValue")
    return true
}

@Override
public boolean onPreferenceChange(Preference preference, Object newValue) {
    Log.e("preference", "Pending Preference value is: " + newValue);
    return true;
}

Vous devez ensuite définir cet écouteur directement avec setOnPreferenceChangeListener(), comme suit:

preference.onPreferenceChangeListener = ...

preference.setOnPreferenceChangeListener(...);

Implémenter OnSharedPreferenceChangeListener

Lorsque vous conservez des valeurs Preference à l'aide de SharedPreferences, vous pouvez également utiliser un SharedPreferences.OnSharedPreferenceChangeListener pour écouter les modifications. Cela vous permet d'écouter quand les valeurs enregistrées par votre Preference sont modifiées. par exemple lors de la synchronisation des paramètres avec un serveur. L'exemple suivant montre comment écouter une modification de la valeur d'un EditTextPreference avec une clé de "name":

override fun onSharedPreferenceChanged(sharedPreferences: SharedPreferences, key: String) {
    if (key == "signature") {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""))
    }
}

@Override
public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals("signature")) {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""));
    }
}

Enregistrez l'écouteur à l'aide de registerOnSharedPreferenceChangedListener(), comme suit:

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(...);

    val listener: SharedPreferences.OnSharedPreferenceChangeListener =
            SharedPreferences.OnSharedPreferenceChangeListener {...}
    

    SharedPreferences.OnSharedPreferenceChangeListener listener =
            new SharedPreferences.OnSharedPreferenceChangeListener() {...}
    

Pour une gestion appropriée du cycle de vie dans Activity ou Fragment, enregistrez et annuler l'enregistrement de cet écouteur dans les rappels onResume() et onPause(), comme indiqué ci-dessous ; dans l'exemple suivant:

override fun onResume() {
    super.onResume()
    preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(this)
}

override fun onPause() {
    super.onPause()
    preferenceManager.sharedPreferences.unregisterOnSharedPreferenceChangeListener(this)
}

@Override
public void onResume() {
    super.onResume();
    getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(this);
}

@Override
public void onPause() {
    super.onPause();
    getPreferenceManager().getSharedPreferences().unregisterOnSharedPreferenceChangeListener(this);
}

Utiliser un datastore personnalisé

Bien que nous recommandions de conserver les objets Preference à l'aide de SharedPreferences, vous pouvez aussi utiliser un datastore personnalisé. Un datastore personnalisé peut s'avérer utile l'application conserve les valeurs dans une base de données ou si les valeurs sont spécifiques à un appareil, comme indiqué dans les exemples suivants.

Implémenter le datastore

Pour implémenter un magasin de données personnalisé, créez une classe qui étend PreferenceDataStore L'exemple suivant crée un datastore qui gère Valeurs String:

class DataStore : PreferenceDataStore() {
    override fun putString(key: String, value: String?) {
        // Save the value somewhere.
    }

    override fun getString(key: String, defValue: String?): String? {
        // Retrieve the value.
    }
}

public class DataStore extends PreferenceDataStore {
    @Override
    public void putString(String key, @Nullable String value) {
        // Save the value somewhere.
    }
    @Override
    @Nullable
    public String getString(String key, @Nullable String defValue) {
        // Retrieve the value.
    }
}

Exécuter les opérations chronophages en dehors du thread principal pour éviter de bloquer l'utilisateur de commande. Étant donné qu'il est possible que le Fragment ou le Activity contenant le datastore à détruire en cas de persistance d'une valeur, sérialisez les données pour ne perdez aucune valeur modifiée par l'utilisateur.

Activer le datastore

Après avoir implémenté votre datastore, définissez le nouveau datastore dans onCreatePreferences() afin que les objets Preference conservent les valeurs avec datastore au lieu d'utiliser la valeur par défaut SharedPreferences. Vous pouvez activer datastore pour chaque Preference ou pour l'ensemble de la hiérarchie.

Pour activer un datastore personnalisé pour un Preference spécifique, appelez setPreferenceDataStore() sur Preference, comme illustré dans l'exemple suivant:

val preference: Preference? = findPreference("key")
preference?.preferenceDataStore = dataStore

Preference preference = findPreference("key");
if (preference != null) {
    preference.setPreferenceDataStore(dataStore);
}

Pour activer un datastore personnalisé pour une hiérarchie entière, appelez setPreferenceDataStore() sur le PreferenceManager:

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

PreferenceManager preferenceManager = getPreferenceManager();
preferenceManager.setPreferenceDataStore(dataStore);

Un datastore défini pour une Preference spécifique remplace tout datastore qui est défini pour la hiérarchie correspondante. Dans la plupart des cas, vous définissez un datastore toute la hiérarchie.