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](https://developer.android.google.cn/static/develop/ui/views/components/settings/images/settings-customsummaryprovider.png?authuser=19&hl=pt-br)
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; });