Esta página foi traduzida pela API Cloud Translation.

Personalizar suas configurações Parte do Android Jetpack.

Este documento descreve como personalizar Objetos Preference na hierarquia.

Encontrar preferências

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

Por exemplo, para acessar um EditTextPreference com um de "signature", faça o seguinte:

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

Recupere esse Preference usando o seguinte código:

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    val signaturePreference: EditTextPreference? = findPreference("signature")
    // Do something with this preference.
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    EditTextPreference signaturePreference = findPreference("signature");
    // Do something with this preference.
}

Controlar a visibilidade das preferências

Você pode controlar quais objetos Preference ficam visíveis para o usuário quando ele acesse a tela de configurações. Por exemplo, se uma determinada Preference for significativa somente quando um recurso correspondente estiver ativado, convém ocultar essa Preference quando o recurso estiver desativado.

Para mostrar uma Preference somente quando uma condição for atendida, primeiro defina a Preference. a visibilidade como falsa no XML, conforme mostrado no exemplo a seguir:

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

Em onCreatePreferences(), mostre a Preference quando o evento é atendida:

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    if(/*some feature*/) {
        val signaturePreference: EditTextPreference? = findPreference("signature")
        signaturePreference?.isVisible = true
    }
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    if(/*some feature*/) {
        EditTextPreference signaturePreference = findPreference("signature");
        if (signaturePreference != null) {
            signaturePreference.setVisible(true);
        }
    }
}

Atualizar resumos de forma dinâmica

Uma Preference que mantém dados precisa exibir o valor atual na um resumo para ajudar o usuário a entender melhor o estado atual do Preference: Por exemplo, uma EditTextPreference precisa mostrar o texto salvo. e um ListPreference precisa mostrar a entrada da lista selecionada. Você também pode têm Preference objetos que precisam atualizar o resumo com base em dados internos ou estado do app externo, por exemplo, uma Preference que mostra uma versão número Você pode fazer isso usando um SummaryProvider

Usar um SimpleSummaryProvider

ListPreference e EditTextPreference incluem implementações simples de SummaryProvider que exibem automaticamente o valor salvo de Preference como o resumo. Se nenhum valor for salvo, será exibida a mensagem definido".

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

Como alternativa, no código, é possível usar ListPreference.SimpleSummaryProvider.getInstance() e EditTextPreference.SimpleSummaryProvider.getInstance() para acessar a instância simples de SummaryProvider e, em seguida, defini-la no Preference, conforme mostrado 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

Você pode criar seu próprio SummaryProvider e substituir provideSummary() para personalizar o resumo sempre que ele for solicitado pela Preference. Para exemplo, a EditTextPreference a seguir exibe o comprimento do código como resumo:

Uma imagem mostrando um exemplo de EditTextPreference — **Figura 1**. Um exemplo de `EditTextPreference`.

Como exemplo, considere o seguinte EditTextPreference:

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

Em onCreatePreferences(), é possível criar um novo SummaryProvider e substituir provideSummary() para retornar o resumo que será exibido:

Kotlin

val countingPreference: EditTextPreference? = findPreference("counting")

countingPreference?.summaryProvider = SummaryProvider<EditTextPreference> { preference ->
    val text = preference.text
    if (text.isNullOrEmpty()) {
        "Not set"
    } else {
        "Length of saved value: " + text.length
    }
}

Java

EditTextPreference countingPreference = findPreference("counting");

if (countingPreference != null) {
    countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() {
        @Override
        public CharSequence provideSummary(EditTextPreference preference) {
            String text = preference.getText();
            if (TextUtils.isEmpty(text) || text == null){
                return "Not set";
            }
            return "Length of saved value: " + text.length();
        }
    });
}

O resumo de Preference mostra o tamanho do valor salvo ou "Não definido" quando não houver um valor salvo.

Personalizar uma caixa de diálogo EditTextPreference

Em uma caixa de diálogo EditTextPreference, é possível personalizar o comportamento do campo de texto da seguinte forma: anexar um OnBindEditTextListener. Esse listener é invocado quando a caixa de diálogo é mostrada ao usuário.

Como exemplo, você pode personalizar uma caixa de diálogo para aceitar apenas números. Primeiro, crie o EditTextPreference:

<EditTextPreference
        app:key="number"
        app:title="Numbers only preference"/>

Em seguida, em onCreatePreferences(), crie um novo OnBindEditTextListener e substitua onBindEditText() para personalizar o EditText quando ele for mostrado ao usuário.

Kotlin

val numberPreference: EditTextPreference? = findPreference("number")

numberPreference?.setOnBindEditTextListener { editText ->
    editText.inputType = InputType.TYPE_CLASS_NUMBER
}

Java

EditTextPreference numberPreference = findPreference("number");

if (numberPreference != null) {
    numberPreference.setOnBindEditTextListener(
            new EditTextPreference.OnBindEditTextListener() {
                @Override
                public void onBindEditText(@NonNull EditText editText) {
                    editText.setInputType(InputType.TYPE_CLASS_NUMBER);
                }
            });
}

Agora, quando a caixa de diálogo for mostrada ao usuário, o teclado será aberto somente em números para que o usuário só possa inserir números no EditText.

Ações de preferência

Uma Preference pode ter uma ação específica quando tocada. Por exemplo, Preference pode funcionar como um link para uma parte separada do seu app. Para adicionar uma ação a um Preference, é possível definir um Intent no Preference diretamente ou você é possível definir OnPreferenceClickListener para uma lógica mais específica.

Definir uma intent

Você pode definir uma Intent em uma Preference para iniciar uma nova Fragment. Activity ou app separado sempre que o Preference for tocado. Esta é a o mesmo que usar Context.startActivity() com um determinado Intent.

Você pode definir uma Intent em XML usando uma tag <intent>. O seguinte define um Intent que inicia um 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 um Preference, da seguinte maneira:

Kotlin

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

Java

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

Você também pode incluir extras com uma Intent usando 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 uma Preference com uma 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")

val webpagePreference = findPreference("webpage")
webpagePreference?.intent = intent

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("http://www.google.com"));
webpagePreference.setIntent(intent);

OnPreferenceClickListener

Você pode definir um OnPreferenceClickListener em uma Preference, o que adiciona uma callback para onPreferenceClick() quando o Preference for tocado. Por exemplo: você pode usar o listener para navegar para outro Fragment ou Activity se uma lógica mais complexa para lidar com a navegação.

Para definir um OnPreferenceClickListener, use um código semelhante ao seguinte:

Kotlin

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

Java

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