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

يصف هذا المستند طريقة تخصيص Preference في التدرج الهرمي.

البحث عن الإعدادات المفضّلة

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

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

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

يمكنك استرداد Preference باستخدام الرمز التالي:

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

التحكّم في إذن الوصول إلى الإعدادات المفضّلة

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

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

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

في onCreatePreferences()، يتم عرض Preference عندما يكون تحقق الشرط:

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

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

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

استخدام SimpleSummaryProvider

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

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

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

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

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

استخدام ملخّص ملخّص مخصّص

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

على سبيل المثال، يمكنك افتراض ما يلي من EditTextPreference:

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

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

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

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

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

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

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

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

الخطوة التالية، في "onCreatePreferences()"، إنشاء OnBindEditTextListener جديدة إلغاء onBindEditText() لتخصيص EditText عند عرضها على المستخدم.

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

والآن، عندما يظهر مربع الحوار للمستخدم، تفتح لوحة المفاتيح ، حتى يتمكّن المستخدم من إدخال الأرقام فقط في 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" كما يلي:

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

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>

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

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

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

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

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