Personalizar suas configurações   Part of Android Jetpack.

Este tópico descreve como personalizar Preferences na sua hierarquia.

Encontrar Preferences

Para acessar uma Preference individual, como ao extrair ou definir um valor da Preference, use PreferenceFragmentCompat.findPreference(). Esse método pesquisa por uma Preference em toda a hierarquia com a chave fornecida.

Por exemplo, no caso de uma EditTextPreference com a chave "signature":

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

É possível recuperar essa Preference usando este 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
}

Controlar a visibilidade da Preference

É possível controlar que Preferences serão visíveis ao usuário quando ele acessar uma tela de configurações. Por exemplo, se uma Preference específica for relevante somente quando um recurso estiver ativado, é recomendável ocultá-la quando esse recurso estiver desativado.

Para exibir uma Preference apenas quando uma condição for atendida, primeiro defina a visibilidade dela como “false” no XML, conforme exibido no exemplo abaixo:

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

Em seguida, em onCreatePreferences(), mostre a Preference quando a condição correspondente for atendida:

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

Atualizar resumos dinamicamente

Uma Preference que mantém dados exibirá o valor atual no resumo para que o usuário possa entender melhor o estado atual dela. Por exemplo, EditTextPreference exibirá o valor de texto salvo, e ListPreference mostrará a entrada da lista selecionada. Além disso, algumas Preferences podem precisar atualizar o resumo com base no estado interno ou externo do aplicativo, como uma Preference que exibe o número de versão . Para fazer isso, use SummaryProvider.

Usar SimpleSummaryProvider

ListPreference e EditTextPreference. incluem implementações de SummaryProvider que exibem automaticamente o valor salvo da Preference como o resumo. Se nenhum valor for salvo, ela exibirá “Não definido".

Para ativar essas implementações a partir de XML, defina app:useSimpleSummaryProvider="true".

Como alternativa, é possível usar ListPreference.SimpleSummaryProvider.getInstance() e EditTextPreference.SimpleSummaryProvider.getInstance() no código para receber uma instância simples de SummaryProvider e defini-la na Preference, conforme exibido no exemplo a seguir:

Kotlin

listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance()
editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()

Java

listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance());
editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());

Usar um SummaryProvider personalizado

É possível criar um SummaryProvider próprio e modificar provideSummary() para personalizar o resumo sempre que ele for solicitado pela Preference. Por exemplo, EditTextPreference abaixo exibe o tamanho do valor salvo como resumo:

Por exemplo, imagine a seguinte EditTextPreference:

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

Em onCreatePreferences(), crie um novo SummaryProvider e modifique provideSummary() para retornar o resumo que será exibido:

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

O resumo da Preference exibirá o tamanho do valor salvo ou “Não definido" quando não houver um valor salvo.

Ações da Preference

Quando uma Preference é tocada, ela pode desempenhar uma ação específica. Por exemplo, uma Preference pode atuar como link para uma parte separada do seu aplicativo. Caso queira adicionar uma ação a uma Preference, defina um Intent na Preference diretamente ou configure um OnPreferenceClickListener para aplicar uma lógica mais específica.

Definir um intent

É possível definir um Intent em uma Preference para iniciar um novo Fragment, Activity ou aplicativo separado sempre que a Preference for tocada. Isso é igual a usar Context.startActivity() com um Intent específico.

Para definir um Intent no XML, use uma tag <intent> aninhada. O exemplo abaixo define um Intent que inicia uma Activity:

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

Como alternativa, você pode usar setIntent() diretamente em uma Preference, como exibido abaixo:

Kotlin

val intent = Intent(context, ExampleActivity::class.java)
activityPreference.setIntent(intent)

Java

Intent intent = new Intent(getContext(), ExampleActivity.class);
activityPreference.setIntent(intent);

Além disso, é possível incluir adicionais com um Intent por meio do 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>

Veja um exemplo de Preference com um Intent que inicia uma página da 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

Você pode definir OnPreferenceClickListener em uma Preference. Isso adiciona uma callback a onPreferenceClick() quando a Preference é tocada. Por exemplo, é possível usar o listener para acessar outro Fragment ou Activity, caso sua lógica de navegação seja mais complexa.

Para definir OnPreferenceClickListener, use um código semelhante a este:

Kotlin

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

Java

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