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

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

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

البدء

علامة 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();
    }
}

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

صورة تعرض مثالاً على شاشة &quot;الإعدادات المفضّلة&quot;
الشكل 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

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.
    }

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

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

Kotlin

val preferences = PreferenceManager.getDefaultSharedPreferences(this).all

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

Java

val preferences = PreferenceManager.getDefaultSharedPreferences(this).all

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

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