ترجیح

بدون نیاز به تعامل با حافظه دستگاه یا مدیریت رابط کاربری، صفحات تنظیمات تعاملی بسازید.
آخرین به‌روزرسانی انتشار پایدار کاندیدای انتشار انتشار بتا انتشار آلفا
۲۶ ژوئیه ۲۰۲۳ ۱.۲.۱ - - -

اعلام وابستگی‌ها

برای افزودن وابستگی به Preference، باید مخزن Google Maven را به پروژه خود اضافه کنید. برای اطلاعات بیشتر، مخزن Maven گوگل را مطالعه کنید.

وابستگی‌های مربوط به مصنوعات مورد نیاز خود را در فایل 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"
}

کاتلین 

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 کمک می‌کند. اگر مشکلات جدیدی کشف کردید یا ایده‌هایی برای بهبود این کتابخانه دارید، به ما اطلاع دهید. لطفاً قبل از ایجاد یک کتابخانه جدید، نگاهی به مشکلات موجود در این کتابخانه بیندازید. می‌توانید با کلیک بر روی دکمه ستاره، رأی خود را به یک مشکل موجود اضافه کنید.

ایجاد یک مسئله جدید

برای اطلاعات بیشتر به مستندات ردیاب مشکل مراجعه کنید.

نسخه ۱.۲

نسخه ۱.۲.۱

۲۶ ژوئیه ۲۰۲۳

androidx.preference:preference:1.2.1 منتشر شد. نسخه ۱.۲.۱ شامل این کامیت‌ها است.

رفع اشکالات

  • PreferenceHeaderFragmentCompat اکنون دکمه بازگشت سیستم را هنگام استفاده در یک ComponentDialog یا هنگام استفاده از کتابخانه‌هایی مانند @AndroidEntryPoint از Hilt که Context از Fragment را پوشش می‌دهند، به درستی مدیریت می‌کند.
  • اولویت اکنون به فعالیت ۱.۵.۱ بستگی دارد. ( Ie5d22 )
  • PreferenceHeaderFragmentCompat.onCreateInitialDetailFragment اکنون header.extras به عنوان آرگومان‌های Fragment منتشر می‌کند.

نسخه ۱.۲.۰

۲۶ ژانویه ۲۰۲۲

androidx.preference:preference:1.2.0 و androidx.preference:preference-ktx:1.2.0 منتشر شدند. نسخه ۱.۲.۰ شامل این کامیت‌ها است.

تغییرات مهم از زمان ۱.۱.۰

  • PreferenceHeaderFragmentCompat برای تنظیمات دو قسمتی اضافه شده است که به طور خودکار بر اساس اندازه دستگاه مورد استفاده سازگار می‌شود و آن را برای استفاده در تلفن‌ها، تبلت‌ها و دستگاه‌های تاشو مناسب می‌کند. قسمت سربرگ با بازنویسی متد onCreatePreferenceHeader() در PreferenceHeaderFragmentCompat ارائه می‌شود. هر <Preference> در سربرگ PreferenceFragmentCompat که app:fragment استفاده کند، باعث می‌شود که آن قطعه در قسمت جزئیات دوم ظاهر شود. قطعه جزئیات اولیه که باید قبل از انتخاب دستی هر ترجیحی نمایش داده شود، می‌تواند با بازنویسی onCreateInitialDetailFragment() سفارشی شود. پیاده‌سازی پیش‌فرض، اولین ترجیحی را که یک قطعه روی آن تعریف شده است، برمی‌گرداند. 
class TwoPanePreference : PreferenceHeaderFragmentCompat() {
    override fun onCreatePreferenceHeader(): PreferenceFragmentCompat {
        return PreferenceHeader()
    }
}

  • حاشیه‌نویسی‌های nullability به بسیاری از APIهایی که قبلاً @NonNull یا @Nullable را مشخص نمی‌کردند، اضافه شد. اگر nullability که در کد کاتلین خود انتخاب کرده‌اید با nullability که اکنون تعریف شده است مطابقت نداشته باشد، این یک تغییر بالقوه مخرب در کد کاتلین است.

  • PreferenceFragmentCompat اکنون قبل از بررسی اینکه آیا Context یا Activity میزبان، این رابط‌ها را پیاده‌سازی می‌کند یا خیر، به دنبال پیاده‌سازی رابط‌های OnPreferenceStartFragmentCallback ، OnNavigateToScreenListener و OnDisplayPreferenceDialogListener در قطعات والد می‌گردد.

نسخه ۱.۲.۰-rc01

