خيار مفضّل

يمكنك إنشاء شاشات إعدادات تفاعلية بدون الحاجة إلى التفاعل مع مساحة التخزين على الجهاز أو إدارة واجهة المستخدم.
آخر الأخبار الإصدار الثابت إصدار محتمل الإصدار التجريبي الإصدار الأولي
‏26 تموز (يوليو) 2023 1.2.1 - - -

تحديد الاعتماديات

لإضافة اعتمادية على Preference، يجب تضمين مستودع Google Maven في مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.

أضِف الاعتماديات الخاصة بالعناصر التي تحتاج إليها في ملف build.gradle لتطبيقك أو وحدتك:

Groovy

dependencies {
    def preference_version = "1.2.1"

    // Java language implementation
    implementation "androidx.preference:preference:$preference_version"
    // Kotlin
    implementation "androidx.preference:preference-ktx:$preference_version"
}

Kotlin

dependencies {
    val preference_version = "1.2.1"

    // Java language implementation
    implementation("androidx.preference:preference:$preference_version")
    // Kotlin
    implementation("androidx.preference:preference-ktx:$preference_version")
}

لمزيد من المعلومات حول الاعتماديات، يُرجى الاطّلاع على إضافة اعتماديات الإصدار.

الملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إعلامنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مشكلة جديدة. يمكنك إضافة صوتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء مشكلة جديدة

يُرجى الاطّلاع على مستندات Issue Tracker للحصول على مزيد من المعلومات.

الإصدار 1.2

الإصدار 1.2.1

‏26 تموز (يوليو) 2023

تم طرح androidx.preference:preference:1.2.1. يتضمّن الإصدار 1.2.1 هذه التعديلات.

إصلاح الأخطاء

  • يتعامل PreferenceHeaderFragmentCompat الآن بشكل صحيح مع زر الرجوع في النظام عند استخدامه داخل ComponentDialog أو عند استخدام مكتبات مثل @AndroidEntryPoint في Hilt التي تغلف Context في Fragment.
  • يعتمد الإعداد المفضّل الآن على الإصدار 1.5.1 من Activity. (Ie5d22)
  • تعمل PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment الآن على نشر header.extras كوسيطات Fragment.

الإصدار 1.2.0

‫26 يناير 2022

تم طرح androidx.preference:preference:1.2.0 وandroidx.preference:preference-ktx:1.2.0. يتضمّن الإصدار 1.2.0 هذه التعديلات.

التغييرات المهمة منذ الإصدار 1.1.0

  • تمت إضافة PreferenceHeaderFragmentCompat لتفضيل اللوحة المزدوجة التي تتكيّف تلقائيًا استنادًا إلى حجم الجهاز المستخدَم، ما يجعلها مناسبة للاستخدام على الهواتف والهواتف القابلة للطي والأجهزة اللوحية. يتم توفير لوحة العنوان من خلال إلغاء طريقة onCreatePreferenceHeader() في PreferenceHeaderFragmentCompat. سيؤدي أي <Preference> في العنوان PreferenceFragmentCompat الذي يستخدم app:fragment إلى ظهور هذا الجزء في لوحة التفاصيل الثانية. يمكن تخصيص جزء التفاصيل الأوّلي الذي يجب عرضه قبل اختيار أي إعداد يدويًا من خلال تجاوز onCreateInitialDetailFragment(). يعرض التنفيذ التلقائي الإعداد المفضّل الأول الذي تم تحديد جزء فيه.
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • تمت إضافة تعليقات توضيحية بشأن إمكانية قبول القيمة الخالية إلى العديد من واجهات برمجة التطبيقات التي لم تحدّد @NonNull أو @Nullable سابقًا. هذا تغيير محتمل يؤدي إلى إيقاف مصدر Kotlin إذا لم تتطابق إمكانية القيم الفارغة التي اخترتها في رمز Kotlin مع إمكانية القيم الفارغة المحدّدة الآن.

  • يبحث PreferenceFragmentCompat الآن عن عمليات تنفيذ الواجهات OnPreferenceStartFragmentCallback وOnNavigateToScreenListener وOnDisplayPreferenceDialogListener في الأجزاء الرئيسية قبل البحث لمعرفة ما إذا كان السياق أو النشاط المضيف ينفّذان هذه الواجهات.

