تخصيص الإعدادات جزء من 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
التي تحتفظ بالبيانات القيمة الحالية
summary لمساعدة المستخدم على فهم الحالة الراهنة
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
التالية طول المسافة المحفوظة
القيمة كالملخص:
![صورة تعرض مثالاً EditTextPreference](https://developer.android.google.cn/static/develop/ui/views/components/settings/images/settings-customsummaryprovider.png?authuser=9&hl=ar)
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
" طول القيمة المحفوظة أو الحالة "لم يتم الضبط".
عند عدم وجود قيمة محفوظة.
تخصيص مربّع الحوار EditTextPreference
في مربّع حوار 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);
OnPreferenceClickListener
يمكنك ضبط OnPreferenceClickListener
على Preference
، ما يؤدي إلى إضافة
معاودة الاتصال بـ onPreferenceClick()
عند النقر على Preference
. على سبيل المثال:
يمكنك استخدام المستمع للانتقال إلى Fragment
أو Activity
آخر إذا
لديها منطق أكثر تعقيدًا للتعامل مع التنقل.
لضبط OnPreferenceClickListener
، يمكنك استخدام رمز مشابه لما يلي:
Kotlin
onClickPreference.setOnPreferenceClickListener({ // Do something. true })
Java
onClickPreference.setOnPreferenceClickListener(preference -> { // Do something. return true; });