התאמה אישית של ההגדרות חלק מ-Android Jetpack.

במסמך הזה נסביר איך לבצע התאמה אישית של מודעות Preference אובייקטים בהיררכיה.

חיפוש העדפות

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

לדוגמה, כדי לגשת EditTextPreference עם תוסף של "signature", צריך לבצע את הפעולות הבאות:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

צריך לאחזר את Preference באמצעות הקוד הבא:

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    val signaturePreference: EditTextPreference? = findPreference("signature")
    // Do something with this preference.
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    EditTextPreference signaturePreference = findPreference("signature");
    // Do something with this preference.
}

שליטה בחשיפה של ההעדפות

אפשר לקבוע אילו אובייקטים מסוג Preference יהיו גלויים למשתמש כשהם עוברים למסך ההגדרות. לדוגמה, אם Preference מסוים הוא משמעותי רק כשתכונה תואמת מופעלת, ייתכן שתרצו להסתיר שPreference כשהתכונה מושבתת.

כדי להציג Preference רק כשתנאי מסוים מתקיים, קודם צריך להגדיר את Preference ב-XML, כמו בדוגמה הבאה:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"
        app:isPreferenceVisible="false"/>

ב-onCreatePreferences(), צריך להציג את Preference כשמתקיים התנאי:

Kotlin

override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
    setPreferencesFromResource(R.xml.preferences, rootKey)
    if(/*some feature*/) {
        val signaturePreference: EditTextPreference? = findPreference("signature")
        signaturePreference?.isVisible = true
    }
}

Java

@Override
public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
    setPreferencesFromResource(R.xml.preferences, rootKey);
    if(/*some feature*/) {
        EditTextPreference signaturePreference = findPreference("signature");
        if (signaturePreference != null) {
            signaturePreference.setVisible(true);
        }
    }
}

עדכון דינמי של סיכומים

Preference שנשאר עם נתונים צריך להציג את הערך הנוכחי שלו סיכום שיעזור למשתמשים להבין טוב יותר את המצב הנוכחי Preference לדוגמה, EditTextPreference חייב להציג את הטקסט השמור והערך ListPreference חייב להציג את רשומת הרשימה שנבחרה. אפשר גם יש Preference אובייקטים שצריכים לעדכן את הסיכום שלהם על סמך נתונים פנימיים או מצב של אפליקציית צד שלישי. לדוגמה, Preference שמציג גרסה מספר. אפשר לעשות זאת באמצעות SummaryProvider

שימוש ב-SimpleSummaryProvider

ListPreference וגם EditTextPreference כוללות הטמעות פשוטות של SummaryProvider שמציגות באופן אוטומטי נשמר ערך Preference כסיכום. אם לא נשמר ערך, תוצג ההודעה 'לא הגדירו".

כדי להפעיל את ההטמעות האלה מתוך XML, צריך להגדיר app:useSimpleSummaryProvider="true"

לחלופין, בקוד אפשר להשתמש ListPreference.SimpleSummaryProvider.getInstance() וגם EditTextPreference.SimpleSummaryProvider.getInstance() כדי לקבל את המכונה הפשוטה של SummaryProvider ואז להגדיר אותה Preference, כמו בדוגמה הבאה:

Kotlin

listPreference.summaryProvider = ListPreference.SimpleSummaryProvider.getInstance()
editTextPreference.summaryProvider = EditTextPreference.SimpleSummaryProvider.getInstance()

Java

listPreference.setSummaryProvider(ListPreference.SimpleSummaryProvider.getInstance());
editTextPreference.setSummaryProvider(EditTextPreference.SimpleSummaryProvider.getInstance());

שימוש ב-SummaryProvider בהתאמה אישית

אפשר ליצור SummaryProvider משלך ולשנות provideSummary() כדי להתאים אישית את הסיכום בכל פעם ש-Preference ביקש אותו. עבור לדוגמה, ב-EditTextPreference הבא מוצג אורך הסרטון השמור בתור סיכום:

איור 1. למשל EditTextPreference.

לדוגמה, נניח את הEditTextPreference הבאה:

<EditTextPreference
        app:key="counting"
        app:title="Counting preference"/>

ב-onCreatePreferences(), אפשר ליצור SummaryProvider חדש ולשנות אותו provideSummary() כדי להחזיר את הסיכום להצגה:

Kotlin

val countingPreference: EditTextPreference? = findPreference("counting")

countingPreference?.summaryProvider = SummaryProvider<EditTextPreference> { preference ->
    val text = preference.text
    if (text.isNullOrEmpty()) {
        "Not set"
    } else {
        "Length of saved value: " + text.length
    }
}

Java

EditTextPreference countingPreference = findPreference("counting");

