حفظ البيانات البسيطة باستخدام SharedPreferences

إذا كانت لديك مجموعة صغيرة نسبيًا من قيم المفاتيح التي تريد حفظها، يمكنك استخدام واجهات برمجة تطبيقات SharedPreferences. يشير الكائن SharedPreferences إلى ملف يحتوي على أزواج المفتاح/القيمة ويوفر طرقًا بسيطة لقراءتها وكتابتها. يدير إطار العمل كل ملف SharedPreferences، ويُمكن أن يكون ملفًا خاصًا أو مشترَكًا.

توضّح لك هذه الصفحة كيفية استخدام واجهات برمجة تطبيقات SharedPreferences لتخزين القيم البسيطة واستردادها.

الحصول على اسم معرِّف للإعدادات المفضّلة المشتركة

يمكنك إنشاء ملف جديد للإعدادات المفضّلة المشتركة أو الوصول إلى ملف حالي من خلال استدعاء إحدى الطريقتَين التاليتَين:

• getSharedPreferences(): استخدِم هذا الخيار إذا كنت بحاجة إلى عدة ملفات إعدادات مفضّلة مشترَكة يتم تحديدها حسب الاسم، والتي تحدِّدها باستخدام المَعلمة الأولى. يمكنك استدعاء هذا الإجراء من أي Context في تطبيقك.
• getPreferences(): استخدِم هذا النموذج من Activity إذا كنت بحاجة إلى استخدام ملف إعدادات مفضّل واحد مشترك فقط للنشاط. نظرًا لأن هذا يسترد ملف تفضيل مشترك افتراضي ينتمي إلى النشاط، فلا تحتاج إلى تقديم اسم.

على سبيل المثال، يصل الرمز التالي إلى ملف الإعدادات المفضَّلة المشتركة الذي تم تحديده من خلال سلسلة المورد R.string.preference_file_key، ويفتح هذا الرمز باستخدام الوضع الخاص ليتمكّن تطبيقك فقط من الوصول إلى الملف:

val sharedPref = activity?.getSharedPreferences(
        getString(R.string.preference_file_key), Context.MODE_PRIVATE)

Context context = getActivity();
SharedPreferences sharedPref = context.getSharedPreferences(
        getString(R.string.preference_file_key), Context.MODE_PRIVATE);

عند تسمية ملفات الإعدادات المفضّلة المشتركة، يجب استخدام اسم يُحدِّد تطبيقك بشكلٍ فريد. ومن الطرق الجيدة لإجراء ذلك إضافة رقم تعريف تطبيقك إلى اسم الملف. على سبيل المثال: "com.example.myapp.PREFERENCE_FILE_KEY"

بدلاً من ذلك، إذا كنت بحاجة إلى ملف إعدادات مفضّل واحد مشترك لنشاطك، يمكنك استخدام طريقة getPreferences():

val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE)

SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);

إذا كنت تستخدِم واجهة برمجة التطبيقات SharedPreferences لحفظ إعدادات التطبيق، يجب استخدام getDefaultSharedPreferences() بدلاً من ذلك للحصول على ملف الإعدادات المفضّلة المشترَكة التلقائي لتطبيقك بالكامل. لمزيد من المعلومات، يُرجى الاطّلاع على دليل المطوّر الخاص بالإعدادات.

الكتابة في الإعدادات المفضّلة المشتركة

للكتابة في ملف الإعدادات المفضّلة المشتركة، أنشئ SharedPreferences.Editor من خلال الاتصال edit() على SharedPreferences.

نقْل المفاتيح والقيم التي تريد كتابتها باستخدام طرق مثل: putInt() وputString() بعد ذلك، اضغط على apply() أو commit() لحفظ التغييرات. مثلاً:

val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return
with (sharedPref.edit()) {
    putInt(getString(R.string.saved_high_score_key), newHighScore)
    apply()
}

SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
SharedPreferences.Editor editor = sharedPref.edit();
editor.putInt(getString(R.string.saved_high_score_key), newHighScore);
editor.apply();

يغيّر apply() الكائن SharedPreferences في الذاكرة على الفور، ولكنه يكتب التحديثات على القرص بشكل غير متزامن. بدلاً من ذلك، يمكنك استخدام commit() لكتابة البيانات على القرص بشكل متزامن. ولكن بما أنّ commit() متزامنة، يجب تجنُّب طلبها من سلسلة التعليمات الرئيسية لأنّ ذلك قد يؤدي إلى إيقاف عرض واجهة المستخدم مؤقتًا.

القراءة من الإعدادات المفضّلة المشتركة

لاسترداد القيم من ملف الإعدادات المفضّلة المشترَكة، يمكنك استدعاء طُرق مثل methods getInt() وgetString()، مع تقديم مفتاح القيمة التي تريدها، واختياريًا قيمة تلقائية لعرضها إذا لم يكن المفتاح متوفّرًا. على سبيل المثال:

val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return
val defaultValue = resources.getInteger(R.integer.saved_high_score_default_key)
val highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue)

SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
int defaultValue = getResources().getInteger(R.integer.saved_high_score_default_key);
int highScore = sharedPref.getInt(getString(R.string.saved_high_score_key), defaultValue);