Preference

Créez des écrans de paramètres interactifs sans avoir à interagir avec l'espace de stockage de l'appareil ni à gérer l'interface utilisateur.
Dernière mise à jour Version stable Version finale Version bêta Version alpha
26 juillet 2023 1.2.1 - - -

Déclarer des dépendances

Pour ajouter une dépendance à Preference, vous devez ajouter le dépôt Maven Google à votre projet. Pour en savoir plus, consultez la section Dépôt Maven de Google.

Ajoutez les dépendances des artefacts dont vous avez besoin dans le fichier build.gradle de votre application ou module :

Groovy

dependencies {
    def preference_version = "1.2.1"

    // Java language implementation
    implementation "androidx.preference:preference:$preference_version"
    // Kotlin
    implementation "androidx.preference:preference-ktx:$preference_version"
}

Kotlin

dependencies {
    val preference_version = "1.2.1"

    // Java language implementation
    implementation("androidx.preference:preference:$preference_version")
    // Kotlin
    implementation("androidx.preference:preference-ktx:$preference_version")
}

Pour en savoir plus sur les dépendances, consultez la page Ajouter des dépendances de compilation.

Commentaires

Vos commentaires nous aident à améliorer Jetpack. N'hésitez pas à nous contacter si vous découvrez de nouveaux problèmes ou si vous avez des idées pour améliorer cette bibliothèque. Veuillez consulter les problèmes existants de cette bibliothèque avant d'en signaler un nouveau. Vous pouvez ajouter votre vote à un problème existant en cliquant sur le bouton en forme d'étoile.

Signaler un nouveau problème

Pour en savoir plus, consultez la documentation sur l'outil Issue Tracker.

Version 1.2

Version 1.2.1

26 juillet 2023

Publication d'androidx.preference:preference:1.2.1. Liste des commits de la version 1.2.1

Correction de bugs

  • PreferenceHeaderFragmentCompat gère désormais correctement le bouton "Retour" du système lorsqu'il est utilisé dans un ComponentDialog ou lors de l'utilisation de bibliothèques telles que @AndroidEntryPoint de Hilt qui encapsulent le Context du fragment.
  • Les préférences dépendent désormais de Activity 1.5.1. (Ie5d22).
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment propage désormais header.extras en tant qu'arguments Fragment.

Version 1.2.0

26 janvier 2022

Publication d'androidx.preference:preference:1.2.0 et androidx.preference:preference-ktx:1.2.0. Liste des commits de la version 1.2.0

Changements importants depuis la version 1.1.0

  • Ajout de PreferenceHeaderFragmentCompat pour la préférence de double volet, qui s'adapte automatiquement à la taille de l'appareil utilisé et peut donc être utilisé sur des téléphones, des pliables et des tablettes. Le volet d'en-tête est fourni en remplaçant la méthode onCreatePreferenceHeader() sur PreferenceHeaderFragmentCompat. Toute <Preference> dans l'en-tête PreferenceFragmentCompat utilisant app:fragment entraînera l'affichage de ce fragment dans le deuxième volet Détails. Vous pouvez personnaliser le fragment de détails initial qui doit s'afficher avant qu'une préférence ne soit sélectionnée manuellement en remplaçant onCreateInitialDetailFragment(). L'implémentation par défaut renvoie la première préférence pour laquelle un fragment est défini.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • Ajout d'annotations concernant la possibilité d'une valeur nulle à de nombreuses API qui ne spécifiaient pas @NonNull ni @Nullable. Il s'agit d'une modification potentiellement destructive de la source Kotlin si la possibilité de valeur nulle que vous aviez choisie dans votre code Kotlin ne correspond pas à la possibilité de valeur nulle désormais définie.

  • PreferenceFragmentCompat recherche maintenant les implémentations des interfaces OnPreferenceStartFragmentCallback, OnNavigateToScreenListener et OnDisplayPreferenceDialogListener sur les fragments parents avant de vérifier si le contexte ou l'activité de l'hébergement implémente ces interfaces.

