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"
ویژگی های PreferenceCategory
initialExpandedChildrenCount
یک مقدار صحیح که رفتار Preference قابل گسترش را فعال می کند. این مقدار نشان دهنده حداکثر تعداد فرزندان برای نمایش در PreferenceGroup است. بچه‌های اضافی جمع می‌شوند و با ضربه زدن روی دکمه بزرگ کردن نشان داده می‌شوند. به طور پیش فرض، این مقدار Integer.MAX_VALUE است و همه فرزندان نشان داده می شوند.
اخطار: در صورت استفاده از این ویژگی، مطمئن شوید که کلیدی را روی PreferenceCategory تنظیم کرده اید تا وضعیت به درستی ذخیره شده و هنگام تغییر پیکربندی (مانند چرخش صفحه) بازیابی شود.
آرایه‌ای از رشته‌ها که مربوط به ورودی‌های لیست برای نمایش به کاربر است. هر یک از این مقادیر با شاخصی با آرایه ای از مقادیری مطابقت دارند که در داخل وجود دارند. به عنوان مثال، زمانی که کاربر اولین ورودی فهرست را انتخاب می کند، اولین عنصر در آرایه مقادیر مربوطه باقی می ماند.
مثال:app:entries="@array/entries"
هشدار: مطمئن شوید که طول هر دو آرایه یکسان است و شاخص‌های هر آرایه با جفت ورودی/مقدار صحیح مطابقت دارند.
entryValues
آرایه ورودی هایی که باید ادامه داشته باشند. هر یک از این مقادیر با نمایه با آرایه ای از ورودی های لیست که به کاربر نمایش داده می شود مطابقت دارد.
مثال:app:entryValues="@array/values"
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-29 بهوقت ساعت هماهنگ جهانی."],[],[],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\"`"]]