الإصدار 1.2.0-rc01

15 كانون الأول (ديسمبر) 2021

تم إصدار androidx.preference:preference:1.2.0-rc01 وandroidx.preference:preference-ktx:1.2.0-rc01 بدون أي تغييرات منذ 1.2.0-beta01. يتضمّن الإصدار 1.2.0-rc01 هذه التعديلات.

الإصدار 1.2.0-beta01

17 تشرين الثاني (نوفمبر) 2021

تم إصدار androidx.preference:preference:1.2.0-beta01 وandroidx.preference:preference-ktx:1.2.0-beta01 بدون أي تغييرات منذ الإصدار Preference 1.2.0-alpha02. يتضمّن الإصدار 1.2.0-beta01 هذه التعديلات.

الإصدار 1.2.0-alpha02

‫3 نوفمبر 2021

تم طرح androidx.preference:preference:1.2.0-alpha02 وandroidx.preference:preference-ktx:1.2.0-alpha02. يتضمّن الإصدار 1.2.0-alpha02 هذه التعديلات.

تغييرات واجهة برمجة التطبيقات

  • تمت إضافة تعليقات توضيحية بشأن إمكانية قبول القيمة الخالية إلى العديد من واجهات برمجة التطبيقات التي لم تحدّد @NonNull أو @Nullable سابقًا. (I04252، Ie2cc0)
  • تمت إزالة واجهة برمجة التطبيقات openPreference() من PreferenceHeaderFragmentCompat، ويتم طلب هذه الطريقة تلقائيًا، لذا لا يجب طلبها يدويًا. (Ia6989)

التغييرات في السلوك

  • تتّبع عمليات رد الاتصال في الفئة PreferenceFragmentCompat لكلّ من OnNavigateToScreenListener وOnDisplayPreferenceDialogListener النمط نفسه الذي تتّبعه OnPreferenceTreeClickListener، كما أنّها تبحث في التسلسل الهرمي للجزء الرئيسي عن أدوات معالجة صالحة قبل البحث لمعرفة ما إذا كان السياق أو النشاط المضيفان ينفّذان هذه الواجهات. (I7ae6c)

الإصدار ‎1.2.0-alpha01

‫27 أكتوبر 2021

تم طرح androidx.preference:preference:1.2.0-alpha01 وandroidx.preference:preference-ktx:1.2.0-alpha01. يتضمّن الإصدار 1.2.0-alpha01 هذه التعديلات.

الميزات الجديدة

  • تمت إضافة PreferenceHeaderFragmentCompat لإعدادات اللوحة المزدوجة (I9a2d8)

التغييرات في السلوك

  • يمكن الآن تنفيذ عمليات معاودة الاتصال المفضّلة لكلّ من OnPreferenceDisplayDialogCallback وOnPreferenceStartScreenCallback وOnPreferenceStartFragmentCallback في سياق غير نشاط. يتم التحقّق من getContext() لمعرفة ما إذا كان ينفّذ عمليات معاودة الاتصال هذه قبل التحقّق من getActivity(). وإذا كان getContext() يعرض نشاطًا (الحالة الشائعة)، لن يحدث أي تغيير في السلوك.

  • يبحث طلب PreferenceFragmentCompat إلى onPreferenceTreeClick الآن عن عمليات تنفيذ واجهة OnPreferenceStartFragmentCallback في الأجزاء الرئيسية قبل النظر في عملية تنفيذ النشاط. (c64eed)

الإصدار 1.1

الإصدار 1.1.1