۱۵ دسامبر ۲۰۲۱

androidx.preference:preference:1.2.0-rc01 و androidx.preference:preference-ktx:1.2.0-rc01 بدون هیچ تغییری از زمان 1.2.0-beta01 منتشر شده‌اند. نسخه ۱.۲.۰-rc01 شامل این کامیت‌ها است.

نسخه ۱.۲.۰-بتا۰۱

۱۷ نوامبر ۲۰۲۱

androidx.preference:preference:1.2.0-beta01 و androidx.preference:preference-ktx:1.2.0-beta01 بدون هیچ تغییری نسبت به Preference 1.2.0-alpha02 منتشر شده‌اند. نسخه 1.2.0-beta01 شامل این کامیت‌ها است.

نسخه ۱.۲.۰-آلفا۰۲

۳ نوامبر ۲۰۲۱

androidx.preference:preference:1.2.0-alpha02 و androidx.preference:preference-ktx:1.2.0-alpha02 منتشر شدند. نسخه 1.2.0-alpha02 شامل این کامیت‌ها است.

تغییرات API

  • حاشیه‌نویسی‌های مربوط به قابلیت تهی‌سازی به بسیاری از APIهایی که قبلاً @NonNull یا @Nullable را مشخص نمی‌کردند، اضافه شد. ( I04252 ، Ie2cc0 )
  • API openPreference() از PreferenceHeaderFragmentCompat حذف شد - این متد برای شما فراخوانی می‌شود و نباید به صورت دستی فراخوانی شود. ( Ia6989 )

تغییرات رفتاری

  • فراخوانی‌های PreferenceFragmentCompat برای OnNavigateToScreenListener و OnDisplayPreferenceDialogListener اکنون از الگوی مشابه OnPreferenceTreeClickListener پیروی می‌کنند و قبل از بررسی اینکه آیا Context یا Activity میزبان این رابط‌ها را پیاده‌سازی می‌کند یا خیر، سلسله مراتب قطعه والد را برای شنوندگان معتبر جستجو می‌کنند. ( I7ae6c )

نسخه ۱.۲.۰-آلفا۰۱

۲۷ اکتبر ۲۰۲۱

androidx.preference:preference:1.2.0-alpha01 و androidx.preference:preference-ktx:1.2.0-alpha01 منتشر شدند. نسخه 1.2.0-alpha01 شامل این کامیت‌ها است.

ویژگی‌های جدید

  • PreferenceHeaderFragmentCompat برای تنظیمات دو قسمتی اضافه شد ( I9a2d8 )

تغییرات رفتاری

  • فراخوانی‌های ترجیحی برای OnPreferenceDisplayDialogCallback، OnPreferenceStartScreenCallback و OnPreferenceStartFragmentCallback اکنون می‌توانند در یک Context غیر Activity پیاده‌سازی شوند. getContext() بررسی می‌شود تا ببیند آیا این فراخوانی‌های برگشتی را قبل از بررسی getActivity() پیاده‌سازی می‌کند یا خیر. اگر getContext() یک Activity را برگرداند (مورد رایج)، هیچ تغییر رفتاری وجود ندارد.

  • فراخوانی متد onPreferenceTreeClick توسط PreferenceFragmentCompat ، قبل از بررسی پیاده‌سازی Activity، به دنبال پیاده‌سازی‌های رابط OnPreferenceStartFragmentCallback روی قطعات والد می‌گردد. ( c64eed )

نسخه ۱.۱

نسخه ۱.۱.۱

۱۵ آوریل ۲۰۲۰

androidx.preference:preference:1.1.1 و androidx.preference:preference-ktx:1.1.1 منتشر شدند. نسخه ۱.۱.۱ شامل این کامیت‌ها است.

رفع اشکالات

  • PreferenceDialogFragmentCompat دیگر هنگام inflate کردن یک FragmentContainerView از xml، IllegalStateException را صادر نمی‌کند. ( b/150051716 )

به‌روزرسانی‌های وابستگی

  • اولویت اکنون به قطعه 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 )

نسخه ۱.۱.۰

۵ سپتامبر ۲۰۱۹

androidx.preference:preference:1.1.0 و androidx.preference:preference-ktx:1.1.0 منتشر شدند. کامیت‌های موجود در این نسخه را می‌توانید اینجا پیدا کنید.

اگر این اولین 1.1.* است که به آن به‌روزرسانی می‌کنید، در اینجا فهرست مختصری از تغییرات بزرگ‌تر از زمان آخرین نسخه پایدار، 1.0.0 ، آورده شده است. همچنین ممکن است راهنمای تنظیمات ، نمونه برنامه و سخنرانی اجلاس توسعه‌دهندگان اندروید برای شما مفید باشد.

