Composants et attributs des préférences Fait partie d'Android Jetpack.

Cet article décrit certains des composants et attributs Preference les plus couramment utilisés lors de la création d'un écran de paramètres.

Composants des préférences

Cette section décrit les composants Preference courants. Pour en savoir plus, consultez les pages de référence correspondantes à chaque composant.

Infrastructure des préférences

PreferenceFragmentCompat : un Fragment qui gère l'affichage d'une hiérarchie interactive d'objets Preference.

Conteneurs de préférences

PreferenceScreen : conteneur de niveau supérieur qui représente un écran de paramètres. Il s'agit du composant racine de votre hiérarchie Preference.

PreferenceCategory : conteneur permettant de regrouper des éléments Preferences similaires. Une PreferenceCategory affiche un titre de catégorie et sépare visuellement les groupes de Preferences.

Préférences individuelles

Preference : élément de base représentant un paramètre individuel. Si un Preference est défini pour être persistant, il est associé à une paire clé-valeur qui contient le choix de l'utilisateur concernant le paramètre, qui est accessible ailleurs dans l'application.

EditTextPreference : un Preference qui conserve une valeur String. Les utilisateurs peuvent appuyer sur Preference pour lancer une boîte de dialogue contenant le champ de texte qui leur permet de modifier la valeur persistante.

ListPreference : un Preference qui persiste une valeur de chaîne. Les utilisateurs peuvent modifier cette valeur dans une boîte de dialogue contenant une liste de cases d'option avec les libellés correspondants.

MultiSelectListPreference : Preference qui persiste un ensemble de chaînes. Les utilisateurs peuvent modifier ces valeurs dans une boîte de dialogue contenant une liste de cases à cocher avec les libellés correspondants.

SeekBarPreference : Preference qui conserve une valeur entière. Vous pouvez modifier cette valeur en faisant glisser une barre de recherche correspondante affichée dans la mise en page Preference.

SwitchPreferenceCompat : Preference qui persiste une valeur booléenne. Cette valeur peut être modifiée en interagissant avec le widget de commutateur correspondant ou en appuyant sur la mise en page Preference.

CheckBoxPreference : Preference qui persiste une valeur booléenne. Vous pouvez modifier cette valeur en interagissant avec la case à cocher correspondante ou en appuyant sur la mise en page Preference.

Attributs de préférences

Vous trouverez ci-dessous certains des attributs les plus couramment utilisés qui configurent l'apparence et le comportement de Preference.

Attributs génériques

title

Valeur String qui représente le titre de Preference.

Exemple:app:title="Title"

summary

Une valeur String qui représente le résumé Preference.

Exemple:app:summary="Summary"

icon

Un élément Drawable qui représente l'icône Preference.

Exemple:app:icon="@drawable/ic_camera"

key

Une valeur String qui représente la clé utilisée pour conserver la valeur du Preference associé. Une clé vous permet de personnaliser davantage Preference pendant l'exécution. Vous devez définir une clé pour chaque Preference de votre hiérarchie.

Exemple:app:key="key"

enabled

Valeur booléenne indiquant si les utilisateurs peuvent interagir avec Preference. Lorsque cette valeur est false, l'élément Preference est grisé et les utilisateurs ne peuvent pas interagir avec lui. La valeur par défaut est true.

Exemple:app:enabled="false"

selectable

Valeur booléenne indiquant si les utilisateurs peuvent interagir avec Preference. La valeur par défaut est true.

Exemple:app:selectable="false"

isPreferenceVisible

Valeur booléenne indiquant si une catégorie Preference ou Preference est visible. Cela équivaut à appeler setVisible().

Exemple:app:isPreferenceVisible="false"

defaultValue

Représente la valeur par défaut d'un élément Preference. Cette valeur est définie et conservée lorsqu'aucune autre valeur persistante n'est trouvée pour ce Preference. Le type de valeur dépend de la Preference associée.

Exemple:app:defaultValue="true"

dependency

Représente la clé d'un SwitchPreferenceCompat qui contrôle l'état de ce Preference. Lorsque le bouton bascule correspondant est désactivé, ce Preference est désactivé et ne peut pas être modifié.

Exemple:app:dependency="parent"

Attributs PreferenceCategory

initialExpandedChildrenCount

Valeur entière qui permet le comportement Preference extensible. Cette valeur représente le nombre maximal d'enfants à afficher dans PreferenceGroup. Les éléments enfants supplémentaires sont réduits et peuvent être affichés en appuyant sur le bouton "Développer". Par défaut, cette valeur est Integer.MAX_VALUE, et tous les enfants sont affichés.

Avertissement:Veillez à définir une clé sur PreferenceCategory si vous utilisez cet attribut afin que l'état soit correctement enregistré et restauré lorsque la configuration change (par exemple, lors de la rotation de l'écran).

Exemple:app:initialExpandedChildrenCount="0"

Attributs ListPreference et MultiSelectListPreference

entries

Tableau de chaînes correspondant aux entrées de liste à afficher à l'utilisateur. Chacune de ces valeurs correspond, par index, au tableau de valeurs conservées en interne. Par exemple, lorsqu'un utilisateur sélectionne la première entrée de la liste, le premier élément du tableau de valeurs correspondant est conservé.

Exemple:app:entries="@array/entries"

Avertissement:Assurez-vous que la longueur des deux tableaux est identique et que les index de chaque tableau correspondent à la bonne paire entrée / valeur.

entryValues

Tableau d'entrées à conserver. Chacune de ces valeurs correspond par index au tableau d'entrées de liste présentées à l'utilisateur.

Exemple:app:entryValues="@array/values"