Preference

Crea pantallas de configuración interactivas sin necesidad de interactuar con el almacenamiento del dispositivo ni de administrar la IU.
Actualización más reciente Versión estable Versión potencial Versión beta Versión alfa
26 de julio de 2023 1.2.1 - - -

Cómo declarar dependencias

Para agregar una dependencia en Preference, debes agregar el repositorio Maven de Google a tu proyecto. Consulta el repositorio Maven de Google para obtener más información.

Agrega las dependencias de los artefactos que necesites en el archivo build.gradle de tu app o módulo:

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")
}

Para obtener más información sobre las dependencias, consulta Cómo agregar dependencias de compilación.

Comentarios

Tus comentarios ayudan a mejorar Jetpack. Avísanos si descubres nuevos errores o tienes ideas para mejorar esta biblioteca. Consulta los errores existentes de esta biblioteca antes de crear uno nuevo. Puedes agregar tu voto a un error existente haciendo clic en el botón de la estrella.

Crear un error nuevo

Consulta la documentación sobre la Herramienta de seguimiento de errores para obtener más información.

Versión 1.2

Versión 1.2.1

26 de julio de 2023

Lanzamiento de androidx.preference:preference:1.2.1. La versión 1.2.1 contiene estas confirmaciones.

Correcciones de errores

  • PreferenceHeaderFragmentCompat ahora controla correctamente el botón Atrás del sistema cuando se usa dentro de ComponentDialog o cuando se usan bibliotecas como @AndroidEntryPoint de Hilt que unen el Context de Fragment.
  • La preferencia ahora depende de la Actividad 1.5.1. (Ie5d22).
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment ahora propaga header.extras como los argumentos Fragment.

Versión 1.2.0

26 de enero de 2022

Lanzamiento de androidx.preference:preference:1.2.0 y androidx.preference:preference-ktx:1.2.0. La versión 1.2.0 contiene estas confirmaciones.

Cambios importantes desde la versión 1.1.0

  • Se agregó PreferenceHeaderFragmentCompat para la preferencia de dos paneles que se adapta automáticamente según el tamaño del dispositivo que se usa, lo que lo hace útil para teléfonos, dispositivos plegables y tablets. El panel de encabezados que se brinda anula el método onCreatePreferenceHeader() en PreferenceHeaderFragmentCompat. Cualquier <Preference> en el encabezado PreferenceFragmentCompat que usa app:fragment hará que ese fragmento aparezca en el segundo panel de detalles. El fragmento de detalle inicial que se debe mostrar antes de que se seleccione cualquier preferencia se puede personalizar anulando onCreateInitialDetailFragment(). La implementación predeterminada muestra la primera preferencia que tiene un fragmento definido.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • Se agregaron anotaciones de nulabilidad a muchas de las API que antes no especificaban @NonNull ni @Nullable. Este es un posible cambio rotundo de la fuente de Kotlin si la nulabilidad que elegiste en el código Kotlin no coincidía con la nulabilidad que está definida ahora.

  • PreferenceFragmentCompat ahora busca implementaciones de las interfaces OnPreferenceStartFragmentCallback, OnNavigateToScreenListener y OnDisplayPreferenceDialogListener en los fragmentos superiores antes de ver si el hosting de Context o Activity implementan esas interfaces.

Versión 1.2.0-rc01

15 de diciembre de 2021

Lanzamiento de androidx.preference:preference:1.2.0-rc01 y androidx.preference:preference-ktx:1.2.0-rc01 sin cambios desde 1.2.0-beta01. La versión 1.2.0-rc01 contiene estas confirmaciones.

Versión 1.2.0-beta01

17 de noviembre de 2021

Lanzamiento de androidx.preference:preference:1.2.0-beta01 y androidx.preference:preference-ktx:1.2.0-beta01 sin modificaciones desde Preference 1.2.0-alpha02. La versión 1.2.0-beta01 contiene estas confirmaciones.

Versión 1.2.0-alpha02

3 de noviembre de 2021

Lanzamiento de androidx.preference:preference:1.2.0-alpha02 y androidx.preference:preference-ktx:1.2.0-alpha02. La versión 1.2.0-alpha02 contiene estas confirmaciones.

Cambios en la API

  • Se agregaron anotaciones de nulabilidad a muchas de las API que antes no especificaban @NonNull ni @Nullable. (I04252, Ie2cc0)
  • Se quitó la API de openPreference() de PreferenceHeaderFragmentCompat. Se llama a este método de forma automática, y no se debe llamar de manera manual. (Ia6989)

