העדפה

אפשר ליצור מסכי הגדרות אינטראקטיביים בלי צורך באינטראקציה עם אחסון המכשיר או בניהול ממשק המשתמש.
העדכון האחרון גרסה יציבה גרסה מועמדת להפצה גרסת בטא גרסת אלפא
26 ביולי 2023 1.2.1 - - -

הצהרה על יחסי תלות

כדי להוסיף תלות ב-Preference, צריך להוסיף את מאגר 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")
}

מידע נוסף על יחסי תלות זמין במאמר הוספת יחסי תלות ב-build.

משוב

המשוב שלכם עוזר לנו לשפר את 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()
    }
}

  • הוספנו אנוטציות לגבי מאפיין המציין אם ערך יכול להיות ריק (nullability) להרבה ממשקי API שלא צוין בהם בעבר @NonNull או @Nullable. זהו שינוי שעלול לגרום לשגיאות בקוד המקור של Kotlin, אם ערכי ה-nullability שבחרתם בקוד Kotlin לא תואמים לערכי ה-nullability שמוגדרים עכשיו.

  • ‫PreferenceFragmentCompat’s now looks for implementations of the OnPreferenceStartFragmentCallback, OnNavigateToScreenListener, and OnDisplayPreferenceDialogListener interface on parent fragments before looking to see if the hosting Context or Activity implement these interfaces.

גרסה ‎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 מכילה את השמירות האלה.

שינויים ב-API

  • נוספו אנוטציות לגבי מאפיין המציין אם ערך יכול להיות ריק (nullability) להרבה ממשקי API שלא צוין בהם בעבר @NonNull או @Nullable. (I04252, Ie2cc0)
  • הוסר ה-API‏ openPreference() מ-PreferenceHeaderFragmentCompat – השיטה הזו נקראת בשבילכם ואין לקרוא לה באופן ידני. (Ia6989)

