Personalizza le impostazioni Componente di Android Jetpack.

Questo documento descrive come personalizzare gli oggetti Preference nella gerarchia.

Trova preferenze

Per accedere a un singolo Preference, ad esempio per recuperare o impostare un valore Preference, utilizza PreferenceFragmentCompat.findPreference(). Questo metodo cerca Preference nell'intera gerarchia con la chiave specificata.

Ad esempio, per accedere a un elemento EditTextPreference con una chiave di "signature", segui questi passaggi:

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

Recupera questo Preference utilizzando il seguente codice:

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

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

Controlla la visibilità delle preferenze

Puoi controllare quali oggetti Preference sono visibili all'utente quando accede a una schermata delle impostazioni. Ad esempio, se un determinato Preference è significativo solo quando una funzionalità corrispondente è attivata, potresti nascondere Preference quando la funzionalità è disattivata.

Per mostrare un elemento Preference solo quando una condizione è soddisfatta, imposta prima la visibilità di Preference su false nel file XML, come mostrato nell'esempio seguente:

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

In onCreatePreferences(), mostra Preference quando è soddisfatta la condizione corrispondente:

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

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

Aggiornare i riepiloghi in modo dinamico

Un elemento Preference con dati persistenti deve mostrare il valore corrente nel riepilogo per aiutare l'utente a comprendere meglio lo stato attuale di Preference. Ad esempio, un EditTextPreference deve mostrare il valore di testo salvato e un ListPreference deve mostrare la voce di elenco selezionata. Potresti anche avere oggetti Preference il cui riepilogo deve essere aggiornato in base allo stato dell'app interno o esterno, ad esempio un oggetto Preference che mostra un numero di versione. A questo scopo, utilizza un SummaryProvider.

Utilizzare un SimpleSummaryProvider

ListPreference e EditTextPreference include semplici implementazioni di SummaryProvider che mostrano automaticamente il valore salvato di Preference come riepilogo. Se non viene salvato alcun valore, viene visualizzato "Non impostato".

Per abilitare queste implementazioni da XML, imposta app:useSimpleSummaryProvider="true".

In alternativa, nel codice puoi usare ListPreference.SimpleSummaryProvider.getInstance() e EditTextPreference.SimpleSummaryProvider.getInstance() per ottenere la semplice istanza SummaryProvider e poi impostarla su Preference, come mostrato nell'esempio seguente:

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

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

Utilizza un valore SummaryProvider personalizzato

Puoi creare il tuo SummaryProvider e sostituire provideSummary() per personalizzare il riepilogo ogni volta che viene richiesto dal Preference. Ad esempio, l'elemento EditTextPreference seguente mostra la lunghezza del valore salvato come riepilogo:

Supponiamo, ad esempio, che: EditTextPreference

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

In onCreatePreferences() puoi creare un nuovo SummaryProvider e sostituire provideSummary() per restituire il riepilogo da visualizzare:

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

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

Il riepilogo di Preference mostra la lunghezza del valore salvato o "Non impostato" quando non esiste alcun valore salvato.

Personalizzare una finestra di dialogo EditTextPreference

All'interno di una finestra di dialogo EditTextPreference puoi personalizzare il comportamento del campo di testo allegando un OnBindEditTextListener. Questo listener viene richiamato quando la finestra di dialogo viene mostrata all'utente.

Ad esempio, puoi personalizzare una finestra di dialogo per accettare solo numeri. Innanzitutto, crea il EditTextPreference:

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

Quindi, in onCreatePreferences(), crea un nuovo OnBindEditTextListener e esegui l'override di onBindEditText() per personalizzare EditText quando viene mostrato all'utente.

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

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

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

Ora, quando la finestra di dialogo viene mostrata all'utente, la tastiera si apre in modalità solo numerica, in modo che l'utente possa inserire solo numeri nel campo EditText.

Azioni preferite

Quando viene toccato, un Preference può avere un'azione specifica. Ad esempio, un Preference può fungere da link a una parte separata della tua app. Per aggiungere un'azione a un Preference, puoi impostare un Intent direttamente in Preference o puoi impostare un OnPreferenceClickListener per una logica più specifica.

Imposta un intent

Puoi impostare un Intent su un Preference per avviare una nuova app Fragment, Activity o separata ogni volta che tocchi il Preference. È come utilizzare Context.startActivity() con un Intent specifico.

Puoi impostare un Intent in XML utilizzando un tag <intent> nidificato. Il seguente esempio definisce un Intent che avvia un Activity:

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

In alternativa, puoi utilizzare setIntent() direttamente su un Preference, come indicato di seguito:

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

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

Puoi anche includere contenuti extra con un Intent utilizzando il formato 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>

Ecco un esempio di Preference con Intent che avvia una pagina web:

<Preference
        app:key="webpage"
        app:title="View webpage">
    <intent
            android:action="android.intent.action.VIEW"
            android:data="http://www.google.com" />
</Preference>

val intent = Intent(Intent.ACTION_VIEW)
intent.data = Uri.parse("http://www.google.com")

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

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

OnPreferenceClickListener

Puoi impostare un OnPreferenceClickListener su un Preference, in modo da aggiungere un callback a onPreferenceClick() quando viene toccato il Preference. Ad esempio, puoi utilizzare il listener per passare a un altro Fragment o Activity se hai una logica più complessa per la gestione della navigazione.

Per impostare un OnPreferenceClickListener, utilizza un codice simile al seguente:

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

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