Version 1.2.0-rc01

15 décembre 2021

Publication d'androidx.preference:preference:1.2.0-rc01 et androidx.preference:preference-ktx:1.2.0-rc01 sans aucune modification par rapport à la version 1.2.0-beta01. Liste des commits de la version 1.2.0-rc01

Version 1.2.0-beta01

17 novembre 2021

Publication d'androidx.preference:preference:1.2.0-beta01 et androidx.preference:preference-ktx:1.2.0-beta01 sans aucune modification de Preference par rapport à la version 1.2.0-alpha02. Liste des commits de la version 1.2.0-beta01

Version 1.2.0-alpha02

3 novembre 2021

Publication d'androidx.preference:preference:1.2.0-alpha02 et androidx.preference:preference-ktx:1.2.0-alpha02. Liste des commits de la version 1.2.0-alpha02

Modifications apportées à l'API

  • Ajout d'annotations concernant la possibilité d'une valeur nulle à de nombreuses API qui ne spécifiaient pas @NonNull ni @Nullable. (I04252, Ie2cc0)
  • Suppression de l'API openPreference() de PreferenceHeaderFragmentCompat : cette méthode est appelée pour vous et ne doit pas être appelée manuellement. (Ia6989)

Nouveaux comportements

  • Les rappels PreferenceFragmentCompat pour OnNavigateToScreenListener et OnDisplayPreferenceDialogListener suivent désormais le même schéma que OnPreferenceTreeClickListener et recherchent la présence d'écouteurs valides dans la hiérarchie de fragments parents avant de vérifier si le contexte ou l'activité de l'hébergement implémente ces interfaces. (I7ae6c)

Version 1.2.0-alpha01

27 octobre 2021

Publication d'androidx.preference:preference:1.2.0-alpha01 et androidx.preference:preference-ktx:1.2.0-alpha01. Liste des commits de la version 1.2.0-alpha01

Nouvelles fonctionnalités

  • Ajout de PreferenceHeaderFragmentCompat pour la préférence de double volet (I9a2d8)

Nouveaux comportements

  • Les rappels de Preference pour OnPreferenceDisplayDialogCallback, OnPreferenceStartScreenCallback et OnPreferenceStartFragmentCallback peuvent désormais être mis en œuvre dans un contexte autre qu'une activité. La méthode getContext() est vérifiée afin de voir si elle met en œuvre ces rappels avant la vérification de la méthode getActivity(). Si getContext() renvoie une activité (cas courant), il n'y a aucun changement de comportement.

  • L'appel de PreferenceFragmentCompat à onPreferenceTreeClick recherche désormais les implémentations de l'interface OnPreferenceStartFragmentCallback sur les fragments parents avant d'envisager l'implémentation de l'activité. (c64eed)

Version 1.1

Version 1.1.1

15 avril 2020

Publication d'androidx.preference:preference:1.1.1 et androidx.preference:preference-ktx:1.1.1. Liste des commits de la version 1.1.1

Corrections de bugs

  • PreferenceDialogFragmentCompat ne génère plus une IllegalStateException lors du gonflage d'une propriété FragmentContainerView via XML. (b/150051716)

Mises à jour des dépendances

  • Preference dépend maintenant de Fragment 1.2.4. (aosp/1277317)
  • La dépendance preference-ktx dépend désormais de androidx.core:core-ktx:1.1.0 et de androidx.fragment:fragment-ktx:1.2.4, en mettant en miroir les dépendances de l'artefact preference principal, et en s'assurant que la mise à niveau de preference-ktx met à jour les artefacts principaux et les artefacts -ktx des dépendances transitives. (aosp/1277319)

Version 1.1.0

5 septembre 2019

Publication d'androidx.preference:preference:1.1.0 et d'androidx.preference:preference-ktx:1.1.0. Les commits inclus dans cette version sont disponibles sur cette page.

