Cómo personalizar tus configuraciones   Part of Android Jetpack.

Este artículo describe cómo personalizar Preferences en tu jerarquía.

Cómo buscar elementos Preference

Para acceder a elementos Preference individuales, como cuando obtienes o configuras un valor de Preference, usa PreferenceFragmentCompat.findPreference(). Este método busca en toda la jerarquía un elemento Preference con una clave específica.

A modo de ejemplo, usemos EditTextPreference con una clave de "firma":

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

Podemos recuperar este objeto Preference usando el siguiente código:

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    val preference = findPreference("signature") as EditTextPreference
    // do something with this preference
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    EditTextPreference preference = (EditTextPreference) findPreference("signature");
    // do something with this preference
}

Cómo controlar la visibilidad de Preference

Puedes controlar qué objetos Preferences ve el usuario cuando navega a la pantalla de configuración. Por ejemplo, si un elemento Preference en particular es importante solo cuando se habilita una función específica, te recomendamos que ocultes ese elemento Preference cuando se inhabilite la función.

Para mostrar un elemento Preference únicamente cuando se cumpla una condición, primero establece la visibilidad de Preference como falsa en el archivo XML, tal como se muestra en el siguiente ejemplo:

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

A continuación, en onCreatePreferences(), muestra el elemento Preference cuando se cumpla la condición específica:

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    if(*/\*some feature\*/*) {
        val preference = findPreference("signature")
        preference.isVisible = true
    }
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    if(*/\*some feature\*/*) {
        Preference editTextPreference = findPreference("signature");
        editTextPreference.setVisible(true);
    }
}

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

Un elemento Preference que recupera datos debería mostrar el valor actual en su resumen para ayudar al usuario a comprender mejor el estado actual de Preference. Por ejemplo, un EditTextPreference debería mostrar el valor de texto guardado actual, y un ListPreference debería mostrar la entrada de lista seleccionada actualmente. También es posible que tengas Preferences que necesiten actualizar su resumen basándose en el estado de la aplicación interna o externa: por ejemplo, un elemento Preference que muestra un número de versión. Esto se puede lograr usando un SummaryProvider.

Cómo utilizar un SimpleSummaryProvider

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

Puedes habilitar estas implementaciones desde el XML configurando app:useSimpleSummaryProvider="true".

De forma alternativa, en el código puedes usar ListPreference.SimpleSummaryProvider.getInstance() y EditTextPreference.SimpleSummaryProvider.getInstance() para obtener la instancia simple SummaryProvider y luego establecerla en Preference, tal como se muestra a continuación:

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 SummaryProvider personalizado

Puedes crear tu propio SummaryProvider y anular provideSummary() para personalizar el resumen cuando sea que lo requiera Preference. Por ejemplo, el EditTextPreference que aparece a continuación muestra la longitud del valor guardado como el resumen:

A modo de ejemplo, asume el siguiente EditTextPreference:

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

En onCreatePreferences(), crea un nuevo SummaryProvider y anula provideSummary() para mostrar el resumen que se debe exhibir:

Kotlin

val countingPreference = findPreference("counting") as EditTextPreference

countingPreference.summaryProvider = SummaryProvider<EditTextPreference> { preference ->
    val text = preference.text
    if (TextUtils.isEmpty(text)) {
        "Not set"
    } else {
        "Length of saved value: " + text.length
    }
}

Java

EditTextPreference countingPreference = (EditTextPreference) findPreference("counting");

countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() {
    @Override
    public CharSequence provideSummary(EditTextPreference preference) {
        String text = preference.getText();
        if (TextUtils.isEmpty(text)){
            return "Not set";
        }
        return "Length of saved value: " + text.length();
    }
});

El resumen de Preference ahora muestra la longitud del valor guardado o bien "Not set" cuando no hay un valor almacenado.

Acciones de Preference

Un elemento Preference puede activar una acción especifica si se lo presiona. Por ejemplo, un Preference puede actuar como un vínculo que dirige a otra parte de tu aplicación. Para agregar una acción a un Preference, puedes establecer un Intent directamente en Preference o un OnPreferenceClickListener para una lógica más específica.

Cómo establecer un Intent

Puedes establecer un Intent en un Preference para iniciar un nuevo Fragment, Activity o aplicación independiente cuando se presione un elemento Preference. Esto es lo mismo que usar Context.startActivity() con un Intent específico.

Puedes establecer un Intent en el archivo XML usando una etiqueta anidada <intent>. El ejemplo que se incluye a continuación define un Intent que inicia un elemento Activity:

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

De forma alternativa, puedes usar setIntent() directamente en un Preference, como se muestra aquí:

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 agregar elementos adicionales con un Intent mediante el 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>

Este es un ejemplo de un Preference con un 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")
webpagePreference.setIntent(intent)

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("http://www.google.com"));
webpagePreference.setIntent(intent);

OnPreferenceClickListener

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

Para establecer un OnPreferenceClickListener, usa código similar al que se indica a continuación:

Kotlin

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

Java

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