نيسان (أبريل) 2020

تم طرح androidx.preference:preference:1.1.1 وandroidx.preference:preference-ktx:1.1.1. يتضمّن الإصدار 1.1.1 هذه التعديلات.

إصلاح الأخطاء

  • لن يعرض PreferenceDialogFragmentCompat بعد الآن الخطأ IllegalStateException عند إنشاء FragmentContainerView من ملف XML. (b/150051716)

تحديثات الاعتماديات

  • يعتمد الإعداد المفضّل الآن على Fragment 1.2.4. (aosp/1277317)
  • تعتمد التبعية preference-ktx الآن على androidx.core:core-ktx:1.1.0 وandroidx.fragment:fragment-ktx:1.2.4، ما يعكس تبعيات العنصر preference الرئيسي ويضمن أنّ ترقية preference-ktx تؤدي إلى تعديل كل من العنصر الرئيسي والعنصر -ktx للتبعيات المتعدية. (aosp/1277319)

الإصدار 1.1.0

‫5 أيلول (سبتمبر) 2019

تم طرح androidx.preference:preference:1.1.0 وandroidx.preference:preference-ktx:1.1.0. يمكنك الاطّلاع على التعديلات في هذا الإصدار هنا.

إذا كان هذا هو الإصدار الأول من 1.1.* الذي ستحدّث إليه، إليك قائمة موجزة بالتغييرات الكبيرة التي تم إجراؤها منذ آخر إصدار ثابت، وهو 1.0.0. قد تجد أيضًا دليل الإعدادات ونموذج تطبيق ومؤتمر Android Dev Summit مفيدة.

التغييرات المهمة منذ الإصدار 1.0.0

  • تم إيقاف PreferenceFragment والفئات الأخرى التي تستخدم إطارات عمل Fragments نهائيًا، ويجب استخدام PreferenceFragmentCompat والفئات الأخرى المتوافقة بدلاً من ذلك.
  • يمكنك الآن ضبط SummaryProvider على "الإعداد المفضّل" لضبط ملخّصه بشكلٍ ديناميكي كلّما تم تعديل "الإعداد المفضّل" أو أصبح مرئيًا للمستخدم. اطّلِع على الدليل لمزيد من المعلومات.
  • تمّت إضافة واجهة EditTextPreference.OnBindEditTextListener. يتيح ذلك تخصيص EditText المعروض في مربّع الحوار ذي الصلة بعد ربط مربّع الحوار. هذا بديل مباشر لاستخدام سمات مثل android:inputType مباشرةً في EditTextPreference، وهو أمر غير متاح في مكتبة AndroidX. اطّلِع على الدليل لمزيد من المعلومات.
  • تمت إضافة Preference.setCopyingEnabled() عند ضبط هذا الخيار، سيؤدي الضغط مع الاستمرار على "الخيار المفضّل" إلى عرض قائمة سياقية تتيح نسخ ملخّص "الخيار المفضّل".
  • تم تعديل تصميم SeekBarPreference ليتوافق مع مواصفات Material. يمكنك الاطّلاع على سجلّ التغيير المفصّل لمعرفة التغييرات الأخرى التي تم إجراؤها على SeekBarPreference.
  • تم إجراء عدد كبير من عمليات إصلاح الأخطاء وتعديلات على الأنماط وإصلاحات للتوافق مع مستوى واجهة برمجة التطبيقات وتحسينات عامة على جودة الحياة.

الإصدار ‎1.1.0-rc01

2 تموز (يوليو) 2019

تم طرح androidx.preference:preference:1.1.0-rc01 وandroidx.preference:preference-ktx:1.1.0-rc01. يمكنك الاطّلاع على التعديلات في هذا الإصدار هنا.

