خيار مفضّل

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

تعريف التبعيات

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

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

رائع

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. يُرجى إخبارنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مشكلة جديدة. يمكنك إضافة تصويتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء عدد جديد

راجع مستندات أداة تتبُّع المشاكل للحصول على مزيد من المعلومات.

الإصدار 1.2

الإصدار 1.2.1

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

تم إصدار "androidx.preference:preference:1.2.1". يتضمّن الإصدار 1.2.1 هذه الالتزامات.

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

  • يعالج PreferenceHeaderFragmentCompat الآن زر الرجوع في النظام بشكل صحيح عند استخدامه داخل ComponentDialog أو عند استخدام مكتبات مثل @AndroidEntryPoint من Hilt التي تضم Context للجزء.
  • تعتمد التفضيل الآن على النشاط 1.5.1. (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 بدون أي تغييرات من الإعداد المفضّل 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)

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

  • تتّبع استدعاءات PreferencesFragmentCompat لـ 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).

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

  • يمكن الآن تنفيذ عمليات استدعاء التفضيل لـ OnتفضيلاتDisplayDialogCallback وOnتفضيلاتStartScreenCallback وOnتفضيلاتStartFragmentCallback في سياق غير نشاط. ويتم التحقق من 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)

التعديلات المتعلقة بالتبعية

  • تعتمد الإعدادات المفضّلة الآن على الجزء 1.2.4. (aosp/1277317)
  • تعتمد تبعية preference-ktx الآن على androidx.core:core-ktx:1.1.0 وandroidx.fragment:fragment-ktx:1.2.4، مع مراعاة العناصر التابعة لعنصر preference الرئيسي وضمان تعديل العناصر الرئيسية و-ktx للتبعيات الانتقالية من خلال ترقية preference-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 والفئات الأخرى التي تستخدم "أجزاء إطار العمل" نهائيًا، وعليك استخدام PreferenceFragmentCompat والفئات *المتوافقة الأخرى بدلاً من ذلك.
  • يمكنك الآن ضبط SummaryProvider على "الإعدادات المفضّلة" لضبط ملخّصها ديناميكيًا عندما يتم تعديل الإعدادات المفضّلة أو أصبحت مرئية للمستخدم. راجِع الدليل للحصول على مزيد من المعلومات.
  • تمت إضافة واجهة EditTextPreference.OnBindEditTextListener. يسمح ذلك بتخصيص EditText الذي يتم عرضه في مربّع الحوار المقابل بعد ربط مربّع الحوار. وهذا بديل مباشر لاستخدام سمات مثل android:inputType مباشرةً على EditTextPreference، وذلك غير متاح في مكتبة AndroidX. راجِع الدليل للحصول على مزيد من المعلومات.
  • تمت إضافة Preference.setCopyingEnabled() عند الضبط، سيؤدي الضغط مع الاستمرار على الخيار المفضّل إلى عرض قائمة سياقات تسمح بنسخ ملخّص الإعداد المفضّل.
  • تم تعديل تصميم SeekBarPreference ليتطابق مع مواصفات المواد. اطّلِع على سجلّ التغييرات المفصّل لمعرفة التغييرات الأخرى التي طرأت على SeekBarPreference.
  • تم إجراء عدد كبير من إصلاحات الأخطاء وتحديثات الأنماط وإصلاحات التوافق مع مستوى واجهة برمجة التطبيقات وتحسينات عامة في QOL.

الإصدار 1.1.0-rc01

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

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

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

  • إيقاف Preference#onInitializeAccessibilityNodeInfo
  • أنشأت هذه الطريقة خادمًا وكيلاً لمعلومات عقدة إمكانية الوصول لخيار مفضَّل معيّن، ولكن هذه هي الطبقة الخاطئة لهذا التخصيص. إذا كنت ترغب في ضبط معلومات إمكانية الوصول، يجب عليك بدلاً من ذلك تجاهل onبينSlideViewHolder، وإضافة معلومات إمكانية الوصول إلى العرض مباشرةً.