Cambios en el comportamiento

  • Las devoluciones de llamada de PreferenceFragmentCompat para OnNavigateToScreenListener y OnDisplayPreferenceDialogListener ahora siguen el mismo patrón que OnPreferenceTreeClickListener y buscan la jerarquía de fragmentos superior de objetos de escucha válidos antes de buscar para ver si la actividad o el contexto de hosting implementan estas interfaces. (I7ae6c)

Versión 1.2.0-alpha01

27 de octubre de 2021

Lanzamiento de androidx.preference:preference:1.2.0-alpha01 y androidx.preference:preference-ktx:1.2.0-alpha01. La versión 1.2.0-alpha01 contiene estas confirmaciones.

Nuevas funciones

  • Se agregó PreferenceHeaderFragmentCompat para la preferencia de dos paneles (I9a2d8).

Cambios en el comportamiento

  • Ahora se pueden implementar las devoluciones de llamada Preference de OnPreferenceDisplayDialogCallback, OnPreferenceStartScreenCallback y OnPreferenceStartFragmentCallback en un contexto sin actividades. Se verifica getContext() para verificar si implementa esas devoluciones de llamada antes de comprobar getActivity(). Si getContext() devuelve una actividad (el caso común), no hay ningún cambio de comportamiento.

  • La llamada de PreferenceFragmentCompat a onPreferenceTreeClick ahora busca implementaciones de la interfaz OnPreferenceStartFragmentCallback en fragmentos superiores antes de considerar la implementación de la actividad (c64eed).

Versión 1.1

Versión 1.1.1

15 de abril de 2020

Lanzamiento de androidx.preference:preference:1.1.1 y androidx.preference:preference-ktx:1.1.1. La versión 1.1.1 contiene estas confirmaciones.

Correcciones de errores

  • PreferenceDialogFragmentCompat ya no arrojará una IllegalStateException cuando se aumente un FragmentContainerView de xml (b/150051716).

Actualizaciones de dependencias

  • La preferencia ahora depende del Fragmento 1.2.4 (aosp/1277317).
  • Ahora, la dependencia preference-ktx depende de androidx.core:core-ktx:1.1.0 y androidx.fragment:fragment-ktx:1.2.4, lo que duplica las dependencias del artefacto preference principal y garantiza que se aplique la actualización de preference-ktx a los artefactos principales y de -ktx de las dependencias transitivas (aosp/1277319).

Versión 1.1.0

5 de septiembre de 2019

Lanzamiento de androidx.preference:preference:1.1.0 y androidx.preference:preference-ktx:1.1.0. Para conocer las confirmaciones incluidas en esta versión, consulta este vínculo.

Si esta es la primera vez que actualizas a una versión 1.1.*, a continuación te mostramos una lista concisa de los cambios más importantes en relación con la última versión estable, la 1.0.0. También puedes consultar la Guía de configuración, la app de ejemplo y la charla de Android Dev Summit.

Cambios importantes desde la versión 1.0.0

  • PreferenceFragment y otras clases que usan Framework Fragments dejaron de estar disponibles; en su lugar, debes usar PreferenceFragmentCompat y otras clases *compat.
  • Ahora puedes establecer un SummaryProvider en una Preference para configurar dinámicamente su resumen siempre que esta se actualice o sea visible para el usuario. Para obtener más información, consulta la guía.
  • Se agregó la interfaz de EditTextPreference.OnBindEditTextListener, que permite personalizar el EditText que se muestra en el diálogo correspondiente una vez que este se vinculó. Se trata de un reemplazo directo para usar atributos como android:inputType directamente en EditTextPreference, que no es compatible con la biblioteca de AndroidX. Para obtener más información, consulta la guía.
  • Se agregó Preference.setCopyingEnabled(). Si se activa, cuando mantengas presionada la Preference, se mostrará un menú contextual que permite copiar el resumen de esta.
  • Se actualizó el estilo SeekBarPreference para que coincida con las especificaciones de Material. Consulta el registro de cambios detallado para conocer los otros cambios realizados en SeekBarPreference.
  • Se implementó una gran cantidad de correcciones de errores, actualizaciones de estilo, correcciones de compatibilidad de nivel de API y mejoras generales de calidad de vida.

Versión 1.1.0-rc01

2 julio de 2019

Lanzamiento de androidx.preference:preference:1.1.0-rc01 y androidx.preference:preference-ktx:1.1.0-rc01. Para conocer las confirmaciones incluidas en esta versión, consulta este artículo.

