تخصيص إعداداتك جزء من 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
التالية طول قيمتها المحفوظة كملخّص:
لنفترض مثلاً أنّ الشرط التالي هو 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; });