تغییرات مهم از زمان ۱.۰.۰

  • PreferenceFragment و سایر کلاس‌هایی که از Fragments چارچوب استفاده می‌کنند، منسوخ شده‌اند؛ شما باید به جای آن PreferenceFragmentCompat و سایر کلاس‌های *compat استفاده کنید.
  • اکنون می‌توانید یک SummaryProvider روی یک Preference تنظیم کنید تا خلاصه آن را به صورت پویا پیکربندی کند، هر زمان که Preference به‌روزرسانی شود یا برای کاربر قابل مشاهده باشد. برای اطلاعات بیشتر به راهنما مراجعه کنید.
  • رابط EditTextPreference.OnBindEditTextListener اضافه شد. این امکان سفارشی‌سازی EditText نمایش داده شده در کادر محاوره‌ای مربوطه را پس از اتصال کادر محاوره‌ای فراهم می‌کند. این یک جایگزین مستقیم برای استفاده مستقیم از ویژگی‌هایی مانند android:inputType در EditTextPreference است که در کتابخانه AndroidX پشتیبانی نمی‌شود. برای اطلاعات بیشتر به راهنما مراجعه کنید.
  • اضافه شدن Preference.setCopyingEnabled() ‎ هنگام تنظیم، با فشار دادن طولانی روی Preference، منوی زمینه‌ای نمایش داده می‌شود که امکان کپی کردن خلاصه Preference را فراهم می‌کند.
  • استایل SeekBarPreference به‌روزرسانی شد تا با مشخصات متریال مطابقت داشته باشد. برای مشاهده‌ی سایر تغییرات SeekBarPreference ، به جزئیات تغییرات مراجعه کنید.
  • مقدار زیادی رفع اشکال، به‌روزرسانی‌های سبک، رفع مشکلات سازگاری سطح API و بهبودهای کلی کیفیت زندگی.

نسخه ۱.۱.۰-rc01

۲ ژوئیه ۲۰۱۹

androidx.preference:preference:1.1.0-rc01 و androidx.preference:preference-ktx:1.1.0-rc01 منتشر شدند. کامیت‌های موجود در این نسخه را می‌توانید اینجا بیابید.

تغییرات API

  • منسوخ کردن Preference#onInitializeAccessibilityNodeInfo
  • این روش اطلاعات گره دسترسی را برای یک Preference خاص پروکسی می‌کرد - اما این لایه برای این سفارشی‌سازی اشتباه است. اگر می‌خواهید اطلاعات دسترسی را تنظیم کنید، باید onBindViewHolder را بازنویسی کنید و اطلاعات دسترسی را مستقیماً به نما اضافه کنید.

نسخه ۱.۱.۰-بتا۰۱

۵ ژوئن ۲۰۱۹

androidx.preference:preference:1.1.0-beta01 و androidx.preference:preference-ktx:1.1.0-beta01 منتشر شدند. کامیت‌های موجود در این نسخه را می‌توانید اینجا بیابید.

تغییرات مهم از زمان ۱.۱.۰

اگر این اولین نسخه ۱.۱.* است که به آن به‌روزرسانی می‌کنید، در اینجا فهرست مختصری از تغییرات بزرگ‌تر از زمان آخرین نسخه پایدار، ۱.۱.۰، آورده شده است. همچنین ممکن است راهنمای تنظیمات ، نمونه برنامه و سخنرانی اجلاس توسعه‌دهندگان اندروید برای شما مفید باشد.

  • PreferenceFragment و سایر کلاس‌هایی که از Fragments چارچوب استفاده می‌کنند، منسوخ شده‌اند - شما باید به جای آن از PreferenceFragmentCompat و سایر کلاس‌های *compat استفاده کنید.
  • اکنون می‌توانید یک SummaryProvider را روی یک Preference تنظیم کنید تا خلاصه آن را به صورت پویا پیکربندی کند، هر زمان که Preference به‌روزرسانی شود یا برای کاربر قابل مشاهده باشد. برای اطلاعات بیشتر به راهنما مراجعه کنید.
  • رابط EditTextPreference.OnBindEditTextListener اضافه شد. این رابط امکان سفارشی‌سازی EditText نمایش داده شده در کادر محاوره‌ای مربوطه را پس از اتصال کادر محاوره‌ای فراهم می‌کند. این یک جایگزین مستقیم برای استفاده مستقیم از ویژگی‌هایی مانند android:inputType در EditTextPreference است که در کتابخانه AndroidX پشتیبانی نمی‌شود. برای اطلاعات بیشتر به راهنما مراجعه کنید.
  • اضافه شدن Preference.setCopyingEnabled() ‎ هنگام تنظیم، با فشار دادن طولانی روی Preference، منوی زمینه‌ای نمایش داده می‌شود که امکان کپی کردن خلاصه Preference را فراهم می‌کند.
  • استایل SeekBarPreference به‌روزرسانی شد تا با مشخصات متریال مطابقت داشته باشد. برای مشاهده‌ی سایر تغییرات SeekBarPreference، به جزئیات تغییرات مراجعه کنید.
  • مقدار زیادی رفع اشکال، به‌روزرسانی‌های سبک، رفع مشکلات سازگاری سطح API و بهبودهای کلی کیفیت زندگی.