Cambios en la API

  • Preference#onInitializeAccessibilityNodeInfo dejó de estar disponible.
  • Este método enviaba mediante proxy la información de accesibilidad del nodo a una Preference específica, pero esta es una capa incorrecta para esta personalización. Si deseas ajustar la información de accesibilidad, debes anular onBindViewHolder y agregar directamente información de accesibilidad a la vista.

Versión 1.1.0-beta01

5 de junio de 2019

Lanzamiento de androidx.preference:preference:1.1.0-beta01 y androidx.preference:preference-ktx:1.1.0-beta01. Para conocer las confirmaciones incluidas en esta versión, consulta este vínculo.

Cambios importantes desde la versión 1.1.0

Si esta es la primera vez que actualizas a una versión 1.1.*, a continuación te mostramos una lista concisa de los cambios más importantes en relación con la última versión estable, la 1.1.0. También puedes consultar la Guía de configuración, la app de ejemplo y la charla de Android Dev Summit.

  • PreferenceFragment y otras clases que usan Framework Fragments dejaron de estar disponibles; en su lugar, debes usar PreferenceFragmentCompat y otras clases *compat.
  • Ahora puedes establecer un SummaryProvider en una Preference para configurar dinámicamente su resumen siempre que esta se actualice o sea visible para el usuario. Para obtener más información, consulta la guía.
  • Se agregó la interfaz de EditTextPreference.OnBindEditTextListener, que permite personalizar el EditText que se muestra en el diálogo correspondiente una vez que este se vinculó. Se trata de un reemplazo directo para usar atributos como android:inputType directamente en EditTextPreference, que no es compatible con la biblioteca de AndroidX. Para obtener más información, consulta la guía.
  • Se agregó Preference.setCopyingEnabled(). Si se activa, cuando mantengas presionada la Preference, se mostrará un menú contextual que permite copiar el resumen de esta.
  • Se actualizó el estilo SeekBarPreference para que coincida con las especificaciones de Material. Consulta el registro de cambios detallado para conocer los otros cambios realizados en SeekBarPreference.
  • Se implementó una gran cantidad de correcciones de errores, actualizaciones de estilo, correcciones de compatibilidad de nivel de API y mejoras generales de calidad de vida.

Cambios en la API desde 1.1.0-alpha05

  • Se quitó getOnBindEditTextListener de la API pública, por lo que solo deberías usar setOnBindEditTextListener cuando interactúas con esta API.

Informa sobre errores aquí si tienes algún problema o si tienes sugerencias para nuevas funciones.

Versión 1.1.0-alpha05

7 de mayo de 2019

Lanzamiento de androidx.preference:preference:1.1.0-alpha05 y androidx.preference:preference-ktx:1.1.0-alpha05. Para conocer las confirmaciones incluidas en esta versión, consulta este artículo.

Nuevas funciones

  • Se actualizó el estilo de las Preferences no seleccionables: el título y el resumen ahora comparten el mismo color para dejar en claro que no es posible interactuar con ellos y solo se usan para mostrar información.
  • Nota: Es posible que pienses en agregar enableCopying="true" a tus Preferences no seleccionables, por lo que puedes mantenerlas presionadas para copiar el resumen.

Correcciones de errores

  • Se corrigió una regresión por la que PreferenceCategory y otras Preferences no seleccionables tenían un efecto en cadena cuando se las seleccionaba.
  • Se solucionó un problema de accesibilidad por el que TalkBack interpretaba que no era posible hacer clic en DropDownPreference.
  • Se corrigieron algunos problemas de diseño de derecha a izquierda (RTL).
  • Se actualizaron algunas anotaciones anulables en PreferenceFragmentCompat para que coincidan con Fragment.

Versión 1.1.0-alpha04

13 de marzo de 2019

Lanzamiento de androidx.preference:preference:1.1.0-alpha04 y androidx.preference:preference-ktx:1.1.0-alpha04. Para obtener una lista completa de las confirmaciones incluidas en esta versión, consulta este vínculo.

Nuevas funciones

