Configurações   Parte do Android Jetpack.

As configurações permitem que os usuários mudem a funcionalidade e o comportamento de um app. As configurações podem afetam o comportamento em segundo plano, como a frequência com que o app sincroniza dados com o nuvem, ou podem ter um alcance maior, como alterar o conteúdo e apresentação da interface do usuário.

Observação: este documento explica como usar o AndroidX Preference: biblioteca. Começando com o Android 10, a biblioteca android.preference da plataforma será descontinuada.

Para integrar definições configuráveis pelo usuário ao aplicativo, use a biblioteca de cliente do AndroidX Biblioteca de preferências. Essa biblioteca gerencia a interface do usuário e interage com Storage para que você defina apenas as configurações individuais que o usuário pode configurar. A biblioteca tem um tema do Material Design que oferece uma uma experiência do usuário consistente em todos os dispositivos e versões de SO.

Primeiros passos

Uma Preference é a criação básica da biblioteca Preference. Uma tela de configurações contém um Preference. hierarquia. É possível definir essa hierarquia como um recurso XML ou criar uma hierarquia no código.

As seções a seguir descrevem como criar uma tela de configurações simples usando o Biblioteca AndroidX Preference.

Antes de começar, adicione a dependência da biblioteca Preference ao build.gradle. arquivo:

Groovy

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

Kotlin

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

Após uma sincronização do Gradle, você pode passar para a parte XML da tarefa.

Criar uma hierarquia

No seu projeto, navegue até a pasta res/xml, crie um arquivo preferences.xml. e adicione o seguinte código a ela:

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

Essa hierarquia contém dois objetos Preference: um SwitchPreferenceCompat que permite aos usuários ativar e desativar uma configuração e uma Preference básica sem widget.

Ao criar uma hierarquia, cada Preference precisa ter uma chave exclusiva.

Observação: consulte o Design de configurações do Android Diretrizes para ver recomendações sobre como organizar sua tela de configurações.

Inflar a hierarquia

Para inflar uma hierarquia a partir de um atributo XML, crie uma PreferenceFragmentCompat, sobrepor-se onCreatePreferences(), e forneça o recurso XML que será inflado, conforme mostrado no exemplo a seguir:

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

Em seguida, você pode adicionar esse Fragment à Activity como faria com qualquer outro 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();
    }
}

O resultado é mostrado nesta imagem:

Figura 1. Uma tela de configurações criada usando dois Preference. objetos.

Monitorar as preferências

Você pode receber um evento quando uma preferência for alterada registrando um listener para ele:

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

Ler o valor da preferência atual

PreferenceFragmentCompat oculta grande parte do equipamento envolvido na economia e lendo as preferências. No entanto, tudo é armazenado usando SharedPreferences. Esses valores podem ser lidos como você faria normalmente 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));
});

O snippet anterior extrai uma instância do SharedPreferences padrão para o aplicativo, acessa todos os valores armazenados, passa por eles e os exibe Logcat.