Cómo usar valores de Preference guardados Parte de Android Jetpack.

En este documento, se describe cómo almacenar y usar valores Preference guardados por la Biblioteca de Preference.

Almacenamiento de datos de Preference

En esta sección, se describe cómo un objeto Preference puede persistir datos.

SharedPreferences

De forma predeterminada, un objeto Preference usa SharedPreferences para guardar de salida. La API de SharedPreferences admite operaciones de lectura y escritura pares clave-valor de un archivo que se guarda en las sesiones de la aplicación. El La biblioteca de Preference usa una instancia de SharedPreferences privada para que solo tu aplicación puede acceder a ellos.

A modo de ejemplo, supongamos el siguiente objeto SwitchPreferenceCompat:

<SwitchPreferenceCompat
        app:key="notifications"
        app:title="Enable message notifications"/>

Cuando un usuario activa esta opción. estado, el archivo SharedPreferences se actualiza con un par clave-valor de "notifications" : "true". La clave que se usa es la que la clave establecida para Preference.

Para obtener más información sobre la API de SharedPreferences, consulta Cómo guardar pares clave-valor. datos.

Para obtener información sobre las diferentes maneras de almacenar datos en Android, consulta Datos y almacenamiento de archivos.

PreferenceDataStore

Aunque la biblioteca de Preference conserva datos con SharedPreferences predeterminada, SharedPreferences no siempre son una solución ideal. Por ejemplo, tu aplicación requiere que un usuario acceda, tal vez quieras conservar la configuración de la aplicación en la nube para que la configuración se refleje en con otros dispositivos y plataformas. Del mismo modo, si tu aplicación tiene configuración que son específicas del dispositivo, cada usuario tiene su propia configuración, lo que convierte a SharedPreferences en una solución poco ideal.

Un objeto PreferenceDataStore te permite usar un backend de almacenamiento personalizado para conservar los valores de Preference. Para ver más consulta Usa un almacén de datos personalizado.

Cómo leer valores de Preference

Para recuperar el objeto SharedPreferences que se usa, llama a PreferenceManager.getDefaultSharedPreferences(). Aunque este método funciona desde cualquier parte de tu aplicación, te recomendamos lo siguiente: divides tu aplicación en capas. Para obtener más información, consulta Datos capa.

Por ejemplo, con un objeto EditTextPreference con una clave de "signature", como sigue:

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

Puedes recuperar el valor guardado de este Preference de manera global de la siguiente manera:

Kotlin

val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this /* Activity context */)
val name = sharedPreferences.getString("signature", "")

Java

SharedPreferences sharedPreferences =
        PreferenceManager.getDefaultSharedPreferences(this /* Activity context */);
String name = sharedPreferences.getString("signature", "");

Cómo detectar los cambios en los valores de Preference

Para detectar cambios en los valores de Preference, puedes elegir entre dos interfaces:

• Preference.OnPreferenceChangeListener
• SharedPreferences.OnSharedPreferenceChangeListener

La siguiente tabla muestra las diferencias entre ambas interfaces:

OnPreferenceChangeListener	OnSharedPreferenceChangeListener
Se establece en un solo Preference.	Se aplica a todos los objetos Preference.
Se llama cuando un Preference está a punto de cambiar su valor guardado. incluso si el valor pendiente es el mismo que el guardado.	Se llama solo cuando cambia el valor guardado para un Preference.
Solo se llama a través de la biblioteca Preference. Una parte separada de la aplicación puede cambiar el valor guardado.	Se llama cada vez que cambia el valor guardado, incluso si es de una instancia parte de la aplicación.
Se llama antes de que se guarde el valor pendiente.	Se llama después de que se guarda el valor.
Se llama cuando se usa SharedPreferences o un PreferenceDataStore	Se llama solamente al usar SharedPreferences.

Cómo implementar OnPreferenceChangeListener

Implementar un OnPreferenceChangeListener te permite escuchar un mensaje cambia al valor de un Preference. Luego, puedes validar si el cambio de que ocurra. Por ejemplo, el siguiente código muestra cómo detectar un cambio en la Valor de un EditTextPreference con una clave de "name":

Kotlin

override fun onPreferenceChange(preference: Preference, newValue: Any): Boolean {
    Log.e("preference", "Pending Preference value is: $newValue")
    return true
}

Java

@Override
public boolean onPreferenceChange(Preference preference, Object newValue) {
    Log.e("preference", "Pending Preference value is: " + newValue);
    return true;
}

A continuación, debes configurar este objeto de escucha directamente con setOnPreferenceChangeListener(): de la siguiente manera:

Kotlin

preference.onPreferenceChangeListener = ...

Java

preference.setOnPreferenceChangeListener(...);

Cómo implementar OnSharedPreferenceChangeListener

