Personnaliser vos paramètres Fait partie d'Android Jetpack.
Ce document explique comment personnaliser des objets Preference
dans votre hiérarchie.
Rechercher vos préférences
Pour accéder à un Preference
individuel, par exemple pour obtenir ou définir une valeur Preference
, utilisez PreferenceFragmentCompat.findPreference()
.
Cette méthode recherche un Preference
dans l'ensemble de la hiérarchie à l'aide de la clé donnée.
Par exemple, pour accéder à un EditTextPreference
avec une clé de "signature"
, procédez comme suit:
<EditTextPreference app:key="signature" app:title="Your signature"/>
Récupérez ce Preference
à l'aide du code suivant:
Kotlin
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.preferences, rootKey) val signaturePreference: EditTextPreference? = findPreference("signature") // Do something with this preference. }
Java
@Override public void onCreatePreferences(Bundle savedInstanceState, String rootKey) { setPreferencesFromResource(R.xml.preferences, rootKey); EditTextPreference signaturePreference = findPreference("signature"); // Do something with this preference. }
Contrôler la visibilité des préférences
Vous pouvez contrôler les objets Preference
visibles par l'utilisateur lorsqu'il accède à un écran de paramètres. Par exemple, si une Preference
spécifique n'est pertinente que lorsqu'une fonctionnalité correspondante est activée, vous pouvez masquer cette Preference
lorsque la fonctionnalité est désactivée.
Pour afficher une Preference
uniquement lorsqu'une condition est remplie, définissez d'abord la visibilité Preference
sur "false" dans le fichier XML, comme illustré dans l'exemple suivant:
<EditTextPreference app:key="signature" app:title="Your signature" app:isPreferenceVisible="false"/>
Dans onCreatePreferences()
, affichez Preference
lorsque la condition correspondante est remplie:
Kotlin
override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) { setPreferencesFromResource(R.xml.preferences, rootKey) if(/*some feature*/) { val signaturePreference: EditTextPreference? = findPreference("signature") signaturePreference?.isVisible = true } }
Java
@Override public void onCreatePreferences(Bundle savedInstanceState, String rootKey) { setPreferencesFromResource(R.xml.preferences, rootKey); if(/*some feature*/) { EditTextPreference signaturePreference = findPreference("signature"); if (signaturePreference != null) { signaturePreference.setVisible(true); } } }
Mise à jour dynamique des résumés
Un Preference
qui conserve les données doit afficher la valeur actuelle dans son récapitulatif pour aider l'utilisateur à mieux comprendre l'état actuel de l'Preference
. Par exemple, un EditTextPreference
doit afficher la valeur de texte enregistrée, et un ListPreference
doit afficher l'entrée de liste sélectionnée. Vous pouvez également avoir des objets Preference
qui doivent mettre à jour leur résumé en fonction de l'état interne ou externe de l'application, par exemple un Preference
qui affiche un numéro de version. Pour ce faire, utilisez un SummaryProvider
.
Utiliser un SimpleSummaryProvider
ListPreference
et EditTextPreference
incluent des implémentations SummaryProvider
simples qui affichent automatiquement la valeur Preference
enregistrée en tant que résumé. Si aucune valeur n'est enregistrée, la mention "Non défini" s'affiche.
Pour activer ces implémentations à partir d'un fichier XML, définissez app:useSimpleSummaryProvider="true"
.
Dans le code, vous pouvez également utiliser ListPreference.SimpleSummaryProvider.getInstance()
et EditTextPreference.SimpleSummaryProvider.getInstance()
pour obtenir l'instance SummaryProvider
simple, puis la définir sur Preference
, comme illustré dans l'exemple suivant:
Kotlin
listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance() editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()
Java
listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance()); editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());
Utiliser un SummaryProvider personnalisé
Vous pouvez créer votre propre SummaryProvider
et remplacer provideSummary()
pour personnaliser le résumé chaque fois qu'il est demandé par Preference
. Par exemple, l'élément EditTextPreference
suivant affiche la longueur de sa valeur enregistrée sous forme de résumé:
Par exemple, supposons que l'élément EditTextPreference
suivant s'affiche:
<EditTextPreference app:key="counting" app:title="Counting preference"/>
Dans onCreatePreferences()
, vous pouvez créer un nouveau SummaryProvider
et remplacer provideSummary()
pour renvoyer le résumé à afficher:
Kotlin
val countingPreference: EditTextPreference? = findPreference("counting") countingPreference?.summaryProvider = SummaryProvider<EditTextPreference> { preference -> val text = preference.text if (text.isNullOrEmpty()) { "Not set" } else { "Length of saved value: " + text.length } }
Java
EditTextPreference countingPreference = findPreference("counting"); if (countingPreference != null) { countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() { @Override public CharSequence provideSummary(EditTextPreference preference) { String text = preference.getText(); if (TextUtils.isEmpty(text) || text == null){ return "Not set"; } return "Length of saved value: " + text.length(); } }); }
Le résumé Preference
affiche la longueur de la valeur enregistrée ou "Non défini" s'il n'existe aucune valeur enregistrée.
Personnaliser une boîte de dialogue EditTextPreference
Dans une boîte de dialogue EditTextPreference
, vous pouvez personnaliser le comportement des champs de texte en associant un OnBindEditTextListener
.
Cet écouteur est appelé lorsque l'utilisateur voit la boîte de dialogue.
Par exemple, vous pouvez personnaliser une boîte de dialogue pour qu'elle n'accepte que des chiffres. Commencez par créer le EditTextPreference
:
<EditTextPreference app:key="number" app:title="Numbers only preference"/>
Ensuite, dans onCreatePreferences()
, créez un objet OnBindEditTextListener
et remplacez onBindEditText()
pour personnaliser l'élément EditText
lorsqu'il est présenté à l'utilisateur.
Kotlin
val numberPreference: EditTextPreference? = findPreference("number") numberPreference?.setOnBindEditTextListener { editText -> editText.inputType = InputType.TYPE_CLASS_NUMBER }
Java
EditTextPreference numberPreference = findPreference("number"); if (numberPreference != null) { numberPreference.setOnBindEditTextListener( new EditTextPreference.OnBindEditTextListener() { @Override public void onBindEditText(@NonNull EditText editText) { editText.setInputType(InputType.TYPE_CLASS_NUMBER); } }); }
Désormais, lorsque la boîte de dialogue est présentée à l'utilisateur, le clavier s'ouvre en mode numérique uniquement. L'utilisateur ne peut donc saisir que des chiffres dans EditText
.
Actions souhaitées
Lorsqu'un utilisateur appuie sur un Preference
, il peut effectuer une action spécifique. Par exemple, un élément Preference
peut servir de lien vers une partie distincte de votre application. Pour ajouter une action à un élément Preference
, vous pouvez définir un élément Intent
directement sur l'élément Preference
ou définir un élément OnPreferenceClickListener
pour une logique plus spécifique.
Définir un intent
Vous pouvez définir un Intent
sur une Preference
pour lancer une nouvelle Fragment
, une nouvelle Activity
ou une application distincte chaque fois que l'utilisateur appuie sur Preference
. Cela revient à utiliser Context.startActivity()
avec un Intent
donné.
Vous pouvez définir un Intent
en XML à l'aide d'une balise <intent>
imbriquée. L'exemple suivant définit une Intent
qui lance une Activity
:
<Preference app:key="activity" app:title="Launch activity"> <intent android:targetPackage="com.example" android:targetClass="com.example.ExampleActivity"/> </Preference>
Vous pouvez également utiliser setIntent()
directement sur un Preference
, comme suit:
Kotlin
val intent = Intent(context, ExampleActivity::class.java) activityPreference.setIntent(intent)
Java
Intent intent = new Intent(getContext(), ExampleActivity.class); activityPreference.setIntent(intent);
Vous pouvez également inclure des extras avec un Intent
au format XML:
<Preference app:key="activity" app:title="Launch activity"> <intent android:targetPackage="com.example" android:targetClass="com.example.ExampleActivity"> <extra android:name="example_key" android:value="example_value"/> </intent> </Preference>
Voici un exemple de Preference
avec un Intent
qui lance une page Web:
<Preference app:key="webpage" app:title="View webpage"> <intent android:action="android.intent.action.VIEW" android:data="http://www.google.com" /> </Preference>
Kotlin
val intent = Intent(Intent.ACTION_VIEW) intent.data = Uri.parse("http://www.google.com") val webpagePreference = findPreference("webpage") webpagePreference?.intent = intent
Java
Intent intent = new Intent(Intent.ACTION_VIEW); intent.setData(Uri.parse("http://www.google.com")); webpagePreference.setIntent(intent);
OnPreferenceClickListener
Vous pouvez définir un OnPreferenceClickListener
sur un Preference
, ce qui ajoute un rappel à onPreferenceClick()
lorsque l'utilisateur appuie sur l'Preference
. Par exemple, vous pouvez utiliser l'écouteur pour accéder à un autre élément Fragment
ou Activity
si vous disposez d'une logique plus complexe pour gérer la navigation.
Pour définir un élément OnPreferenceClickListener
, utilisez un code semblable à celui-ci:
Kotlin
onClickPreference.setOnPreferenceClickListener({ // Do something. true })
Java
onClickPreference.setOnPreferenceClickListener(preference -> { // Do something. return true; });