تغییرات API از نسخه ۱.۱.۰-آلفا۰۵

  • getOnBindEditTextListener را از API عمومی حذف می‌کند، شما فقط باید هنگام تعامل با این API از setOnBindEditTextListener استفاده کنید.

لطفاً در صورت بروز هرگونه مشکل، یا اگر پیشنهادی برای ویژگی‌های جدید دارید، اشکالات را اینجا ثبت کنید!

نسخه ۱.۱.۰-آلفا۰۵

۷ مه ۲۰۱۹

androidx.preference:preference:1.1.0-alpha05 و androidx.preference:preference-ktx:1.1.0-alpha05 منتشر شدند. کامیت‌های موجود در این نسخه را می‌توانید اینجا بیابید.

ویژگی‌های جدید

  • استایل‌بندی تنظیمات غیرقابل انتخاب به‌روزرسانی شد - عنوان و خلاصه اکنون رنگ یکسانی دارند تا مشخص شود که نمی‌توان با آنها تعامل داشت و فقط برای نمایش اطلاعات استفاده می‌شوند.
  • توجه: شاید بخواهید enableCopying="true" را به تنظیمات برگزیده‌ی غیرقابل انتخاب خود اضافه کنید تا بتوانید برای کپی کردن خلاصه، انگشت خود را نگه دارید.

رفع اشکالات

  • مشکل رگرسیونی که باعث می‌شد PreferenceCategory و سایر تنظیمات غیرقابل انتخاب، هنگام انتخاب، اثر موجی داشته باشند، برطرف شد.
  • مشکل دسترسی‌پذیری که در آن TalkBack، DropDownPreference را قابل کلیک نمی‌دید، برطرف شد.
  • برخی از مشکلات طرح‌بندی RTL برطرف شد
  • برخی از حاشیه‌نویسی‌های nullable در PreferenceFragmentCompat برای مطابقت با Fragment به‌روزرسانی شدند.

نسخه ۱.۱.۰-آلفا۰۴

۱۳ مارس ۲۰۱۹

androidx.preference:preference:1.1.0-alpha04 و androidx.preference:preference-ktx:1.1.0-alpha04 منتشر شدند. لیست کامل کامیت‌های موجود در این نسخه را می‌توانید اینجا بیابید.

ویژگی‌های جدید

به‌روزرسانی SeekBarPreference !

  • استایل‌بندی برای مطابقت با مشخصات مواد به‌روزرسانی شد
    • برچسب مقدار اکنون به طور پیش‌فرض پنهان است، اگرچه هنوز هم می‌توان آن را با app:showSeekBarValue="true" یا setShowSeekBarValue(true) نمایش داد. این برچسب بخشی از مشخصات Material نیست، اما ما می‌دانیم که به شدت مورد استفاده قرار می‌گیرد، بنابراین به پشتیبانی از آن ادامه خواهیم داد - حتی اگر استفاده از آن را توصیه نکنیم.
    • برچسب مقدار اکنون هنگام کشیدن SeekBar به‌روزرسانی می‌شود، نه هنگام رها شدن آن. توجه داشته باشید که این به معنای به‌روزرسانی داخلی مقدار نیست، برای مشاهده API جدیدی که این قابلیت را فعال می‌کند، به زیر مراجعه کنید.
    • توجه: اگرچه پشتیبانی می‌شود، اما باید از تنظیم خلاصه روی SeekBarPreference خودداری کنید، زیرا این کار در نظر گرفته نشده و بخشی از مشخصات Material نیست.
  • پشتیبانی از به‌روزرسانی‌های مداوم را اضافه می‌کند و به SeekBar اجازه می‌دهد تا مقدار ذخیره شده خود را در حین کشیدن SeekBar به‌روزرسانی کند. این قابلیت را می‌توان از طریق XML یا به صورت برنامه‌نویسی، با استفاده از app:updatesContinuously="true" یا setUpdatesContinuously(true) فعال کرد. این قابلیت هر زمان که موقعیت SeekBar روی صفحه تغییر کند، فعال می‌شود.

