Impostazioni   Componente di Android Jetpack.

Le impostazioni consentono agli utenti di modificare la funzionalità e il comportamento di un'app. Possono influire sul comportamento in background, ad esempio sulla frequenza con cui l'app sincronizza i dati con il cloud, oppure possono avere un ambito più ampio, ad esempio modificare i contenuti e la presentazione dell'interfaccia utente.

Nota: questo documento spiega come utilizzare la libreria AndroidX Preference. A partire da Android 10, la libreria android.preference della piattaforma è deprecata.

Per integrare le impostazioni configurabili dall'utente nella tua app, utilizza la libreria AndroidX Preference. Questa libreria gestisce l'interfaccia utente e interagisce con lo spazio di archiviazione in modo da definire solo le singole impostazioni che l'utente può configurare. La libreria è dotata di un tema Material Design che offre un'esperienza utente coerente su dispositivi e versioni del sistema operativo.

Inizia

Un Preference è l'elemento di base della libreria delle preferenze. Una schermata delle impostazioni contiene una Preference gerarchia. Puoi definire questa gerarchia come risorsa XML oppure creare una gerarchia nel codice.

Le sezioni seguenti descrivono come creare una semplice schermata delle impostazioni utilizzando la libreria AndroidX Preference.

Prima di iniziare, aggiungi la dipendenza Libreria delle preferenze al file build.gradle:

Groovy

dependencies {
    implementation "androidx.preference:preference-ktx:1.2.0"
}

Kotlin

dependencies {
    implementation("androidx.preference:preference-ktx:1.2.0")
}

Dopo una sincronizzazione Gradle, puoi passare alla parte XML dell'attività.

Creare una gerarchia

Nel progetto, vai alla cartella res/xml, crea un file preferences.xml e aggiungi il seguente codice:

<PreferenceScreen
    xmlns:app="http://schemas.android.com/apk/res-auto">

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

    <Preference
        app:key="feedback"
        app:title="Send feedback"
        app:summary="Report technical issues or suggest new features"/>

</PreferenceScreen>

Questa gerarchia contiene due oggetti Preference: un SwitchPreferenceCompat che consente agli utenti di attivare e disattivare un'impostazione e un Preference di base senza widget.

Quando crei una gerarchia, ogni Preference deve avere una chiave univoca.

Nota: consulta le linee guida per la progettazione delle impostazioni di Android per ricevere consigli su come organizzare la schermata delle impostazioni.

Aumentare la gerarchia

Per espandere una gerarchia da un attributo XML, crea un PreferenceFragmentCompat, sostituisci onCreatePreferences() e fornisci la risorsa XML da espandere, come mostrato nell'esempio seguente:

Kotlin

class MySettingsFragment : PreferenceFragmentCompat() {
    override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
        setPreferencesFromResource(R.xml.preferences, rootKey)
    }
}

Java

public class MySettingsFragment extends PreferenceFragmentCompat {
    @Override
    public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
        setPreferencesFromResource(R.xml.preferences, rootKey);
    }
}

Puoi quindi aggiungere questo Fragment al tuo Activity come faresti con qualsiasi altro Fragment:

Kotlin

class MySettingsActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        supportFragmentManager
                .beginTransaction()
                .replace(R.id.settings_container, MySettingsFragment())
                .commit()
    }
}

Java

public class MySettingsActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        getSupportFragmentManager()
                .beginTransaction()
                .replace(R.id.settings_container, new MySettingsFragment())
                .commit();
    }
}

Il risultato è mostrato nell'immagine seguente:

Figura 1. Una schermata delle impostazioni creata utilizzando due oggetti Preference.

Monitora le preferenze

Puoi ottenere un evento quando una preferenza cambia registrando un listener per l'evento:

Kotlin

findPreference<SwitchPreferenceCompat>("notifications")
    ?.setOnPreferenceChangeListener { _, newValue ->
        Log.d("Preferences", "Notifications enabled: $newValue")
        true // Return true if the event is handled.
    }

findPreference<Preference>("feedback")
    ?.setOnPreferenceClickListener {
        Log.d("Preferences", "Feedback was clicked")
        true // Return true if the click is handled.
    }

Java

SwitchPreferenceCompat notificationsPref = findPreference("notifications");

if (notificationsPref != null) {
    notificationsPref.setOnPreferenceChangeListener((preference, newValue) -> {
        Log.d("Preferences", String.format("Notifications enabled: %s", newValue));
        return true; // Return true if the event is handled.
    });
}

Preference feedbackPref = findPreference("feedback");

if (feedbackPref != null) {
    feedbackPref.setOnPreferenceClickListener((preference) -> {
        Log.d("Preferences", "Feedback was clicked");
        return true; // Return true if the event is handled.
    });
}

Leggi il valore della preferenza corrente

PreferenceFragmentCompat nasconde gran parte dei macchinari necessari per salvare e leggere le preferenze. Tuttavia, tutto viene archiviato utilizzando SharedPreferences e puoi leggere questi valori come faresti normalmente con SharedPreferences:

Kotlin

val preferences = PreferenceManager.getDefaultSharedPreferences(this).all

preferences.forEach {
    Log.d("Preferences", "${it.key} -> ${it.value}")
}

Java

var preferences = PreferenceManager.getDefaultSharedPreferences(context).getAll();

preferences.forEach((key, value) ->{
    Log.d("Preferences", String.format("%s -> %s", key, value));
});

Lo snippet precedente ottiene un'istanza del SharedPreferences predefinito per l'app, accede a tutti i valori memorizzati, li esegue in loop e li stampa in Logcat.