Actualización de SeekBarPreference.

  • Se actualizó el diseño para que coincida con las especificaciones de Material.
    • La etiqueta de valor ahora está oculta de forma predeterminada, aunque todavía se puede mostrar con app:showSeekBarValue="true" o setShowSeekBarValue(true). Esta etiqueta no forma parte de la especificación de Material, pero entendemos que se utiliza mucho, por lo que seguiremos admitiéndola aunque no recomendamos usarla.
    • Ahora se actualiza la etiqueta de valor mientras se arrastra la SeekBar, en lugar de cuando se la suelta. Ten en cuenta que esto no significa que el valor se actualiza internamente; consulta a continuación para saber si hay una nueva API que habilite esa funcionalidad.
    • Nota: Aunque es compatible, debes evitar establecer un resumen en una SeekBarPreference, ya que no está previsto y no forma parte de la especificación de Material.
  • Se agregó compatibilidad con actualizaciones continuas, lo que permite que SeekBar actualice su valor guardado mientras se la arrastra. Se puede habilitar desde XML o mediante programación, con app:updatesContinuously="true" o setUpdatesContinuously(true). Se disparará cada vez que cambies la posición de la SeekBar en la pantalla.

Cambios en la API

  • Se agregaron anotaciones de nulabilidad de findPreference() que faltaban.

Correcciones de errores

  • Se corrigió un error por el que los objetos de escucha del menú contextual no se quitaban correctamente si la copia no estaba habilitada.

Versión 1.1.0-alpha03

7 de febrero de 2019

androidx.preference:preference 1.1.0-alpha03

Lanzamiento de androidx.preference:preference 1.1.0-alpha03 y androidx.preference:preference-ktx 1.1.0-alpha03 con las siguientes modificaciones.

Correcciones de errores

  • Se solucionó un problema por el que, en ocasiones, la ventana emergente de copiar/pegar no se mostraba en el diálogo EditTextPreference.
  • Se solucionó un problema por el que el adaptador subyacente no se registraba correctamente, lo que provocaba pérdidas de memoria en condiciones específicas (b/121006469).
  • Se corrigieron algunas fallas relacionadas con los diálogos que se producían durante el cambio de configuración (b/122167543).
  • Se corrigió un problema por el que SummaryProvider no funcionaba con MultiSelectListPreference (b/123022772).

Versión 1.1.0-alpha02

17 de diciembre de 2018

Consulta también la Guía de configuración y la app de muestra, que se actualizaron recientemente.

Nuevas funciones

  • Se agregó la interfaz de EditTextPreference.OnBindEditTextListener, que permite personalizar el EditText que se muestra en el diálogo correspondiente, una vez que este se vinculó. Por ejemplo, para establecer un tipo o longitud de entrada personalizados, o agregar un TextWatcher.

  • Se agregó Preference.setCopyingEnabled(). Si se activa, al mantener presionado en Preference, se mostrará un menú contextual que permite copiar el resumen de la preferencia. Se puede usar para permitir la copia de información estática, como ID de usuario específicos o información sobre la versión de la aplicación.

  • Actualmente, preferenceTheme se aplica al tema de la actividad. Esto significa que, cuando se crea una Preference a partir del código, ya no es necesario usar el contexto de PreferenceManager#getContext(); puedes usar solo el contexto de Fragment/Activity.

Cambios en la API

  • Se refactorizó findPreference() para que muestre <T extends Preference>. Esto significa que no es necesario emitir Preferences de manera explícita cuando se utiliza findPreference(). Por ejemplo, EditTextPreference preference = findPreference(“edit_text”) ahora es un código válido.

Versión 1.1.0-alpha01

5 de noviembre de 2018

Nuevas funciones

  • Ahora puedes establecer un SummaryProvider en una Preference para configurar dinámicamente su resumen siempre que esta se actualice o sea visible para el usuario.
  • Se agregaron implementaciones predeterminadas de SummaryProvider para ListPreference y EditTextPreference que, cuando se configuren, actualizarán automáticamente el resumen de la Preference para indicar el valor guardado, o "Not Set", si no se ha guardado ningún valor. Estos se pueden configurar con app:useSimpleSummaryProvider=”true”.
  • Se agregó PreferenceGroup#removePreferenceRecursively, que busca y quita de forma recurrente una Preference del grupo o de un grupo anidado de menor jerarquía.

Cambios en la API

  • PreferenceFragment y otras clases que usan Fragment de framework se dieron de baja; en su lugar, debes usar PreferenceFragmentCompat y otras clases compatibles.

Correcciones de errores

  • Se corrigió un error por el que iconSpaceReserved no funcionaba correctamente con PreferenceCategories.
  • Se corrigió un error por el que PreferenceCategories no usaba colorAccent para el color de su título en niveles de API inferiores a 21.
  • Se corrigieron algunas incoherencias de diseño de SeekBarPreference en niveles de API inferiores a 21.