تغییرات API

  • حاشیه‌نویسی‌های nullability که وجود ندارند را به findPreference() اضافه می‌کند.

رفع اشکالات

  • اشکالی که باعث می‌شد در صورت فعال نبودن کپی، شنونده‌های منوی زمینه به درستی حذف نشوند، برطرف شد.

نسخه ۱.۱.۰-آلفا۰۳

۷ فوریه ۲۰۱۹

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 )
  • مشکل کار نکردن SummaryProvider برای MultiSelectListPreference ( b/123022772 ) برطرف شد.

نسخه ۱.۱.۰-آلفا۰۲

۱۷ دسامبر ۲۰۱۸

لطفاً راهنمای تنظیمات و برنامه نمونه که اخیراً به‌روزرسانی شده است را نیز بررسی کنید.

ویژگی‌های جدید

  • رابط EditTextPreference.OnBindEditTextListener اضافه شد. این رابط امکان سفارشی‌سازی EditText نمایش داده شده در کادر محاوره‌ای مربوطه را پس از اتصال کادر محاوره‌ای فراهم می‌کند. برای مثال، تنظیم نوع/طول ورودی سفارشی یا اضافه کردن یک TextWatcher.

  • اضافه شدن Preference.setCopyingEnabled() ‎ هنگام تنظیم، با لمس طولانی روی Preference، منوی زمینه‌ای نمایش داده می‌شود که امکان کپی کردن خلاصه Preference را فراهم می‌کند. این قابلیت می‌تواند برای کپی کردن اطلاعات استاتیک مانند شناسه‌های خاص کاربر / اطلاعات نسخه برنامه استفاده شود.

  • preferenceTheme اکنون روی تم اکتیویتی اعمال شده است. این بدان معناست که هنگام ایجاد یک Preference از کد، دیگر نیازی به استفاده از context از PreferenceManager#getContext() ندارید - می‌توانید فقط از context فرگمنت/اکتیویتی خود استفاده کنید.

تغییرات API

  • تابع findPreference() ‎ برای برگرداندن <T extends Preference> بازسازی شد. این یعنی دیگر نیازی نیست هنگام استفاده از findPreference()‎ به طور صریح Preferences را تبدیل نوع کنید. برای مثال، کد زیر معتبر است: EditTextPreference preference = findPreference(“edit_text”) .

نسخه ۱.۱.۰-آلفا۰۱

۵ نوامبر ۲۰۱۸

ویژگی‌های جدید

  • اکنون می‌توانید یک SummaryProvider را روی یک Preference تنظیم کنید تا خلاصه آن را به صورت پویا پیکربندی کند، هر زمان که Preference به‌روزرسانی شود یا برای کاربر قابل مشاهده باشد.
  • پیاده‌سازی‌های پیش‌فرض SummaryProvider برای ListPreference و EditTextPreference اضافه شده است که وقتی تنظیم می‌شوند، خلاصه Preference را به‌طور خودکار به‌روزرسانی می‌کنند تا مقدار ذخیره‌شده‌اش را منعکس کنند، یا اگر مقداری ذخیره نشده باشد، «تنظیم نشده» را نمایش می‌دهند. این موارد را می‌توان با app:useSimpleSummaryProvider=”true” تنظیم کرد.
  • اضافه شدن PreferenceGroup#removePreferenceRecursively که به صورت بازگشتی یک Preference را از گروه یا یک گروه تو در تو در سلسله مراتب پایین‌تر پیدا و حذف می‌کند.

تغییرات API

  • PreferenceFragment و سایر کلاس‌هایی که از Fragments چارچوب استفاده می‌کنند، منسوخ شده‌اند - شما باید به جای آن از PreferenceFragmentCompat و سایر کلاس‌های compat استفاده کنید.

رفع اشکالات

  • مشکل عدم کارکرد صحیح iconSpaceReserved با PreferenceCategories برطرف شد.
  • رفع مشکل عدم استفاده از colorAccent برای رنگ عنوان دسته بندی‌های ترجیحی در نسخه‌های پایین‌تر از API 21.
  • برخی از ناهماهنگی‌های طرح‌بندی SeekBarPreference در API 21 برطرف شد.