S'il s'agit de la première version 1.1.* vers laquelle vous effectuez une mise à jour, voici une liste concise des modifications plus importantes apportées depuis la dernière version stable, 1.0.0. Le guide des paramètres, un exemple d'application et une présentation lors du sommet des développeurs Android peuvent également vous être utiles.

Changements importants depuis la version 1.0.0

  • PreferenceFragment et d'autres classes utilisant des fragments de framework sont devenues obsolètes. Utilisez plutôt PreferenceFragmentCompat et d'autres classes *compat.
  • Vous pouvez désormais définir un SummaryProvider pour un objet Preference afin de configurer son résumé de manière dynamique chaque fois que l'objet Preference est mis à jour ou devient visible par l'utilisateur. Pour en savoir plus, consultez le guide.
  • Ajout de l'interface EditTextPreference.OnBindEditTextListener. Elle permet de personnaliser l'EditText affiché dans la boîte de dialogue correspondante une fois la boîte de dialogue liée. Il s'agit d'un remplacement direct permettant d'utiliser des attributs tels que android:inputType directement dans EditTextPreference, qui n'est pas compatible avec la bibliothèque AndroidX. Pour en savoir plus, consultez le guide.
  • Ajout de Preference.setCopyingEnabled(). Lorsque ce paramètre est défini, un appui prolongé sur l'objet Preference permet d'afficher un menu contextuel vous permettant de copier le résumé de l'objet Preference.
  • Modification du style de SeekBarPreference pour qu'il corresponde aux spécifications de Material. Consultez le journal des modifications détaillé pour en savoir plus sur les autres modifications apportées à SeekBarPreference.
  • Implémentation d'un grand nombre de corrections de bugs, de mises à jour de styles, de corrections de la compatibilité au niveau de l'API et d'améliorations générales de qualité de vie.

Version 1.1.0-rc01

2 juillet 2019

Publication d'androidx.preference:preference:1.1.0-rc01 et d'androidx.preference:preference-ktx:1.1.0-rc01. Les commits inclus dans cette version sont disponibles sur cette page.

Modifications apportées à l'API

  • Preference#onInitializeAccessibilityNodeInfo est devenu obsolète.
  • Cette méthode envoyait par proxy les informations de nœud d'accessibilité pour un objet Preference spécifique, mais il ne s'agit pas de la bonne couche pour cette personnalisation. Si vous souhaitez modifier les informations d'accessibilité, vous devez remplacer la valeur onBindViewHolder et ajouter directement les informations d'accessibilité à la vue.

Version 1.1.0-beta01

5 juin 2019

Publication d'androidx.preference:preference:1.1.0-beta01 et d'androidx.preference:preference-ktx:1.1.0-beta01. Les commits inclus dans cette version sont disponibles sur cette page.

Changements importants depuis la version 1.1.0

S'il s'agit de la première version 1.1.* vers laquelle vous effectuez une mise à jour, voici une liste concise des modifications plus importantes apportées depuis la dernière version stable, 1.1.0. Le guide des paramètres, un exemple d'application et une présentation lors du sommet des développeurs Android peuvent également vous être utiles.

  • PreferenceFragment et d'autres classes utilisant des fragments de framework sont devenues obsolètes. Utilisez plutôt PreferenceFragmentCompat et d'autres classes *compat.
  • Vous pouvez désormais définir un SummaryProvider pour un objet Preference afin de configurer son résumé de manière dynamique chaque fois que l'objet Preference est mis à jour ou devient visible par l'utilisateur. Pour en savoir plus, consultez le guide.
  • Ajout de l'interface EditTextPreference.OnBindEditTextListener. Elle permet de personnaliser l'EditText affiché dans la boîte de dialogue correspondante une fois la boîte de dialogue liée. Il s'agit d'un remplacement direct permettant d'utiliser des attributs tels que android:inputType directement dans EditTextPreference, qui n'est pas compatible avec la bibliothèque AndroidX. Pour en savoir plus, consultez le guide.
  • Ajout de Preference.setCopyingEnabled(). Lorsque ce paramètre est défini, un appui prolongé sur l'objet Preference permet d'afficher un menu contextuel vous permettant de copier le résumé de l'objet Preference.
  • Modification du style de SeekBarPreference pour qu'il corresponde aux spécifications de Material. Consultez le journal des modifications détaillé pour en savoir plus sur les autres modifications apportées à SeekBarPreference.
  • Implémentation d'un grand nombre de corrections de bugs, de mises à jour de styles, de corrections de la compatibilité au niveau de l'API et d'améliorations générales de qualité de vie.