Al crear valores de Preference persistentes con SharedPreferences, también puedes usar un objeto SharedPreferences.OnSharedPreferenceChangeListener para detectar cambios. De esta manera, puedes detectar cuándo se modifican los valores guardados por Preference. como cuando se sincroniza la configuración con un servidor. En el siguiente ejemplo, se muestra cómo detecta un cambio en el valor de un EditTextPreference con una clave de "name"

Kotlin

override fun onSharedPreferenceChanged(sharedPreferences: SharedPreferences, key: String) {
    if (key == "signature") {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""))
    }
}

Java

@Override
public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals("signature")) {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""));
    }
}

Registra el objeto de escucha con registerOnSharedPreferenceChangedListener(): de la siguiente manera:

Kotlin

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

Java

getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(...);

Advertencia: Para evitar la recolección no deseada de elementos no utilizados, almacena una referencia importante a el objeto de escucha. Cuando llamas a registerOnSharedPreferenceChangeListener(), la SharedPreferenceManager no almacena una referencia importante al objeto de escucha. Para Para solucionar este problema, puedes implementar onSharedPreferenceChanged() directamente en tu PreferenceFragmentCompat También puedes crear una variable de instancia, como se muestra en el siguiente ejemplo:

Kotlin

    val listener: SharedPreferences.OnSharedPreferenceChangeListener =
            SharedPreferences.OnSharedPreferenceChangeListener {...}
    

Java

    SharedPreferences.OnSharedPreferenceChangeListener listener =
            new SharedPreferences.OnSharedPreferenceChangeListener() {...}
    

Para una administración adecuada del ciclo de vida en tu Activity o Fragment, registra y cancela el registro de este objeto de escucha en las devoluciones de llamada onResume() y onPause(), como se muestra en el siguiente ejemplo:

Kotlin

override fun onResume() {
    super.onResume()
    preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(this)
}

override fun onPause() {
    super.onPause()
    preferenceManager.sharedPreferences.unregisterOnSharedPreferenceChangeListener(this)
}

Java

@Override
public void onResume() {
    super.onResume();
    getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(this);
}

@Override
public void onPause() {
    super.onPause();
    getPreferenceManager().getSharedPreferences().unregisterOnSharedPreferenceChangeListener(this);
}

Usa un almacén de datos personalizado

Aunque recomendamos objetos Preference persistentes con SharedPreferences, también puedes usar un almacén de datos personalizado. Un almacén de datos personalizado puede ser útil si tu aplicación conserva los valores en una base de datos o si los valores son específicos del dispositivo, como se muestran en los siguientes ejemplos.

Implementa el almacén de datos

Para implementar un almacén de datos personalizado, crea una clase que extienda PreferenceDataStore En el siguiente ejemplo, se crea un almacén de datos que controla Valores String:

Kotlin

class DataStore : PreferenceDataStore() {
    override fun putString(key: String, value: String?) {
        // Save the value somewhere.
    }

    override fun getString(key: String, defValue: String?): String? {
        // Retrieve the value.
    }
}

Java

public class DataStore extends PreferenceDataStore {
    @Override
    public void putString(String key, @Nullable String value) {
        // Save the value somewhere.
    }
    @Override
    @Nullable
    public String getString(String key, @Nullable String defValue) {
        // Retrieve the value.
    }
}

Nota: Anula solamente métodos que usan tus objetos Preference. Llamando un método que no implementaste genera una UnsupportedOperationException.

Ejecutar cualquier operación que requiera mucho tiempo fuera del subproceso principal para evitar bloquear al usuario interfaz de usuario. Como es posible que Fragment o Activity contenga el que se destruya mientras se conserva un valor, serializa los datos para y no pierdas ningún valor que haya modificado el usuario.

Habilita el almacén de datos

Después de implementar el almacén de datos, configura el nuevo almacén de datos en onCreatePreferences() para que los objetos Preference conserven valores con el en lugar de usar el SharedPreferences predeterminado. Puedes habilitar un almacén de datos para cada Preference o para toda la jerarquía.

Para habilitar un almacén de datos personalizado para un Preference específico, llama a setPreferenceDataStore() en Preference, como se muestra en el siguiente ejemplo:

Kotlin

val preference: Preference? = findPreference("key")
preference?.preferenceDataStore = dataStore

Java

Preference preference = findPreference("key");
if (preference != null) {
    preference.setPreferenceDataStore(dataStore);
}

Para habilitar un almacén de datos personalizado para toda una jerarquía, llama a setPreferenceDataStore() en PreferenceManager:

Kotlin

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

Java

PreferenceManager preferenceManager = getPreferenceManager();
preferenceManager.setPreferenceDataStore(dataStore);

Un almacén de datos configurado para una Preference específica anula cualquier almacén de datos que se configura para la jerarquía correspondiente. En la mayoría de los casos, se configura un almacén de datos para toda la jerarquía.

Nota: Si configuras un almacén de datos para una Preference después de que Preference se adjunta a la jerarquía, el valor inicial de Preference no es se volvió a propagar.