Cómo personalizar tu configuración Parte de Android Jetpack.

En este documento, se describe cómo personalizar objetos Preference en tu jerarquía.

Cómo buscar preferencias

Para acceder a un objeto Preference individual, como cuando recibes o configuras un valor Preference, usa PreferenceFragmentCompat.findPreference(). Este método busca en toda la jerarquía un objeto Preference con la clave determinada.

Por ejemplo, para acceder a un EditTextPreference con una clave "signature", haz lo siguiente:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

Recupera este Preference con el siguiente código:

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.
}

Cómo controlar la visibilidad de objetos Preference

Puedes controlar qué objetos Preference son visibles para el usuario cuando navega a una pantalla de configuración. Por ejemplo, si un objeto Preference en particular es significativo solo cuando se habilita una función correspondiente, es posible que quieras ocultar ese objeto Preference cuando la función está inhabilitada.

Para mostrar un objeto Preference solo cuando se cumpla una condición, primero establece la visibilidad Preference como falsa en el archivo XML, como se muestra en el siguiente ejemplo:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"
        app:isPreferenceVisible="false"/>

En onCreatePreferences(), muestra Preference cuando se cumple la condición correspondiente:

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

Cómo actualizar resúmenes de manera dinámica

Un Preference con datos persistentes debe mostrar el valor actual en su resumen para ayudar al usuario a comprender mejor el estado actual de Preference. Por ejemplo, un EditTextPreference debe mostrar el valor de texto guardado, y un ListPreference debe mostrar la entrada de la lista seleccionada. También es posible que tengas objetos Preference que deban actualizar su resumen según el estado interno o externo de la app, por ejemplo, un Preference que muestra un número de versión. Puedes hacerlo con un SummaryProvider.

Cómo usar un objeto SimpleSummaryProvider

ListPreference y EditTextPreference incluyen implementaciones de SummaryProvider simples que muestran automáticamente el valor de Preference guardado como resumen. Si no se guarda ningún valor, muestran "Not set".

Para habilitar estas implementaciones desde XML, configura app:useSimpleSummaryProvider="true".

Como opción, en el código, puedes usar ListPreference.SimpleSummaryProvider.getInstance() y EditTextPreference.SimpleSummaryProvider.getInstance() para obtener la instancia de SummaryProvider simple y, luego, configurarla en el objeto Preference, tal como se muestra en el siguiente ejemplo:

Kotlin

listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance()
editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()

Java

listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance());
editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());

Cómo usar un objeto SummaryProvider personalizado

Puedes crear tu propio objeto SummaryProvider y anular el objeto provideSummary() para personalizar el resumen siempre que lo solicite el objeto Preference. Por ejemplo, el siguiente EditTextPreference muestra la longitud de su valor guardado como resumen:

Una imagen que muestra un ejemplo de EditTextPreference
Figura 1: Un ejemplo de EditTextPreference

A modo de ejemplo, supongamos lo siguiente EditTextPreference:

<EditTextPreference
        app:key="counting"
        app:title="Counting preference"/>

En onCreatePreferences(), puedes crear un nuevo SummaryProvider y anular provideSummary() para mostrar el resumen que se incluirá:

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();
        }
    });
}

El resumen de Preference muestra la longitud del valor guardado o "Not set" cuando no existe un valor guardado.

Cómo personalizar un diálogo EditTextPreference

En un diálogo EditTextPreference, puedes personalizar el comportamiento del campo de texto si adjuntas un OnBindEditTextListener. Este objeto de escucha se invoca cuando se muestra el diálogo al usuario.

A modo de ejemplo, puedes personalizar un diálogo para que solo acepte números. Primero, crea el EditTextPreference:

<EditTextPreference
        app:key="number"
        app:title="Numbers only preference"/>

A continuación, en onCreatePreferences(), crea una nueva OnBindEditTextListener y anula onBindEditText() para personalizar la EditText cuando se muestra al usuario.

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

Ahora, cuando se muestra el diálogo al usuario, se abre el teclado en el modo numérico para que solo pueda ingresar números en la EditText.

Acciones de Preference

Un objeto Preference puede ejercer una acción específica cuando se lo presiona. Por ejemplo, un Preference puede actuar como un vínculo a una parte separada de tu app. Para agregar una acción a una Preference, puedes configurar un Intent en el Preference directamente o puedes configurar un OnPreferenceClickListener para una lógica más específica.

Cómo configurar un elemento Intent

Puedes configurar un Intent en un Preference para iniciar un nuevo Fragment, Activity o una app diferente cada vez que se presione Preference. Esto es lo mismo que usar Context.startActivity() con un elemento Intent determinado.

Puedes configurar un elemento Intent en el archivo XML si usas una etiqueta <intent> anidada. En el siguiente ejemplo, se define un Intent que inicia un Activity:

<Preference
        app:key="activity"
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity"/>
</Preference>

Como alternativa, puedes usar setIntent() directamente en un objeto Preference, de la siguiente manera:

Kotlin

val intent = Intent(context, ExampleActivity::class.java)
activityPreference.setIntent(intent)

Java

Intent intent = new Intent(getContext(), ExampleActivity.class);
activityPreference.setIntent(intent);

También puedes incluir elementos adicionales con una Intent mediante 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>

Aquí se muestra un ejemplo de un objeto Preference con un elemento Intent que abre una página 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

Puedes configurar un OnPreferenceClickListener en un Preference, que agrega una devolución de llamada a onPreferenceClick() cuando se presiona Preference. Por ejemplo, puedes usar el objeto de escucha para navegar a otro Fragment o Activity si tienes una lógica más compleja para controlar la navegación.

Para configurar un objeto OnPreferenceClickListener, usa código similar al siguiente:

Kotlin

onClickPreference.setOnPreferenceClickListener({
    // Do something.
    true
})

Java

onClickPreference.setOnPreferenceClickListener(preference -> {
    // Do something.
    return true;
});