Modifications de l'API depuis la version 1.1.0-alpha05

  • Suppression de getOnBindEditTextListener de l'API publique. Vous ne devez utiliser setOnBindEditTextListener que pour interagir avec cette API.

Si vous rencontrez des problèmes ou si vous avez des suggestions de nouvelles fonctionnalités, cliquez ici pour nous les communiquer.

Version 1.1.0-alpha05

7 mai 2019

Publication d'androidx.preference:preference:1.1.0-alpha05 et d'androidx.preference:preference-ktx:1.1.0-alpha05. Les commits inclus dans cette version sont disponibles sur cette page.

Nouvelles fonctionnalités

  • Modification du style des objets Preference non sélectionnables : le titre et le résumé ont désormais la même couleur pour indiquer clairement qu'il est impossible d'interagir avec ces éléments et qu'ils ne sont utilisés que pour afficher des informations.
  • Remarque : nous vous conseillons d'ajouter enableCopying="true" à vos objets Preference non sélectionnables afin de pouvoir copier le résumé à l'aide d'un appui long.

Corrections de bugs

  • Correction d'une régression où PreferenceCategory et d'autres objets Preference non sélectionnables avaient un effet d'ondes en cas de sélection
  • Correction d'un problème d'accessibilité où TalkBack ne voyait pas DropDownPreference en tant qu'élément cliquable
  • Correction de certains problèmes de mise en page de droite à gauche
  • Mise à jour de certaines annotations pouvant être nulles dans PreferenceFragmentCompat pour qu'elles correspondent à Fragment

Version 1.1.0-alpha04

13 mars 2019

Publication d'androidx.preference:preference:1.1.0-alpha04 et androidx.preference:preference-ktx:1.1.0-alpha04. La liste complète des commits inclus dans cette version est disponible sur cette page.

Nouvelles fonctionnalités

Mise à jour de SeekBarPreference.

  • Style mis à jour pour correspondre aux spécifications de Material
    • Le libellé de la valeur est désormais masqué par défaut, bien qu'il puisse toujours être affiché avec app:showSeekBarValue="true" ou setShowSeekBarValue(true). Ce libellé ne fait pas partie des spécifications de Material, mais nous savons qu'il est très utilisé. Nous continuerons donc à le prendre en charge, même si nous ne vous recommandons pas de l'utiliser.
    • Le libellé de la valeur est maintenant mis à jour lorsque la barre de recherche est déplacée, et non lorsqu'elle est relâchée. Notez que cela ne signifie pas que la valeur est mise à jour en interne. Voir ci-dessous pour une nouvelle API qui active cette fonctionnalité.
    • Remarque : bien que cette fonctionnalité soit compatible, vous devez éviter de définir un résumé sur une SeekBarPreference, car ce comportement n'est pas prévu et ne fait pas partie des spécifications de Material.
  • Ajout de la prise en charge des mises à jour continues, qui permet à la barre de recherche de mettre à jour sa valeur enregistrée tout en étant déplacée. Cette fonctionnalité peut être activée à partir d'un fichier XML ou d'un programme, avec app:updatesContinuously="true" ou setUpdatesContinuously(true). Cette action se déclenchera chaque fois que la position de la barre de recherche sera modifiée.

Modifications apportées à l'API

  • Ajoute les annotations de possibilité de valeur nulle manquantes pour findPreference()

