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"
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Preference components and attributes\nPart of [Android Jetpack](/jetpack).\n=========================================================================\n\nThis topic describes some of the most commonly-used `Preference` components and\nattributes used when building a settings screen.\n\nPreference components\n---------------------\n\nThis section describes common `Preference` components. For more information, see\nthe corresponding reference pages for each component.\n\n### Preference infrastructure\n\n[`PreferenceFragmentCompat`](/reference/androidx/preference/PreferenceFragmentCompat) -\na [`Fragment`](/reference/kotlin/androidx/fragment/app/Fragment) that handles\ndisplaying an interactive hierarchy of `Preference` objects.\n\n### Preference containers\n\n[`PreferenceScreen`](/reference/androidx/preference/PreferenceScreen) -\na top-level container that represents a settings screen. This is the root\ncomponent of your `Preference` hierarchy.\n\n[`PreferenceCategory`](/reference/androidx/preference/PreferenceCategory) -\na container that is used to group similar `Preferences`. A `PreferenceCategory`\ndisplays a category title and visually separates groups of `Preferences`.\n\n### Individual Preferences\n\n[`Preference`](/reference/androidx/preference/Preference) - the basic\nbuilding block that represents an individual setting. If a `Preference` is set\nto persist, it has a corresponding key-value pair that holds the user's choice\nfor the setting that can be accessed elsewhere in the application.\n\n[`EditTextPreference`](/reference/androidx/preference/EditTextPreference) -\na `Preference` that persists a `String` value. Users can tap on the `Preference`\nto launch a dialog containing the text field that allows the user to change the\npersisted value.\n\n[`ListPreference`](/reference/androidx/preference/ListPreference) - a\n`Preference` that persists a String value. Users can change this value in a\ndialog that contains a list of radio buttons with corresponding labels.\n\n[`MultiSelectListPreference`](/reference/androidx/preference/MultiSelectListPreference) -\na `Preference` that persists a set of Strings. Users can change these values in\na dialog that contains a list of checkboxes with corresponding labels.\n\n[`SeekBarPreference`](/reference/androidx/preference/SeekBarPreference) -\na `Preference` that persists an integer value. This value can be changed by\ndragging a corresponding seekbar that is displayed in the `Preference` layout.\n\n[`SwitchPreferenceCompat`](/reference/androidx/preference/SwitchPreferenceCompat) -\na `Preference` that persists a boolean value. This value can be changed by\ninteracting with the corresponding switch widget or by tapping on the\n`Preference` layout.\n\n[`CheckBoxPreference`](/reference/androidx/preference/CheckBoxPreference) -\na `Preference` that persists a boolean value. This value can be changed by\ninteracting with the corresponding checkbox or by tapping on the `Preference`\nlayout.\n| **Note:** Although `SwitchPreferenceCompat` and `CheckBoxPreference` store a boolean value and function in similar ways, we recommend using a `SwitchPreferenceCompat` where possible. For more information, see the [Android Settings Design Guidelines](https://source.android.com/devices/tech/settings/settings-guidelines#checkbox).\n\nPreference attributes\n---------------------\n\nListed below are some of the most commonly-used attributes that configure\n`Preference` appearance and behavior.\n| **Note:** Each attribute listed below has a corresponding getter and setter. For mostly static hierarchies, however, we recommend configuring these attributes via the `Preference` XML resource.\n\n### Generic attributes\n\n\n`title`\n\n: A `String` value that represents the title of the\n `Preference`.\n\n **Example:** `app:title=\"Title\"`\n\n\n`summary`\n\n: A `String` value that represents the `Preference`\n summary.\n\n **Example:** `app:summary=\"Summary\"`\n\n\n`icon`\n\n: A `Drawable` that represents the `Preference`\n icon.\n\n **Example:** `app:icon=\"@drawable/ic_camera\"`\n\n\n`key`\n\n: A `String` value that represents the key that is used to\n persist the value for the associated `Preference`. A key allows\n you to further customize the `Preference` during runtime.\n You should set a key for each `Preference` in your\n hierarchy.\n\n\n **Example:** `app:key=\"key\"`\n\n\n`enabled`\n\n: A boolean value that indicates whether users can interact with the\n `Preference`. When this value is `false`, the\n `Preference` appears grayed out, and users cannot interact with\n it. The default value is `true`.\n\n **Example:** `app:enabled=\"false\"`\n\n\n`selectable`\n\n: A boolean value that indicates whether users can interact with the\n `Preference`. The default value is `true`.\n\n **Example:** `app:selectable=\"false\"`\n\n\n`isPreferenceVisible`\n\n: A boolean value that indicates whether a `Preference` or\n `Preference` category is visible. This is equivalent to calling\n [`setVisible()`](/reference/androidx/preference/Preference#setVisible(boolean)).\n\n **Example:** `app:isPreferenceVisible=\"false\"`\n\n\n`defaultValue`\n\n: Represents the default value for a `Preference`. This value is\n set and persisted when no other persisted value for this\n `Preference` is found. The value type depends on the associated\n `Preference`.\n\n **Example:** `app:defaultValue=\"true\"`\n\n\n`dependency`\n\n: Represents the key of a `SwitchPreferenceCompat` that controls\n the state of this `Preference`. When the corresponding switch\n is turned off, this `Preference` is disabled and is unable to\n be modified.\n\n **Example:** `app:dependency=\"parent\"`\n\n### PreferenceCategory attributes\n\n\n`initialExpandedChildrenCount`\n\n: An integer value that enables expandable `Preference`\n behavior. This value represents the maximum number of children to show in\n the `PreferenceGroup`. Any extra children are collapsed and can\n be shown by tapping the expand button. By default, this value is\n `Integer.MAX_VALUE`, and all children are shown.\n\n **Warning:** Ensure that you set a key on the\n `PreferenceCategory` if using this attribute so that the state\n is correctly saved and restored when the configuration changes (such as\n when rotating the screen).\n\n\n **Example:** `app:initialExpandedChildrenCount=\"0\"`\n\n### ListPreference / MultiSelectListPreference attributes\n\n\n`entries`\n\n: An array of Strings that corresponds to the list entries to be displayed\n to the user. Each of these values correspond by index to the array of\n values that are internally persisted. For example, when a user selects the\n first list entry, the first element in the corresponding array of values\n is persisted.\n\n\n **Example:** `app:entries=\"@array/entries\"`\n\n **Warning:** Ensure the length of both arrays are the\n same, and the indexes of each array match the correct entry / value\n pair.\n\n\n`entryValues`\n\n: The array of entries to be persisted. Each of these values correspond by\n index to the array of list entries that are displayed to the user.\n\n\n **Example:** `app:entryValues=\"@array/values\"`"]]
