Menyesuaikan setelan Bagian dari Android Jetpack.

Dokumen ini menjelaskan cara menyesuaikan objek Preference dalam hierarki Anda.

Menemukan preferensi

Untuk mengakses Preference tertentu, misalnya saat mendapatkan atau menyetel nilai Preference, gunakan PreferenceFragmentCompat.findPreference(). Metode ini menelusuri seluruh hierarki untuk menemukan Preference dengan kunci yang ditentukan.

Misalnya, untuk mengakses EditTextPreference dengan kunci "signature", lakukan hal berikut:

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

Ambil Preference ini menggunakan kode berikut:

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

Mengontrol visibilitas Preference

Anda dapat mengontrol objek Preference mana yang terlihat oleh pengguna saat mereka membuka layar setelan. Misalnya, jika Preference tertentu hanya bermakna jika fitur yang terkait diaktifkan, sebaiknya Anda menyembunyikan Preference saat fitur dinonaktifkan.

Untuk menampilkan Preference hanya jika sebuah kondisi terpenuhi, pertama-tama tetapkan visibilitas Preference dalam XML ke salah (false), seperti ditunjukkan dalam contoh berikut:

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

Di onCreatePreferences(), tampilkan Preference jika kondisi yang sesuai terpenuhi:

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

Memperbarui ringkasan secara dinamis

Preference yang menyimpan data harus menampilkan nilai saat ini dalam ringkasannya untuk membantu pengguna lebih memahami status Preference saat ini. Misalnya, EditTextPreference harus menampilkan nilai teks tersimpan, dan ListPreference harus menunjukkan entri daftar yang dipilih. Anda mungkin juga memiliki objek Preference yang perlu memperbarui ringkasannya berdasarkan status aplikasi internal atau eksternal—misalnya, Preference yang menampilkan nomor versi. Anda dapat melakukannya menggunakan SummaryProvider.

Menggunakan SimpleSummaryProvider

ListPreference dan EditTextPreference menyertakan implementasi SummaryProvider sederhana yang otomatis menampilkan nilai Preference yang disimpan sebagai ringkasan. Jika tidak ada nilai yang disimpan, tanda "Not set" akan ditampilkan.

Untuk mengaktifkan implementasi ini dari XML, tetapkan app:useSimpleSummaryProvider="true".

Atau, dalam kode, Anda dapat menggunakan ListPreference.SimpleSummaryProvider.getInstance() dan EditTextPreference.SimpleSummaryProvider.getInstance() untuk mendapatkan instance SummaryProvider sederhana, lalu menetapkannya di Preference, seperti ditunjukkan dalam contoh berikut:

Kotlin

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

Java

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

Menggunakan SummaryProvider kustom

Anda dapat membuat SummaryProvider sendiri dan mengganti provideSummary() untuk menyesuaikan ringkasan setiap kali diminta oleh Preference. Misalnya, EditTextPreference berikut menampilkan panjang nilai tersimpannya sebagai ringkasan:

Gambar yang menampilkan contoh EditTextPreference
Gambar 1. Contoh EditTextPreference.

Sebagai contoh, asumsikan EditTextPreference berikut:

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

Di onCreatePreferences(), Anda dapat membuat SummaryProvider baru dan mengganti provideSummary() untuk menampilkan ringkasan yang akan ditampilkan:

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

Ringkasan Preference menampilkan panjang nilai tersimpan, atau "Not set" jika tidak ada nilai tersimpan.

Menyesuaikan dialog EditTextPreference

Dalam dialog EditTextPreference, Anda dapat menyesuaikan perilaku kolom teks dengan menyertakan OnBindEditTextListener. Pemroses ini dipanggil saat dialog ditampilkan kepada pengguna.

Sebagai contoh, Anda dapat menyesuaikan dialog untuk hanya menerima angka. Pertama, buat EditTextPreference:

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

Selanjutnya, di onCreatePreferences(), buat OnBindEditTextListener baru dan ganti onBindEditText() untuk menyesuaikan EditText saat ditampilkan kepada pengguna.

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

Sekarang, saat dialog ditampilkan kepada pengguna, keyboard akan terbuka dalam mode angka saja, sehingga pengguna hanya dapat memasukkan angka ke dalam EditText.

Tindakan Preference

Preference dapat memiliki tindakan tertentu saat diketuk. Misalnya, Preference dapat bertindak sebagai link ke bagian terpisah dari aplikasi Anda. Untuk menambahkan tindakan ke Preference, Anda dapat menetapkan Intent di Preference secara langsung atau Anda dapat menetapkan OnPreferenceClickListener untuk logika yang lebih spesifik.

Menetapkan Intent

Anda dapat menetapkan Intent pada Preference untuk meluncurkan Fragment, Activity, atau aplikasi baru yang terpisah setiap kali Preference diketuk. Hal ini sama seperti menggunakan Context.startActivity() dengan Intent tertentu.

Anda dapat menyetel Intent dalam XML menggunakan tag <intent> bertingkat. Contoh berikut menentukan Intent yang meluncurkan Activity:

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

Atau, Anda dapat menggunakan setIntent() langsung di Preference, seperti berikut:

Kotlin

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

Java

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

Anda juga dapat menyertakan tambahan dengan Intent menggunakan 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>

Berikut adalah contoh Preference dengan Intent yang meluncurkan halaman 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

Anda dapat menetapkan OnPreferenceClickListener pada Preference, yang menambahkan callback ke onPreferenceClick() saat Preference diketuk. Misalnya, Anda dapat menggunakan pemroses untuk menavigasi ke Fragment atau Activity lain jika Anda memiliki logika yang lebih kompleks untuk menangani navigasi.

Untuk menetapkan OnPreferenceClickListener, gunakan kode yang mirip dengan berikut ini:

Kotlin

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

Java

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