Corrections de bugs

  • Correction d'un bug qui empêchait la suppression correcte des écouteurs du menu contextuel si la copie n'était pas activée

Version 1.1.0-alpha03

7 février 2019

androidx.preference:preference 1.1.0-alpha03

Publication d'androidx.preference:preference 1.1.0-alpha03 et androidx.preference:preference-ktx 1.1.0-alpha03 avec les modifications suivantes.

Corrections de bugs

  • Correction d'un problème qui empêchait parfois l'affichage du pop-up de copier-coller dans la boîte de dialogue EditTextPreference
  • Correction d'un problème pour lequel l'adaptateur sous-jacent n'était pas correctement enregistré, ce qui provoquait des fuites de mémoire sous certaines conditions (b/121006469)
  • Correction de plantages liés à des boîtes de dialogue, qui se produisaient pendant la modification de la configuration (b/122167543)
  • Résolution du problème de fonctionnement de SummaryProvider avec MultiSelectListPreference (b/123022772)

Version 1.1.0-alpha02

17 décembre 2018

Veuillez également consulter le guide des paramètres et l'exemple d'application, qui ont été mis à jour récemment.

Nouvelles fonctionnalités

  • Ajout de l'interface EditTextPreference.OnBindEditTextListener qui permet de personnaliser l'EditText affiché dans la boîte de dialogue correspondante une fois la boîte de dialogue liée. Par exemple, vous pouvez définir un type/longueur d'entrée personnalisé ou ajouter un TextWatcher.

  • Ajout de Preference.setCopyingEnabled(). Lorsque ce paramètre est défini, un appui prolongé sur l'objet Preference permet d'afficher un menu contextuel vous permettant de copier le résumé de l'objet Preference. Cela permet d'autoriser la copie d'informations statiques, telles que des ID utilisateur spécifiques ou des informations de version d'application.

  • preferenceTheme est maintenant appliqué au thème de l'activité. Cela signifie que lorsque vous créez un objet Preference à partir du code, vous n'avez plus besoin d'utiliser le contexte de PreferenceManager#getContext(). Vous pouvez simplement utiliser le contexte de votre fragment/activité.

Modifications apportées à l'API

  • Refactorisation de findPreference() pour renvoyer <T extends Preference>. Autrement dit, vous n'avez pas besoin de caster explicitement des objets Preference lorsque vous utilisez findPreference(). Par exemple, EditTextPreference preference = findPreference(“edit_text”) est désormais un code valide.

Version 1.1.0-alpha01

5 novembre 2018

Nouvelles fonctionnalités

  • Vous pouvez désormais définir un SummaryProvider pour un objet Preference afin de configurer son résumé de manière dynamique chaque fois que l'objet Preference est mis à jour ou devient visible par l'utilisateur.
  • Ajout des implémentations de SummaryProvider par défaut pour ListPreference et EditTextPreference. Lorsqu'elles sont définies, elles permettent de mettre à jour automatiquement le résumé de l'objet Preference pour indiquer la valeur enregistrée, ou la mention "Not Set" (Non défini) si aucune valeur n'a été enregistrée. Vous pouvez les définir avec app:useSimpleSummaryProvider=”true”
  • Ajout de PreferenceGroup#removePreferenceRecursively, qui recherche et supprime de manière récursive un objet Preference dans le groupe, ou dans un groupe imbriqué à un niveau inférieur dans la hiérarchie.

Modifications apportées à l'API

  • PreferenceFragment et d'autres classes utilisant des fragments de framework sont maintenant obsolètes. Utilisez plutôt PreferenceFragmentCompat et d'autres classes compat.

Corrections de bugs

  • Correction d'iconSpaceReserved qui ne fonctionnait pas correctement avec PreferenceCategories.
  • Correction de PreferenceCategories qui n'utilisaient pas colorAccent pour la couleur de leur titre dans les versions antérieures à la version d'API 21.
  • Correction d'incohérences de mise en page de SeekBarPreference dans les versions antérieures à la version d'API 21.