שינויים בהתנהגות

  • הקריאות החוזרות (callbacks) של PreferenceFragmentCompat עבור OnNavigateToScreenListener ו-OnDisplayPreferenceDialogListener פועלות עכשיו לפי אותו דפוס כמו OnPreferenceTreeClickListener, והן מחפשות את היררכיית הפרגמנטים של האב כדי למצוא מאזינים (listeners) תקפים לפני שהן בודקות אם Context או Activity של המארח מטמיעים את הממשקים האלה. (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 מכילה את השמירות האלה.

תכונות חדשות

  • נוספה העדפה של שני חלונות (I9a2d8)PreferenceHeaderFragmentCompat

שינויים בהתנהגות

  • מעכשיו אפשר להטמיע קריאות חוזרות (callback) להעדפות עבור OnPreferenceDisplayDialogCallback,‏ OnPreferenceStartScreenCallback ו-OnPreferenceStartFragmentCallback בהקשר שאינו Activity. המערכת בודקת את getContext()‎ כדי לראות אם היא מטמיעה את הקריאות החוזרות האלה לפני שהיא בודקת את getActivity()‎. אם getContext()‎ מחזירה Activity (המקרה הנפוץ), לא חל שינוי בהתנהגות.

  • הקריאה של PreferenceFragmentCompat אל onPreferenceTreeClick מחפשת עכשיו הטמעות של הממשק OnPreferenceStartFragmentCallback בקטעי ה-Fragment של ההורה לפני שהיא בודקת את ההטמעה של Activity. (c64eed)

גרסה 1.1

גרסה 1.1.1

15 באפריל 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 ובמחלקות אחרות מסוג *compat.
  • עכשיו אפשר להגדיר SummaryProvider להעדפה כדי להגדיר באופן דינמי את הסיכום שלה בכל פעם שההעדפה מתעדכנת או הופכת גלויה למשתמש. מידע נוסף זמין במדריך.
  • נוסף ממשק EditTextPreference.OnBindEditTextListener. כך אפשר להתאים אישית את EditText שמוצג בתיבת הדו-שיח המתאימה אחרי שהיא קושרה. השימוש ב-API הזה מחליף את השימוש במאפיינים כמו android:inputType ישירות ב-EditTextPreference, שלא נתמך בספריית AndroidX. מידע נוסף זמין במדריך.
  • נוסף Preference.setCopyingEnabled() כשמגדירים את ההעדפה, לחיצה ארוכה עליה תציג תפריט הקשר שמאפשר להעתיק את הסיכום שלה.
  • עדכנו את הסגנון של SeekBarPreference כך שיתאים למפרטים של Material. שינויים נוספים ב-SeekBarPreference מפורטים ביומן השינויים.
  • כמות גדולה של תיקוני באגים, עדכוני סגנון, תיקוני תאימות ברמת ה-API ושיפורים כלליים באיכות החיים.

גרסה ‎1.1.0-rc01

‫2 ביולי 2019

‫androidx.preference:preference:1.1.0-rc01 וגם androidx.preference:preference-ktx:1.1.0-rc01 מופצים. כאן אפשר לראות את השמירות שכלולות בגרסה הזו.

שינויים ב-API

  • הוצאה משימוש של 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 ואת מחלקות אחרות שמשתמשות ב-Framework Fragments. במקומן צריך להשתמש ב-PreferenceFragmentCompat ובמחלקות אחרות מסוג *compat.
  • עכשיו אפשר להגדיר SummaryProvider ב-Preference כדי להגדיר באופן דינמי את הסיכום שלו בכל פעם ש-Preference מתעדכן או הופך לגלוי למשתמש. מידע נוסף זמין במדריך.
  • נוסף ממשק EditTextPreference.OnBindEditTextListener. ההגדרה הזו מאפשרת להתאים אישית את רכיב ה-EditText שמוצג בתיבת הדו-שיח המתאימה אחרי שתיבת הדו-שיח נקשרה. זוהי החלפה ישירה לשימוש במאפיינים כמו android:inputType ישירות ב-EditTextPreference, שלא נתמך בספריית AndroidX. מידע נוסף זמין במדריך.
  • נוסף Preference.setCopyingEnabled() כשמגדירים את ההעדפה, לחיצה ארוכה עליה תציג תפריט הקשר שמאפשר להעתיק את הסיכום שלה.
  • העיצוב של SeekBarPreference עודכן כך שיתאים למפרט Material. שינויים נוספים ב-SeekBarPreference מפורטים במאמר בנושא יומן שינויים.
  • כמות גדולה של תיקוני באגים, עדכוני סגנון, תיקוני תאימות ברמת ה-API ושיפורים כלליים באיכות החיים.

שינויים ב-API מאז גרסה ‎1.1.0-alpha05

  • הוסרה הפונקציה getOnBindEditTextListener מ-API ציבורי. צריך להשתמש רק בפונקציה setOnBindEditTextListener כשמבצעים אינטראקציה עם ה-API הזה.

אם נתקלתם בבעיות או שיש לכם הצעות לתכונות חדשות, אתם יכולים לדווח על באגים כאן.

גרסה ‎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 מופצים. כאן אפשר לראות את הרשימה המלאה של פעולות ה-commit שכלולות בגרסה הזו.

תכונות חדשות

העדכון של SeekBarPreference

  • העיצוב עודכן בהתאם למפרטים של Material
    • תווית הערך מוסתרת עכשיו כברירת מחדל, אבל עדיין אפשר להציג אותה באמצעות app:showSeekBarValue="true" או setShowSeekBarValue(true). התווית הזו לא כלולה במפרט של Material, אבל אנחנו מבינים שהיא בשימוש נרחב ולכן נמשיך לתמוך בה – למרות שאנחנו לא ממליצים להשתמש בה.
    • תווית הערך מתעדכנת עכשיו בזמן הגרירה של פס ההזזה, ולא כשהוא משוחרר. שימו לב: זה לא אומר שהערך מתעדכן באופן פנימי. בהמשך מוסבר על API חדש שמאפשר את הפונקציונליות הזו.
    • הערה: למרות שיש תמיכה בהגדרה של סיכום ב-SeekBarPreference, מומלץ להימנע מכך כי זה לא הייעוד של ההגדרה הזו והיא לא חלק ממפרט Material.
  • נוספה תמיכה בעדכונים רציפים, שמאפשרת לעדכן את הערך השמור של SeekBar בזמן הגרירה של SeekBar. אפשר להפעיל את ההגדרה הזו מ-XML או באופן פרוגרמטי, באמצעות app:updatesContinuously="true" או setUpdatesContinuously(true). הפעולה הזו תופעל בכל פעם שהמיקום של פס ההזזה במסך ישתנה.

שינויים ב-API

  • הוספת אנוטציות חסרות של nullability ל-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)
  • תוקנה הבעיה שבה SummaryProvider לא פועל עבור MultiSelectListPreference (b/123022772)

