تخصيص إعداداتك جزء من Android Jetpack.

يوضّح هذا المستند طريقة تخصيص عناصر Preference في التسلسل الهرمي.

العثور على الإعدادات المفضّلة

للوصول إلى عنصر Preference فردي، مثلاً عند الحصول على قيمة Preference أو ضبطها، استخدِم PreferenceFragmentCompat.findPreference(). تبحث هذه الطريقة في التدرّج الهرمي بأكمله عن Preference باستخدام المفتاح المعيّن.

على سبيل المثال، للوصول إلى EditTextPreference باستخدام مفتاح "signature"، قم بما يلي:

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

استرجع Preference باستخدام الرمز التالي:

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

التحكم في إمكانية رؤية الإعدادات المفضّلة

يمكنك تحديد عناصر Preference التي تظهر للمستخدم عند انتقاله إلى شاشة الإعدادات. على سبيل المثال، إذا كانت قيمة Preference معيّنة مفيدة فقط عند تفعيل ميزة مقابلة، ننصحك بإخفاء Preference عندما تكون الميزة غير مفعّلة.

لعرض Preference فقط عند استيفاء شرط معيّن، اضبط أولاً مستوى الرؤية Preference على "خطأ" في XML، كما هو موضّح في المثال التالي:

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

في onCreatePreferences()، يمكنك عرض العنصر Preference عند استيفاء الشرط المقابل:

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

تعديل الملخّصات ديناميكيًا

يجب أن تعرض سمة Preference التي تحتفظ بالبيانات القيمة الحالية في الملخص الخاص بها لمساعدة المستخدم على فهم الحالة الراهنة للسمة Preference بشكل أفضل. على سبيل المثال، يجب أن يعرض EditTextPreference قيمة النص المحفوظة، ويجب أن يعرض ListPreference إدخال القائمة الذي تم اختياره. قد يكون لديك أيضًا عناصر Preference تحتاج إلى تعديل ملخصها بناءً على حالة التطبيق الداخلية أو الخارجية، مثلاً Preference الذي يعرض رقم الإصدار. ويمكنك إجراء ذلك باستخدام SummaryProvider.

استخدام SimpleSummaryProvider

ListPreference وEditTextPreference يمكنك تضمين عمليات تنفيذ SummaryProvider البسيطة التي تعرض تلقائيًا قيمة Preference المحفوظة كملخّص. إذا لم يتم حفظ أي قيمة، فسيتم عرض "لم يتم التعيين".

لتفعيل عمليات التنفيذ هذه من XML، يجب ضبط app:useSimpleSummaryProvider="true".

بدلاً من ذلك، في الرمز، يمكنك استخدام ListPreference.SimpleSummaryProvider.getInstance() وEditTextPreference.SimpleSummaryProvider.getInstance() للحصول على مثيل SummaryProvider البسيط ثم ضبطه على Preference، كما هو موضّح في المثال التالي:

Kotlin

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

Java

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

استخدام مُقدِّم ملخّص مخصّص

يمكنك إنشاء SummaryProvider الخاص بك وإلغاء provideSummary() لتخصيص الملخّص في أي وقت يتم فيه طلبه من خلال Preference. على سبيل المثال، تعرض سمة EditTextPreference التالية طول قيمتها المحفوظة كملخّص:

الشكل 1. مثال EditTextPreference.

لنفترض مثلاً أنّ الشرط التالي هو EditTextPreference:

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

في onCreatePreferences()، يمكنك إنشاء SummaryProvider جديدة وإلغاء provideSummary() لعرض الملخّص المعروض:

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

يعرض ملخّص Preference طول القيمة المحفوظة أو "غير محدّدة" في حال عدم توفّر أي قيمة محفوظة.

تخصيص مربع الحوار EditTextPreferences

ضمن مربّع حوار EditTextPreference، يمكنك تخصيص سلوك حقل النص من خلال إرفاق OnBindEditTextListener. يتم استدعاء هذا المستمع عند عرض مربّع الحوار للمستخدم.

على سبيل المثال، يمكنك تخصيص مربّع حوار لقبول الأرقام فقط. أولاً، أنشئ EditTextPreference:

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

بعد ذلك، في onCreatePreferences()، يمكنك إنشاء OnBindEditTextListener جديد وتجاوز onBindEditText() لتخصيص EditText عندما يتم عرضه للمستخدم.

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

وعندما يظهر مربّع الحوار للمستخدم، يتم فتح لوحة المفاتيح في الوضع الرقمي فقط، ما يتيح للمستخدم إدخال أرقام فقط في EditText.

الإجراءات المفضَّلة

يمكن أن يؤدي النقر على Preference إلى إجراء محدّد. على سبيل المثال، يمكن استخدام Preference كرابط يؤدي إلى جزء منفصل من تطبيقك. لإضافة إجراء إلى Preference، يمكنك ضبط Intent على Preference مباشرةً أو ضبط OnPreferenceClickListener لإجراء منطق أكثر تحديدًا.

تحديد هدف

يمكنك ضبط Intent على Preference لتشغيل تطبيق Fragment جديد أو Activity أو تطبيق منفصل عند النقر على Preference. يشبه ذلك استخدام Context.startActivity() مع Intent محدّد.

يمكنك ضبط Intent في ملف XML باستخدام علامة <intent> مدمجة. يحدّد المثال التالي عنصر Intent يؤدي إلى تشغيل Activity:

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

يمكنك بدلاً من ذلك استخدام setIntent() مباشرةً على Preference كما يلي:

Kotlin

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

Java

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

يمكنك أيضًا إدراج محتوى إضافي مع Intent باستخدام 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>

في ما يلي مثال على Preference مع Intent يؤدي إلى تشغيل صفحة ويب:

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

Onتفضيلات ClickListener

يمكنك ضبط OnPreferenceClickListener على Preference، ما يؤدي إلى إضافة رد على onPreferenceClick() عند النقر على Preference. على سبيل المثال، يمكنك استخدام أداة المستمع للانتقال إلى عنصر Fragment آخر أو Activity آخر إذا كان لديك منطق أكثر تعقيدًا للتعامل مع التنقّل.

لضبط OnPreferenceClickListener، استخدِم رمزًا مشابهًا لما يلي:

Kotlin

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

Java

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