if (countingPreference != null) {
    countingPreference.setSummaryProvider(new SummaryProvider<EditTextPreference>() {
        @Override
        public CharSequence provideSummary(EditTextPreference preference) {
            String text = preference.getText();
            if (TextUtils.isEmpty(text) || text == null){
                return "Not set";
            }
            return "Length of saved value: " + text.length();
        }
    });
}

בסיכום Preference מוצג משך הערך שנשמר או 'לא מוגדר' כשלא קיים ערך שמור.

התאמה אישית של תיבת הדו-שיח EditTextPreference

בתיבת דו-שיח של EditTextPreference אפשר להתאים אישית את ההתנהגות של שדות טקסט לפי צירוף OnBindEditTextListener. ה-listener הזה מופעל כשמוצגת למשתמש תיבת דו-שיח.

לדוגמה, תוכלו להתאים אישית תיבת דו-שיח כדי לקבל מספרים בלבד. קודם כול, יוצרים EditTextPreference:

<EditTextPreference
        app:key="number"
        app:title="Numbers only preference"/>

בשלב הבא, ב-onCreatePreferences(), יוצרים OnBindEditTextListener חדש לשנות את onBindEditText() כדי להתאים אישית את EditText כשהוא מוצג משתמש.

Kotlin

val numberPreference: EditTextPreference? = findPreference("number")

numberPreference?.setOnBindEditTextListener { editText ->
    editText.inputType = InputType.TYPE_CLASS_NUMBER
}

Java

EditTextPreference numberPreference = findPreference("number");

if (numberPreference != null) {
    numberPreference.setOnBindEditTextListener(
            new EditTextPreference.OnBindEditTextListener() {
                @Override
                public void onBindEditText(@NonNull EditText editText) {
                    editText.setInputType(InputType.TYPE_CLASS_NUMBER);
                }
            });
}

עכשיו, כשתיבת הדו-שיח מוצגת למשתמש, המקלדת נפתחת במספרים בלבד , כך שהמשתמש יכול להזין רק מספרים בEditText.

פעולות של העדפות

כשמקישים על Preference, אפשר לבצע פעולה ספציפית. לדוגמה, Preference יכול לשמש כקישור לחלק נפרד באפליקציה שלך. כדי להוסיף פעולה ל-Preference, אפשר להגדיר Intent ב-Preference ישירות או יכול להגדיר OnPreferenceClickListener ללוגיקה ספציפית יותר.

הגדרת כוונה

אפשר להגדיר Intent ב-Preference כדי להפעיל Fragment חדש, Activity, או אפליקציה נפרדת בכל פעם שמקישים על Preference. כאן בדיוק כמו שמשתמשים Context.startActivity() עם ערך נתון של Intent.

אפשר להגדיר Intent ב-XML באמצעות תג <intent> מקונן. הבאים בדוגמה הזו מגדיר Intent שמפעיל Activity:

<Preference
        app:key="activity"
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity"/>
</Preference>

לחלופין, אפשר להשתמש ב-setIntent() ישירות דרך Preference, באופן הבא:

Kotlin

val intent = Intent(context, ExampleActivity::class.java)
activityPreference.setIntent(intent)

Java

Intent intent = new Intent(getContext(), ExampleActivity.class);
activityPreference.setIntent(intent);

אפשר גם להוסיף תוספות עם Intent באמצעות XML:

<Preference
        app:key="activity"
        app:title="Launch activity">
    <intent
            android:targetPackage="com.example"
            android:targetClass="com.example.ExampleActivity">
        <extra
                android:name="example_key"
                android:value="example_value"/>
    </intent>
</Preference>

הנה דוגמה ל-Preference עם Intent שמפעיל דף אינטרנט:

<Preference
        app:key="webpage"
        app:title="View webpage">
    <intent
            android:action="android.intent.action.VIEW"
            android:data="http://www.google.com" />
</Preference>

Kotlin

val intent = Intent(Intent.ACTION_VIEW)
intent.data = Uri.parse("http://www.google.com")

val webpagePreference = findPreference("webpage")
webpagePreference?.intent = intent

Java

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("http://www.google.com"));
webpagePreference.setIntent(intent);

OnPreferenceClickListener

אפשר להגדיר OnPreferenceClickListener ב-Preference, וכך מוסיפה קריאה חוזרת אל onPreferenceClick() כשמקישים על Preference. לדוגמה, אפשר להשתמש במאזינים כדי לנווט אל Fragment או Activity אחרים אם יש לוגיקה מורכבת יותר בטיפול בניווט.

כדי להגדיר OnPreferenceClickListener, צריך להשתמש בקוד שדומה לזה:

Kotlin

onClickPreference.setOnPreferenceClickListener({
    // Do something.
    true
})

Java

onClickPreference.setOnPreferenceClickListener(preference -> {
    // Do something.
    return true;
});