גרסה ‎1.1.0-alpha02

‫17 בדצמבר 2018

מומלץ לעיין גם במדריך ההגדרות שעדכנו לאחרונה ובאפליקציה לדוגמה.

תכונות חדשות

  • נוסף EditTextPreference.OnBindEditTextListener interface הוא מאפשר להתאים אישית את ה-EditText שמוצג בתיבת הדו-שיח המתאימה אחרי שהיא נקשרה. לדוגמה, הגדרת אורך או סוג קלט מותאמים אישית או הוספת TextWatcher.

  • נוסף Preference.setCopyingEnabled() כשמגדירים את ההעדפה, לחיצה ארוכה עליה תציג תפריט הקשר שמאפשר להעתיק את הסיכום שלה. אפשר להשתמש בהגדרה הזו כדי לאפשר העתקה של מידע סטטי, כמו מזהים ספציפיים למשתמש או פרטי גרסת האפליקציה.

  • המאפיין preferenceTheme מוחל עכשיו על ערכת הנושא של הפעילות כלומר, כשיוצרים Preference מקוד, כבר לא צריך להשתמש בהקשר מ-PreferenceManager#getContext() – אפשר פשוט להשתמש בהקשר של Fragment או Activity.

שינויים ב-API

  • בוצע רפקטורינג של findPreference() כדי להחזיר <T extends Preference> המשמעות היא שלא צריך לבצע המרה מפורשת של Preferences כשמשתמשים ב-findPreference(). לדוגמה, EditTextPreference preference = findPreference(“edit_text”) הוא עכשיו קוד תקין.

גרסה ‎1.1.0-alpha01

‫5 בנובמבר 2018

תכונות חדשות

  • עכשיו אפשר להגדיר SummaryProvider בהעדפה כדי להגדיר באופן דינמי את הסיכום שלה בכל פעם שההעדפה מתעדכנת או הופכת גלויה למשתמש.
  • נוספו הטמעות ברירת מחדל של SummaryProvider עבור ListPreference ו-EditTextPreference. אם הן מוגדרות, הן מעדכנות באופן אוטומטי את הסיכום של Preference כדי לשקף את הערך השמור שלו, או את הערך Not Set אם לא נשמר ערך. אפשר להגדיר אותם באמצעות app:useSimpleSummaryProvider=”true”
  • נוספה הפונקציה PreferenceGroup#removePreferenceRecursively שמוצאת באופן רקורסיבי Preference ומסירה אותו מהקבוצה, או מקבוצה בתוך קבוצה ברמה נמוכה יותר בהיררכיה.

שינויים ב-API

  • הוצאנו משימוש את PreferenceFragment ואת מחלקות אחרות שמשתמשות ב-framework Fragments. במקומם, צריך להשתמש ב-PreferenceFragmentCompat ובמחלקות תאימות אחרות.

תיקוני באגים

  • תוקנה הבעיה שבה iconSpaceReserved לא פעל בצורה תקינה עם PreferenceCategories.
  • תוקן באפליקציות שפועלות בגרסאות API נמוכות מ-21: PreferenceCategories לא משתמשות ב-colorAccent לצבע של שם הפריט.
  • תוקנו כמה אי-התאמות בפריסת SeekBarPreference בגרסאות שמתחת ל-API 21.