تغييرات واجهة برمجة التطبيقات

  • إيقاف Preference#onInitializeAccessibilityNodeInfo
  • كانت هذه الطريقة تعمل كخادم وكيل لمعلومات عقدة إمكانية الوصول إلى إعدادات "الخيار المفضّل" معيّنة، ولكنّ هذه الطبقة غير مناسبة لهذا التخصيص. إذا أردت تعديل معلومات تسهيل الاستخدام، عليك بدلاً من ذلك إلغاء طريقة عمل onBindViewHolder وإضافة معلومات تسهيل الاستخدام إلى طريقة العرض مباشرةً.

الإصدار 1.1.0-beta01

‫5 يونيو 2019

تم طرح androidx.preference:preference:1.1.0-beta01 وandroidx.preference:preference-ktx:1.1.0-beta01. يمكنك الاطّلاع على التعديلات في هذا الإصدار هنا.

التغييرات المهمة منذ الإصدار 1.1.0

إذا كان هذا هو الإصدار الأول من السلسلة 1.1.* الذي ستثبّته، إليك قائمة موجزة بالتغييرات الكبيرة التي تم إجراؤها منذ آخر إصدار ثابت، وهو 1.1.0. قد تجد أيضًا دليل الإعدادات ونموذج تطبيق ومؤتمر Android Dev Summit مفيدة.

  • تم إيقاف PreferenceFragment والفئات الأخرى التي تستخدم حِزم Fragment نهائيًا، ويجب استخدام PreferenceFragmentCompat والفئات الأخرى المتوافقة بدلاً من ذلك.
  • يمكنك الآن ضبط SummaryProvider على Preference لضبط الملخّص ديناميكيًا كلما تم تعديل Preference أو أصبح مرئيًا للمستخدم. اطّلِع على الدليل لمزيد من المعلومات.
  • تمّت إضافة واجهة EditTextPreference.OnBindEditTextListener. يتيح ذلك تخصيص عنصر EditText المعروض في مربّع الحوار ذي الصلة بعد ربط مربّع الحوار. هذا هو البديل المباشر لاستخدام سمات مثل android:inputType مباشرةً في EditTextPreference، وهو ما لا يتوافق مع مكتبة AndroidX. اطّلِع على الدليل لمزيد من المعلومات.
  • تمت إضافة Preference.setCopyingEnabled() عند ضبط هذا الخيار، سيؤدي الضغط مع الاستمرار على "الخيار المفضّل" إلى عرض قائمة سياقية تتيح نسخ ملخّص "الخيار المفضّل".
  • تم تعديل تصميم SeekBarPreference ليتوافق مع مواصفات Material. يمكنك الاطّلاع على سجلّ التغيير المفصّل لمعرفة التغييرات الأخرى التي تم إجراؤها على SeekBarPreference.
  • تم إجراء عدد كبير من عمليات إصلاح الأخطاء وتعديلات على الأنماط وإصلاحات للتوافق مع مستوى واجهة برمجة التطبيقات وتحسينات عامة على جودة الحياة.

تغييرات واجهة برمجة التطبيقات منذ الإصدار 1.1.0-alpha05

  • تتم إزالة getOnBindEditTextListener من واجهة برمجة التطبيقات العامة، ولن تحتاج إلى استخدام setOnBindEditTextListener إلا عند التفاعل مع واجهة برمجة التطبيقات هذه.

يُرجى الإبلاغ عن الأخطاء هنا في حال مواجهة أي مشاكل أو إذا كانت لديك اقتراحات بشأن ميزات جديدة.

الإصدار ‎1.1.0-alpha05

7 أيار (مايو) 2019

تم طرح androidx.preference:preference:1.1.0-alpha05 وandroidx.preference:preference-ktx:1.1.0-alpha05. يمكنك الاطّلاع على التعديلات في هذا الإصدار هنا.

