Paramètres Inclus dans Android Jetpack.

Les paramètres permettent aux utilisateurs de modifier les fonctionnalités et le comportement d'une application. Les paramètres peuvent affectent le comportement en arrière-plan, comme la fréquence à laquelle l'application synchronise les données dans le cloud, ou élargir leur portée, par exemple en modifiant le contenu présentation de l'interface utilisateur.

Remarque :Ce document explique comment utiliser la préférence AndroidX. bibliothèque. À partir d'Android 10, la bibliothèque android.preference de la plate-forme est obsolète.

Pour intégrer des paramètres configurables par l'utilisateur dans votre application, utilisez AndroidX Bibliothèque de préférences. Cette bibliothèque gère l'interface utilisateur et interagit avec de façon à ne définir que les paramètres individuels configurer. La bibliothèque a un thème Material Design qui offre expérience utilisateur cohérente sur tous les appareils et versions d'OS.

Premiers pas

Un Preference est le bâtiment de base de la bibliothèque des préférences. Un écran de paramètres contient un Preference hiérarchie. Vous pouvez définir cette hiérarchie en tant que ressource XML ou créer une hiérarchie dans le code.

Les sections suivantes décrivent comment créer un écran de paramètres simple à l'aide de la méthode Bibliothèque de préférences AndroidX.

Avant de commencer, ajoutez la dépendance de la bibliothèque des préférences à votre build.gradle :

Groovy

dependencies {
    implementation "androidx.preference:preference-ktx:1.2.0"
}

Kotlin

dependencies {
    implementation("androidx.preference:preference-ktx:1.2.0")
}

Après une synchronisation Gradle, vous pouvez passer à la partie XML de la tâche.

Créer une hiérarchie

Dans votre projet, accédez au dossier res/xml, créez un fichier preferences.xml, et ajoutez-y le code suivant:

<PreferenceScreen
    xmlns:app="http://schemas.android.com/apk/res-auto">

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

    <Preference
        app:key="feedback"
        app:title="Send feedback"
        app:summary="Report technical issues or suggest new features"/>

</PreferenceScreen>

Cette hiérarchie contient deux objets Preference : SwitchPreferenceCompat qui permet aux utilisateurs d'activer et de désactiver un paramètre, ainsi qu'un Preference de base sans .

Lors de la création d'une hiérarchie, chaque Preference doit avoir une clé unique.

Remarque :Consultez la section Conception des paramètres Android Consignes pour obtenir des recommandations sur l'organisation de l'écran des paramètres.

Gonfler la hiérarchie

Pour gonfler une hiérarchie à partir d'un attribut XML, créez un PreferenceFragmentCompat, ignorer onCreatePreferences(), et fournissez la ressource XML à gonfler, comme illustré dans l'exemple suivant:

Kotlin

class MySettingsFragment : PreferenceFragmentCompat() {
    override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
        setPreferencesFromResource(R.xml.preferences, rootKey)
    }
}

Java

public class MySettingsFragment extends PreferenceFragmentCompat {
    @Override
    public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
        setPreferencesFromResource(R.xml.preferences, rootKey);
    }
}

Vous pouvez ensuite ajouter ce Fragment à votre Activity, comme vous le feriez avec n'importe quelle autre Fragment:

Kotlin

class MySettingsActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        supportFragmentManager
                .beginTransaction()
                .replace(R.id.settings_container, MySettingsFragment())
                .commit()
    }
}

Java

public class MySettingsActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        getSupportFragmentManager()
                .beginTransaction()
                .replace(R.id.settings_container, new MySettingsFragment())
                .commit();
    }
}

Le résultat est illustré dans l'image suivante:

Figure 1 : Un écran de paramètres créé à l'aide de deux Preference d'objets.

Surveiller les préférences

Vous pouvez obtenir un événement lorsqu'une préférence change en enregistrant un écouteur pour comme suit:

Kotlin

findPreference<SwitchPreferenceCompat>("notifications")
    ?.setOnPreferenceChangeListener { _, newValue ->
        Log.d("Preferences", "Notifications enabled: $newValue")
        true // Return true if the event is handled.
    }

findPreference<Preference>("feedback")
    ?.setOnPreferenceClickListener {
        Log.d("Preferences", "Feedback was clicked")
        true // Return true if the click is handled.
    }

Java

SwitchPreferenceCompat notificationsPref = findPreference("notifications");

if (notificationsPref != null) {
    notificationsPref.setOnPreferenceChangeListener((preference, newValue) -> {
        Log.d("Preferences", String.format("Notifications enabled: %s", newValue));
        return true; // Return true if the event is handled.
    });
}

Preference feedbackPref = findPreference("feedback");

if (feedbackPref != null) {
    feedbackPref.setOnPreferenceClickListener((preference) -> {
        Log.d("Preferences", "Feedback was clicked");
        return true; // Return true if the event is handled.
    });
}

Lire la valeur de préférence actuelle

PreferenceFragmentCompat masque une grande partie des machines impliquées dans l'enregistrement et lisant les préférences. Cependant, tout est stocké à l'aide SharedPreferences, et vous pouvez lire ces valeurs comme vous le faites habituellement avec SharedPreferences:

Kotlin

val preferences = PreferenceManager.getDefaultSharedPreferences(this).all

preferences.forEach {
    Log.d("Preferences", "${it.key} -> ${it.value}")
}

Java

var preferences = PreferenceManager.getDefaultSharedPreferences(context).getAll();

preferences.forEach((key, value) ->{
    Log.d("Preferences", String.format("%s -> %s", key, value));
});

L'extrait précédent obtient une instance de SharedPreferences par défaut pour l'application, accède à toutes les valeurs stockées, les passe en boucle et les imprime Logcat.