الإعدادات جزء من Android Jetpack.

تتيح الإعدادات للمستخدمين تغيير وظائف التطبيق وسلوكه. ويمكن أن تؤثر الإعدادات في السلوك في الخلفية، مثل عدد المرات التي يُزامن فيها التطبيق البيانات مع السحابة الإلكترونية، أو يمكن أن يكون لها تأثير أوسع نطاقًا، مثل تغيير محتوى واجهة المستخدم وطريقة عرضها.

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

البدء

يُعد Preference الوحدة الأساسية لمكتبة الإعدادات المفضّلة. تحتوي شاشة الإعدادات على Preference تدرّج. يمكنك تعريف هذا التدرج الهرمي كمورد XML، أو يمكنك إنشاء تدرج هرمي في الرموز البرمجية.

توضّح الأقسام التالية كيفية إنشاء شاشة إعدادات بسيطة باستخدام مكتبة ملفّات الإعدادات في AndroidX.

قبل البدء، أضِف التبعية لـ "مكتبة الإعدادات المفضّلة" إلى build.gradleملف:

رائع

dependencies {
    implementation "androidx.preference:preference-ktx:1.2.0"
}

Kotlin

dependencies {
    implementation("androidx.preference:preference-ktx:1.2.0")
}

بعد مزامنة Gradle، يمكنك الانتقال إلى جزء XML من المهمة.

إنشاء تسلسل هرمي

في مشروعك، انتقِل إلى مجلد res/xml، وأنشئ ملف preferences.xml، وأضِف الرمز التالي إليه:

<PreferenceScreen
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <SwitchPreferenceCompat
        app:key="notifications"
        app:title="Enable message notifications"/>

    <Preference
        app:key="feedback"
        app:title="Send feedback"
        app:summary="Report technical issues or suggest new features"/>

</PreferenceScreen>

يحتوي هذا التسلسل الهرمي على عنصرَي Preference: أحدهما هو SwitchPreferenceCompat الذي يتيح للمستخدمين تفعيل إعداد وإيقافه، والآخر هو Preference أساسي بدون تطبيق مصغّر.

عند إنشاء تسلسل هرمي، يجب أن يكون لكل Preference مفتاح فريد.

تضخيم التسلسل الهرمي

ولتضخيم ترتيب هرمي من سمة XML، يمكنك إنشاء PreferenceFragmentCompat، وتجاوز onCreatePreferences()، وتوفير مورد XML لتضخيمه، كما هو موضّح في المثال التالي:

Kotlin

class MySettingsFragment : PreferenceFragmentCompat() {
    override fun onCreatePreferences(savedInstanceState: Bundle?, rootKey: String?) {
        setPreferencesFromResource(R.xml.preferences, rootKey)
    }
}

Java

public class MySettingsFragment extends PreferenceFragmentCompat {
    @Override
    public void onCreatePreferences(Bundle savedInstanceState, String rootKey) {
        setPreferencesFromResource(R.xml.preferences, rootKey);
    }
}

يمكنك بعد ذلك إضافة هذا Fragment إلى Activity كما تفعل مع أي Fragment آخر:

Kotlin

class MySettingsActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        supportFragmentManager
                .beginTransaction()
                .replace(R.id.settings_container, MySettingsFragment())
                .commit()
    }
}

Java

public class MySettingsActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        getSupportFragmentManager()
                .beginTransaction()
                .replace(R.id.settings_container, new MySettingsFragment())
                .commit();
    }
}

تظهر النتيجة في الصورة التالية:

صورة تعرض مثالاً على شاشة الإعدادات المفضّلة
الشكل 1. شاشة إعدادات تم إنشاؤها باستخدام كائنَين Preference

مراقبة الإعدادات المفضّلة

يمكنك الحصول على حدث عندما يتغيّر أحد الإعدادات المفضّلة من خلال تسجيل أداة استماع له:

Kotlin

findPreference<SwitchPreferenceCompat>("notifications")
    ?.setOnPreferenceChangeListener { _, newValue ->
        Log.d("Preferences", "Notifications enabled: $newValue")
        true // Return true if the event is handled.
    }

findPreference<Preference>("feedback")
    ?.setOnPreferenceClickListener {
        Log.d("Preferences", "Feedback was clicked")
        true // Return true if the click is handled.
    }

Java

SwitchPreferenceCompat notificationsPref = findPreference("notifications");

if (notificationsPref != null) {
    notificationsPref.setOnPreferenceChangeListener((preference, newValue) -> {
        Log.d("Preferences", String.format("Notifications enabled: %s", newValue));
        return true; // Return true if the event is handled.
    });
}

Preference feedbackPref = findPreference("feedback");

if (feedbackPref != null) {
    feedbackPref.setOnPreferenceClickListener((preference) -> {
        Log.d("Preferences", "Feedback was clicked");
        return true; // Return true if the event is handled.
    });
}

قراءة قيمة التفضيل الحالية

PreferenceFragmentCompat يخفي الكثير من الآليات المُستخدَمة في حفظ الإعدادات المفضّلة وقراءتها. ومع ذلك، يتم تخزين كل شيء باستخدام SharedPreferences، ويمكنك قراءة هذه القيم كما تفعل عادةً باستخدام SharedPreferences:

Kotlin

val preferences = PreferenceManager.getDefaultSharedPreferences(this).all

preferences.forEach {
    Log.d("Preferences", "${it.key} -> ${it.value}")
}

Java

var preferences = PreferenceManager.getDefaultSharedPreferences(context).getAll();

preferences.forEach((key, value) ->{
    Log.d("Preferences", String.format("%s -> %s", key, value));
});

يحصل المقتطف السابق على مثيل من SharedPreferences التلقائي للتطبيق، ويصل إلى جميع القيم المخزَّنة، ويكررها، ويطبعها في Logcat.