الميزات الجديدة

  • تم تعديل تصميم "الإعدادات المفضّلة" غير القابلة للاختيار، وأصبح العنوان والملخّص يتشاركان اللون نفسه لتوضيح أنّه لا يمكن التفاعل معهما، وأنّهما يُستخدمان فقط لعرض المعلومات.
  • ملاحظة: ننصحك بإضافة enableCopying="true" إلى الإعدادات المفضّلة غير القابلة للاختيار، حتى تتمكّن من الضغط مع الاستمرار لنسخ الملخّص.

إصلاح الأخطاء

  • تم إصلاح خطأ في الإصدار السابق حيث كان يظهر تأثير تموّج عند اختيار PreferenceCategory والإعدادات المفضّلة الأخرى غير القابلة للاختيار
  • تم إصلاح مشكلة متعلّقة بإمكانية الوصول، وهي أنّ TalkBack لم يرَ DropDownPreference على أنّه قابل للنقر
  • تم إصلاح بعض المشاكل المتعلّقة بالتنسيق من اليمين إلى اليسار
  • تم تعديل بعض التعليقات التوضيحية التي تقبل القيم الخالية في PreferenceFragmentCompat لتتوافق مع Fragment

الإصدار ‎1.1.0-alpha04

‫13 مارس 2019

تم طرح androidx.preference:preference:1.1.0-alpha04 وandroidx.preference:preference-ktx:1.1.0-alpha04. يمكنك الاطّلاع على القائمة الكاملة للتعديلات في هذا الإصدار هنا.

الميزات الجديدة

SeekBarPreference التحديث الجديد!

  • تم تعديل التصميم ليتوافق مع مواصفات Material
    • يتم الآن إخفاء تصنيف القيمة تلقائيًا، ولكن يمكن عرضه باستخدام app:showSeekBarValue="true" أو setShowSeekBarValue(true). لا يشكّل هذا التصنيف جزءًا من مواصفات Material، ولكنّنا ندرك أنّه يُستخدَم بشكل كبير، لذا سنواصل توفيره، على الرغم من أنّنا لا ننصح باستخدامه.
    • يتم الآن تعديل تصنيف القيمة أثناء سحب شريط SeekBar، بدلاً من تعديله عند تحريره. يُرجى العِلم أنّ هذا لا يعني تعديل القيمة داخليًا، راجِع ما يلي للاطّلاع على واجهة برمجة تطبيقات جديدة تتيح هذه الوظيفة.
    • ملاحظة: على الرغم من أنّ هذا الإجراء متاح، عليك تجنُّب ضبط ملخّص على SeekBarPreference لأنّه غير مخصّص لهذا الغرض وليس جزءًا من مواصفات Material.
  • تضيف هذه السمة إمكانية إجراء تعديلات مستمرة، ما يسمح لـ SeekBar بتعديل القيمة المحفوظة أثناء سحب SeekBar. يمكن تفعيل ذلك من XML أو برمجيًا باستخدام app:updatesContinuously="true" أو setUpdatesContinuously(true). سيتم تشغيل هذا الإجراء كلما تغيّر موضع شريط التمرير على الشاشة.

تغييرات واجهة برمجة التطبيقات

  • إضافة تعليقات توضيحية بشأن إمكانية قبول القيم الفارغة إلى findPreference()

إصلاح الأخطاء

  • تم إصلاح الخلل الذي لم تتم فيه إزالة أدوات معالجة قائمة السياق بشكل صحيح في حال عدم تفعيل خيار النسخ

الإصدار ‎1.1.0-alpha03

‫7 فبراير 2019

androidx.preference:preference 1.1.0-alpha03

تم إصدار androidx.preference:preference 1.1.0-alpha03 وandroidx.preference:preference-ktx 1.1.0-alpha03 مع التغييرات التالية.

