Utilizza i valori delle preferenze salvati Parte di Android Jetpack.

Questo documento descrive come archiviare e utilizzare Valori di Preference salvati da nella libreria delle preferenze.

Archiviazione dati preferita

Questa sezione descrive in che modo un elemento Preference può rendere persistenti i dati.

Preferenze condivise

Per impostazione predefinita, un Preference utilizza SharedPreferences per risparmiare e i relativi valori. L'API SharedPreferences supporta lettura e scrittura semplici coppie chiave-valore da un file salvato tra le sessioni dell'applicazione. La La libreria delle preferenze utilizza un'istanza SharedPreferences privata in modo che solo l'applicazione possa accedervi.

Ad esempio, supponiamo che: SwitchPreferenceCompat:

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

Quando un utente attiva questa opzione lo stato corrente, il file SharedPreferences si aggiorna con una coppia chiave-valore di "notifications" : "true". La chiave utilizzata è uguale alla chiave impostata per Preference.

Per ulteriori informazioni sull'API SharedPreferences, consulta la sezione Salva coppia chiave-valore di archiviazione dati.

Per informazioni sulle diverse modalità di archiviazione dei dati su Android, consulta l'articolo Informazioni e archiviazione di file.

Archivio dati Preference

Anche se la libreria delle preferenze mantiene i dati con SharedPreferences del per impostazione predefinita, SharedPreferences non sono sempre una soluzione ideale. Ad esempio, se se la tua applicazione richiede l'accesso da parte dell'utente, potresti voler mantenere impostazioni dell'applicazione nel cloud in modo che si riflettano su altri dispositivi e piattaforme. Allo stesso modo, se la tua applicazione ha opzioni specifiche per ciascun dispositivo, ogni utente sul dispositivo ha impostazioni separate, rendendo SharedPreferences una soluzione non ottimale.

Un PreferenceDataStore consente di utilizzare un backend di archiviazione personalizzato per rendere persistenti i valori Preference. Per ulteriori informazioni consulta Utilizzare un datastore personalizzato.

Lettura dei valori delle preferenze

Per recuperare l'oggetto SharedPreferences in uso, chiama PreferenceManager.getDefaultSharedPreferences() Sebbene questo metodo funzioni da qualsiasi punto dell'applicazione, ti consigliamo di suddividi la tua app in livelli. Per ulteriori informazioni, consulta la sezione Dati .

Ad esempio, dato un valore EditTextPreference con chiave "signature", come che segue:

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

Puoi recuperare il valore salvato per Preference a livello globale, come segue:

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", "");

Monitora le modifiche ai valori delle preferenze

Per rilevare le modifiche ai valori di Preference, puoi scegliere tra due interfacce:

• Preference.OnPreferenceChangeListener
• SharedPreferences.OnSharedPreferenceChangeListener

La tabella seguente mostra le differenze tra le due interfacce:

OnPreferenceChangeListener	OnSharedPreferenceChangeListener
Impostato su un singolo Preference.	Si applica a tutti gli oggetti Preference.
Richiamato quando Preference sta per modificare il valore salvato, anche se il valore in sospeso è uguale a quello salvato.	Richiamato solo quando cambia il valore salvato di Preference.
Chiamata solo tramite la raccolta di Preference. Una parte separata dell'applicazione può modificare il valore salvato.	Richiamato ogni volta che il valore salvato cambia, anche se proviene da un dell'applicazione.
Richiamato prima del salvataggio del valore in attesa.	Richiamato dopo il salvataggio del valore.
Hai chiamato con SharedPreferences o una PreferenceDataStore.	Chiamata soltanto con l'utilizzo di SharedPreferences.

Implementare OnPreferenceChangeListener

L'implementazione di un OnPreferenceChangeListener consente di rimanere in ascolto di un messaggio in attesa cambia nel valore di Preference. Poi puoi verificare se la modifica . Ad esempio, il seguente codice mostra come ascoltare una modifica al metodo valore di un EditTextPreference con una chiave di "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;
}

Poi devi impostare il listener direttamente con setOnPreferenceChangeListener(), come segue:

Kotlin

preference.onPreferenceChangeListener = ...

Java

preference.setOnPreferenceChangeListener(...);

Implementazione di OnSharedPreferenceChangeListener

Quando mantieni valori Preference utilizzando SharedPreferences, puoi anche usare un SharedPreferences.OnSharedPreferenceChangeListener per ascoltare le modifiche. In questo modo puoi rilevare quando vengono modificati i valori salvati da Preference ad esempio per sincronizzare le impostazioni con un server. L'esempio seguente mostra come rimane in ascolto di una modifica al valore di un EditTextPreference con una chiave "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 il listener utilizzando registerOnSharedPreferenceChangedListener(), come segue:

Kotlin

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

Java

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

Avviso: per evitare la garbage collection involontaria, archivia un riferimento efficace a l'ascoltatore. Quando chiami registerOnSharedPreferenceChangeListener(), SharedPreferenceManager non memorizza un riferimento significativo al listener. A risolvere questo problema, puoi implementare onSharedPreferenceChanged() direttamente PreferenceFragmentCompat. Puoi anche creare una variabile di istanza, come mostrato nel seguente esempio:

Kotlin

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

Java

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

Per una corretta gestione del ciclo di vita in Activity o Fragment, registrati e annulla la registrazione di questo listener nei callback onResume() e onPause(), come mostrato nel seguente esempio:

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

Utilizza un datastore personalizzato

Anche se consigliamo di mantenere gli oggetti Preference in modo permanente utilizzando SharedPreferences, puoi anche usare un datastore personalizzato. Un datastore personalizzato può essere utile se l'applicazione rende persistenti i valori su un database o se i valori sono specifici di un dispositivo, mostrate nei seguenti esempi.

Implementare il datastore

Per implementare un datastore personalizzato, crea una classe che si estende PreferenceDataStore. L'esempio seguente crea un datastore che gestisce String valori:

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: solo i metodi di override utilizzati dagli oggetti Preference. Chiamata in corso un metodo che non hai implementato genera un UnsupportedOperationException.

Esegui operazioni dispendiose in termini di tempo dal thread principale per evitare di bloccare l'utente a riga di comando. Poiché è possibile che Fragment o Activity contengano il parametro l'eliminazione del datastore mantenendo un valore permanente, serializza i dati in modo da di non perdere i valori modificati dall'utente.

Abilita il datastore

Dopo aver implementato il datastore, imposta il nuovo datastore onCreatePreferences() in modo che gli oggetti Preference rimangano valori con anziché utilizzare il datastore SharedPreferences predefinito. Puoi attivare un datastore per ogni Preference o per l'intera gerarchia.

Per abilitare un datastore personalizzato per un valore Preference specifico, chiama setPreferenceDataStore() su Preference, come mostrato nell'esempio seguente:

Kotlin

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

Java

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

Per abilitare un datastore personalizzato per un'intera gerarchia, chiama setPreferenceDataStore() il giorno PreferenceManager:

Kotlin

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

Java

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

Un datastore impostato per un Preference specifico esegue l'override di qualsiasi datastore che sia impostata per la gerarchia corrispondente. Nella maggior parte dei casi, imposti un datastore dell'intera gerarchia.

Nota: se imposti un datastore per Preference dopo che Preference è associato alla gerarchia, il valore iniziale di Preference non è propagati di nuovo.