Sesuaikan setelan Anda Bagian dari Android Jetpack.

Dokumen ini menjelaskan cara menyesuaikan Objek Preference dalam hierarki Anda.

Temukan 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 dari "signature", lakukan hal berikut:

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

Ambil Preference ini menggunakan kode berikut:

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

Mengontrol visibilitas Preference

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

Untuk menampilkan Preference hanya saat sebuah kondisi terpenuhi, tetapkan Preference terlebih dahulu visibilitas ke false dalam XML, seperti ditunjukkan dalam contoh berikut:

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

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

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

Memperbarui ringkasan secara dinamis

Preference yang mempertahankan data harus menampilkan nilai saat ini di ringkasan untuk membantu pengguna lebih memahami status saat ini Preference. Misalnya, EditTextPreference harus menampilkan teks yang disimpan nilai, dan ListPreference harus menunjukkan entri daftar yang dipilih. Anda mungkin juga memiliki objek Preference yang perlu memperbarui ringkasannya berdasarkan status aplikasi eksternal—misalnya, Preference yang menampilkan versi angka Anda dapat melakukannya dengan 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, akan ditampilkan "Tidak siap."

Untuk mengaktifkan implementasi ini dari XML, setel 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:

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

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. Sebagai contoh, EditTextPreference berikut menampilkan panjang file yang disimpan nilai sebagai ringkasan:

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:

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

Ringkasan Preference menampilkan panjang nilai yang disimpan atau "Not set" ketika tidak ada nilai yang disimpan.

Menyesuaikan dialog EditTextPreference

Dalam dialog EditTextPreference, Anda dapat menyesuaikan perilaku kolom teks dengan melampirkan 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 ke .

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

Sekarang, ketika dialog ditampilkan kepada pengguna, keyboard akan terbuka dalam format numerik saja , sehingga pengguna hanya dapat memasukkan angka ke dalam EditText.

Tindakan Preference

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

Menetapkan Intent

Anda dapat menyetel Intent di Preference untuk meluncurkan Fragment baru, Activity, atau aplikasi terpisah setiap kali Preference diketuk. Ini adalah sama seperti menggunakan Context.startActivity() dengan Intent tertentu.

Anda dapat menyetel Intent dalam XML menggunakan tag <intent> bertingkat. Hal berikut contoh 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() secara langsung di Preference, seperti berikut:

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

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>

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

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

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

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

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