إصلاح الأخطاء

  • تم إصلاح المشكلة المتمثّلة في عدم ظهور النافذة المنبثقة للنسخ/اللصق أحيانًا في مربّع حوار EditTextPreference
  • تم إصلاح مشكلة عدم إلغاء تسجيل المحوّل الأساسي بشكلٍ صحيح، ما يؤدي إلى حدوث تسرّب للذاكرة في ظروف معيّنة (b/121006469)
  • تم إصلاح بعض الأعطال المرتبطة بمربّعات الحوار والتي حدثت أثناء تغيير الإعداد (b/122167543)
  • عدم عمل Fixed SummaryProvider مع MultiSelectListPreference (b/123022772)

الإصدار ‎1.1.0-alpha02

‫17 كانون الأول (ديسمبر) 2018

يُرجى أيضًا الاطّلاع على دليل الإعدادات وتطبيق العينة اللذين تم تعديلهما مؤخرًا.

الميزات الجديدة

  • تمت إضافة واجهة EditTextPreference.OnBindEditTextListener تتيح هذه الواجهة تخصيص عنصر EditText المعروض في مربّع الحوار ذي الصلة بعد ربط مربّع الحوار. على سبيل المثال، ضبط نوع / طول إدخال مخصّص أو إضافة TextWatcher.

  • تمت إضافة Preference.setCopyingEnabled() عند ضبط هذا الخيار، سيؤدي الضغط مع الاستمرار على "الخيار المفضّل" إلى عرض قائمة سياقية تتيح نسخ ملخّص "الخيار المفضّل". يمكن استخدام ذلك للسماح بنسخ المعلومات الثابتة، مثل أرقام التعريف الخاصة بالمستخدمين أو معلومات إصدار التطبيق.

  • يتم الآن تطبيق السمة preferenceTheme على سمة النشاط وهذا يعني أنّه عند إنشاء Preference من الرمز، لن تحتاج بعد الآن إلى استخدام السياق من PreferenceManager#getContext()، بل يمكنك استخدام سياق Fragment/Activity فقط.

تغييرات واجهة برمجة التطبيقات

  • تمت إعادة تصميم findPreference() لعرض <T extends Preference> وهذا يعني أنّه ليس عليك تحويل "الإعدادات المفضّلة" بشكل صريح عند استخدام findPreference(). على سبيل المثال، EditTextPreference preference = findPreference(“edit_text”) أصبح الآن رمزًا صالحًا.

الإصدار ‎1.1.0-alpha01

‫5 نوفمبر 2018

الميزات الجديدة

  • يمكنك الآن ضبط SummaryProvider على Preference لضبط ملخّصه ديناميكيًا كلما تم تعديل Preference أو أصبح مرئيًا للمستخدم.
  • تمت إضافة عمليات تنفيذ تلقائية لـ SummaryProvider لكل من ListPreference وEditTextPreference، وعند ضبطها، سيتم تعديل ملخّص Preference تلقائيًا ليعكس القيمة المحفوظة أو "لم يتم الضبط" إذا لم يتم حفظ أي قيمة. يمكن ضبطها باستخدام app:useSimpleSummaryProvider=”true”
  • تمت إضافة PreferenceGroup#removePreferenceRecursively التي تعثر بشكل متكرر على عنصر Preference وتزيله من المجموعة أو من مجموعة مدمجة في مستوى أدنى من التسلسل الهرمي.

تغييرات واجهة برمجة التطبيقات

  • تم إيقاف استخدام PreferenceFragment والفئات الأخرى التي تستخدم حِزم Fragment في إطار العمل، لذا عليك استخدام PreferenceFragmentCompat والفئات الأخرى المتوافقة بدلاً من ذلك.

إصلاح الأخطاء

  • تم إصلاح مشكلة عدم عمل iconSpaceReserved بشكل صحيح مع PreferenceCategories.
  • تم إصلاح مشكلة عدم استخدام colorAccent في PreferenceCategories للون العنوان على الإصدارات الأقدم من المستوى 21 لواجهة برمجة التطبيقات.
  • تم إصلاح بعض حالات عدم الاتساق في تخطيط SeekBarPreference في الإصدارات الأقدم من المستوى 21 لواجهة برمجة التطبيقات.