المكوّنات والسمات المفضّلة جزء من Android Jetpack.

يوضِّح هذا الموضوع بعض مكونات وسمات Preference الأكثر استخدامًا، والتي يتم استخدامها عند إنشاء شاشة الإعدادات.

مكوّنات التفضيل

يوضِّح هذا القسم مكوّنات Preference الشائعة. لمزيد من المعلومات، انظر الصفحات المرجعية المقابلة لكل مكون.

البنية الأساسية المفضّلة

PreferenceFragmentCompat - Fragment يعالج عرض تدرج هرمي تفاعلي مكوّن من Preference عناصر.

حاويات التفضيل

PreferenceScreen - حاوية من المستوى الأعلى تمثّل شاشة الإعدادات. هذا هو المكوّن الجذري في التسلسل الهرمي Preference.

PreferenceCategory - حاوية تُستخدم لتجميع Preferences متشابهة. تعرض السمة PreferenceCategory عنوان فئة وتفصل مرئيًا بين مجموعات Preferences.

الإعدادات المفضَّلة الفردية

Preference - اللبنة الأساسية التي تمثل إعدادًا فرديًا في حال ضبط سياسة Preference على الإبقاء، يتوفّر لها زوج مفاتيح/قيمة مقابل يتيح للمستخدم اختيار الإعداد الذي يمكن الوصول إليه من مكان آخر في التطبيق.

EditTextPreference - Preference تحتفظ بقيمة String. يمكن للمستخدمين النقر على Preference لإطلاق مربّع حوار يتضمّن حقل النص الذي يتيح للمستخدم تغيير القيمة الثابتة.

ListPreference - Preference تحتفظ بقيمة سلسلة. يمكن للمستخدمين تغيير هذه القيمة في مربع حوار يحتوي على قائمة بأزرار الاختيار ذات التسميات المقابلة.

MultiSelectListPreference - Preference تستخدم مجموعة من السلاسل يمكن للمستخدمين تغيير هذه القيم في مربع حوار يحتوي على قائمة بمربعات الاختيار مع التسميات المقابلة.

SeekBarPreference - Preference تحتفظ بقيمة عدد صحيح. يمكن تغيير هذه القيمة من خلال سحب شريط التقديم/الترجيع المقابل له والذي يظهر في تنسيق Preference.

SwitchPreferenceCompat - Preference تحتفظ بقيمة منطقية. يمكن تغيير هذه القيمة من خلال التفاعل مع التطبيق المصغّر الخاص بمفتاح التبديل أو من خلال النقر على تنسيق Preference.

CheckBoxPreference - Preference تحتفظ بقيمة منطقية. يمكن تغيير هذه القيمة من خلال التفاعل مع مربّع الاختيار المقابل أو النقر على تنسيق Preference.

سمات التفضيل

في ما يلي بعض السمات الأكثر استخدامًا التي تضبط مظهر Preference وسلوكه.

السمات العامة

title

تمثّل هذه السمة قيمة String التي تمثّل عنوان Preference.

مثال: app:title="Title"

summary

تمثّل هذه السمة قيمة String تمثّل ملخّص Preference.

مثال: app:summary="Summary"

icon

تمثّل هذه السمة Drawable الذي يمثّل الرمز Preference.

مثال: app:icon="@drawable/ic_camera"

key

قيمة String تمثّل المفتاح المستخدَم للاحتفاظ بقيمة Preference المرتبطة. ويتيح لك المفتاح تخصيص Preference بشكل أكبر أثناء وقت التشغيل. عليك ضبط مفتاح لكل Preference في التسلسل الهرمي.

مثال: app:key="key"

enabled

قيمة منطقية تشير إلى ما إذا كان بإمكان المستخدمين التفاعل مع Preference. وعندما تكون هذه القيمة false، تظهر السمة Preference باللون الرمادي، ولا يمكن للمستخدمين التفاعل معها. القيمة التلقائية هي true.

مثال: app:enabled="false"

selectable

قيمة منطقية تشير إلى ما إذا كان بإمكان المستخدمين التفاعل مع Preference. القيمة التلقائية هي true.

مثال: app:selectable="false"

isPreferenceVisible

قيمة منطقية تشير إلى ما إذا كانت الفئة Preference أو Preference مرئية يعادل ذلك طلب الرقم setVisible().

مثال: app:isPreferenceVisible="false"

defaultValue

يمثّل هذا المقياس القيمة التلقائية للسمة Preference. يتم ضبط هذه القيمة والاحتفاظ بها عند عدم العثور على قيمة أخرى غير متوفّرة للسمة Preference. ويعتمد نوع القيمة على سمة Preference المرتبطة بها.

مثال: app:defaultValue="true"

dependency

يُمثِّل مفتاح SwitchPreferenceCompat الذي يتحكّم في حالة Preference. وعند إيقاف مفتاح التبديل المقابل، يكون Preference غير مفعّل ولا يمكن تعديله.

مثال: app:dependency="parent"

سمات الفئة المفضّلة

initialExpandedChildrenCount

هي قيمة عدد صحيح تتيح سلوك Preference القابل للتوسيع. وتمثّل هذه القيمة الحد الأقصى لعدد العناصر الثانوية التي يتم عرضها في PreferenceGroup. يتم تصغير أي عناصر فرعية إضافية ويمكن عرضها من خلال النقر على زر التوسيع. بشكل تلقائي، تكون هذه القيمة هي Integer.MAX_VALUE، ويتم عرض جميع العناصر الثانوية.

تحذير: احرص على ضبط مفتاح على PreferenceCategory في حال استخدام هذه السمة ليتم حفظ الحالة واستعادتها بشكل صحيح عند تغيير الإعدادات (مثلاً، عند تدوير الشاشة).

مثال: app:initialExpandedChildrenCount="0"

سمات ListPreferences / MultiSelectListPreferences

entries

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

مثال: app:entries="@array/entries"

تحذير: تأكَّد من تطابق طول كلتا الصفيفتين، وأنّ فهرس كل مصفوفة يتطابق مع زوج الإدخال / القيمة الصحيح.

entryValues

مصفوفة الإدخالات المطلوب الاحتفاظ بها. تتطابق كل قيمة من هذه القيم حسب الفهرس مع مصفوفة إدخالات القائمة التي يتم عرضها للمستخدم.

مثال: app:entryValues="@array/values"