الإصدار 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.

  • لقد أوقفنا PreferencesFragment والفئات الأخرى التي تستخدم Fragment في إطار العمل نهائيًا - يجب عليك استخدام PreferencesFragmentCompat وفئات *compat الأخرى بدلاً من ذلك.
  • يمكنك الآن ضبط SummaryProvider على أحد الإعدادات المفضّلة لضبط ملخّصه ديناميكيًا عندما يتم تعديل تلك الإعدادات المفضّلة أو أصبحت مرئية للمستخدم. راجِع الدليل للحصول على مزيد من المعلومات.
  • تمت إضافة واجهة EditTextPreference.OnBindEditTextListener. يتيح هذا الإجراء تخصيص نص التعديل المعروض في مربع الحوار المقابل بعد ربط مربع الحوار. وهذا بديل مباشر لاستخدام سمات مثل android:inputType مباشرةً في EditTextPreferences، وهو غير متاح في مكتبة AndroidX. راجِع الدليل للحصول على مزيد من المعلومات.
  • تمت إضافة Preference.setCopyingEnabled() عند الضبط، سيؤدي الضغط مع الاستمرار على الخيار المفضّل إلى عرض قائمة سياقات تسمح بنسخ ملخّص الإعداد المفضّل.
  • تم تعديل نمط SeekBarPreferences ليطابق مواصفات المواد. راجِع سجلّ التغييرات المفصّل لمعرفة التغييرات الأخرى على SeekBarPreferences.
  • تم إجراء عدد كبير من إصلاحات الأخطاء وتحديثات الأنماط وإصلاحات التوافق مع مستوى واجهة برمجة التطبيقات وتحسينات عامة في QOL.

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

  • لإزالة getOnSelectEditTextListener من واجهة برمجة تطبيقات عامة، يجب عليك فقط استخدام setOnAllowedEditTextListener عند التفاعل مع واجهة برمجة التطبيقات هذه.

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

الإصدار 1.1.0-alpha05

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

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

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

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

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

  • تم إصلاح الانحدار حيث يكون لدرجة التفضيلات والتفضيلات الأخرى غير القابلة للتحديد تأثير مضاعف عند تحديده
  • تم إصلاح مشكلة إمكانية الوصول التي كانت يتعذّر فيها على TalkBack رؤية DropDownPreferences كإمكانية قابلة للنقر
  • تم إصلاح بعض مشاكل تنسيق RTL
  • تم تحديث بعض التعليقات التوضيحية التي يمكن إلغاء قيمها في PreferencesFragmentCompat لتتوافق مع Fragment

الإصدار 1.1.0-alpha04

13 آذار (مارس) 2019

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

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

آخر الأخبار عن "SeekBarPreference"

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

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

  • لإضافة التعليقات التوضيحية التي لا تتضمّن قيمة فارغة إلى 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 مع التغييرات التالية.

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

  • تم إصلاح المشكلة المتمثلة في عدم ظهور أحيانًا نافذة منبثقة للنسخ/اللصق في مربع حوار EditTextPreferences
  • تم إصلاح مشكلة عدم تسجيل المحوِّل الأساسي بشكلٍ صحيح، والتي تتسبب في تسرُّب الذاكرة في ظل ظروف معيّنة (b/121006469).
  • تم إصلاح بعض الأعطال المتعلقة بمربعات الحوار التي حدثت أثناء تغيير الإعداد (b/122167543)
  • ميزة ملخّص الخدمة الثابتة لا تعمل مع ميزة MultiSelectListPreferences (b/123022772)

الإصدار 1.1.0-alpha02

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

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

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

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

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

  • تم تطبيق PreferencesTheme الآن على مظهر النشاط يعني هذا أنه عند إنشاء التفضيلات من الرمز، لن تحتاج بعد ذلك إلى استخدام السياق من PreferenceManager#getContext()، بل يمكنك فقط استخدام سياق الجزء/النشاط.

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

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

الإصدار 1.1.0-alpha01

5 تشرين الثاني (نوفمبر) 2018

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

  • يمكنك الآن ضبط مُقدِّم ملخّص على "تفضيل" لضبط ملخّصه ديناميكيًا عندما يتم تعديل تفضيله أو أصبح مرئيًا للمستخدم.
  • تمت إضافة عمليات تنفيذ summaryProvider التلقائية لـ ListPreferences وEditTextPreferences، والتي عند ضبطها ستؤدي إلى تعديل ملخّص القيمة المفضّلة تلقائيًا لإظهار قيمتها المحفوظة أو "لم يتم الضبط" إذا لم يتم حفظ أيّ قيمة. يمكن ضبطها باستخدام app:useSimpleSummaryProvider=”true”.
  • تمت إضافة PreferencesGroup#removePreferencesRecursively، وهو العثور على الإعدادات المفضّلة وإزالتها بشكل متكرّر من المجموعة، أو مجموعة متداخلة في ترتيب أدنى في التسلسل الهرمي،

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

  • لقد تم إهمال PreferencesFragment وغير ذلك من الفئات التي تستخدم Fragment في إطار العمل - يجب عليك استخدام PreferencesFragmentCompat وغيرها من الفئات المتوافقة بدلاً من ذلك.

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

  • رمز تم إصلاحه لا يعمل SpaceReserve بشكل صحيح مع التفضيلات.
  • تم إصلاح التفضيلات التي لا تستخدم colorAccent للون عنوانها الأقل من API 21.
  • تم إصلاح بعض تناقضات تنسيق SeekBarPreferences أسفل واجهة برمجة التطبيقات 21.