Personalizzare le impostazioni Parte di Android Jetpack.

Questo documento descrive come personalizzare Preference di oggetti nella gerarchia.

Trovare le preferenze

Per accedere a un singolo Preference, ad esempio quando ottieni o imposti un Valore Preference, utilizza PreferenceFragmentCompat.findPreference() Questo metodo cerca nell'intera gerarchia un Preference con la chiave specificata.

Ad esempio, per accedere a una EditTextPreference con un di "signature", procedi nel seguente modo:

<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 lo apri una schermata delle impostazioni. Ad esempio, se un determinato Preference è sia significativa solo quando una funzionalità corrispondente è abilitata, potresti decidere di nascondere che Preference quando la funzionalità è disattivata.

Per mostrare un Preference solo quando una condizione è soddisfatta, imposta prima Preference la visibilità 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 i valori corrispondenti è soddisfatta:

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

Aggiorna dinamicamente i riepiloghi

Un Preference che mantiene i dati deve visualizzare il valore corrente nel summary per aiutare l'utente a comprendere meglio lo stato attuale del Preference. Ad esempio, EditTextPreference deve mostrare il testo salvato e ListPreference deve mostrare la voce dell'elenco selezionata. Potresti inoltre avere Preference oggetti che devono aggiornare il riepilogo in base a query stato esterno dell'app, ad esempio un Preference che mostra una versione numero. Puoi farlo utilizzando un SummaryProvider

Utilizza un SimpleSummaryProvider

ListPreference e EditTextPreference includono semplici implementazioni di SummaryProvider che mostrano automaticamente valore Preference salvato come riepilogo. Se non viene salvato alcun valore, viene visualizzata la dicitura "Non impostare."

Per attivare 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 impostarla 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 ed eseguire l'override provideSummary() per personalizzare il riassunto ogni volta che viene richiesto da Preference. Per ad esempio, il seguente EditTextPreference mostra la lunghezza del relativo file come riepilogo:

Supponi, ad esempio, di avere il seguente valore EditTextPreference:

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

In onCreatePreferences(), puoi creare un nuovo SummaryProvider ed eseguire l'override 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 Preference mostra la lunghezza del valore salvato o dello stato "Non impostato" se non esistono valori salvati.

Personalizzare una finestra di dialogo EditTextPreference

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

Ad esempio, puoi personalizzare una finestra di dialogo in modo da accettare solo numeri. Per prima cosa, crea EditTextPreference:

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

Poi in onCreatePreferences(), crea un nuovo OnBindEditTextListener e sostituisci onBindEditText() per personalizzare EditText quando viene mostrato 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 solo in formato numerico in modo che l'utente possa inserire solo numeri nell'EditText.

Azioni preferite

Un Preference può avere un'azione specifica quando viene toccato. 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 su Preference o puoi impostare OnPreferenceClickListener: per una logica più specifica.

Imposta un intent

Puoi impostare un Intent su un Preference per lanciare un nuovo Fragment, Activity o un'app separata ogni volta che tocchi Preference. Questo è il come utilizzare Context.startActivity() con un determinato Intent.

Puoi impostare un Intent in XML utilizzando un tag <intent> nidificato. Le seguenti 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 segue:

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

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

Puoi anche includere extra con un Intent utilizzando un file 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 apre 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);

Listener di clicpreferenza

Puoi impostare un OnPreferenceClickListener su un Preference, il che aggiunge un callback a onPreferenceClick() quando viene toccato Preference. Ad esempio: puoi utilizzare il listener per passare a un altro Fragment o Activity se hanno una logica più complessa per gestire la navigazione.

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

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

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