إذا كان لديك مجموعة صغيرة نسبيًا من القيم الأساسية التي تريد حفظها،
يمكنك استخدام واجهات برمجة تطبيقات SharedPreferences
. يشير الكائن SharedPreferences
إلى ملف يحتوي على أزواج المفتاح/القيمة ويقدّم طرقًا بسيطة لقراءتها وكتابتها. تتم إدارة كل ملف SharedPreferences
من خلال إطار العمل ويمكن أن
يكون خاصًا أو مشتركًا.
توضّح لك هذه الصفحة كيفية استخدام واجهات برمجة التطبيقات SharedPreferences
لتخزين القيم البسيطة واستردادها.
التحكّم في الإعدادات المفضّلة المشتركة
يمكنك إنشاء ملف تفضيل مشترك جديد أو الوصول إلى ملف حالي عن طريق استدعاء إحدى الطرق التالية:
getSharedPreferences()
: يمكنك استخدام هذا الخيار إذا كنت بحاجة إلى عدة ملفات مفضّلة مشتركة يتم تحديدها بالاسم، والتي تحدّدها بالمَعلمة الأولى. يمكنك الاتصال بهذا الرقم من أيContext
في تطبيقك.getPreferences()
: استخدِم هذا الخيار منActivity
إذا أردت استخدام ملف تفضيل مشترك واحد فقط للنشاط. نظرًا لأن هذا يسترد ملف التفضيل المشترك الافتراضي الذي ينتمي إلى النشاط، فلن تحتاج إلى تقديم اسم.
على سبيل المثال، يصل الرمز البرمجي التالي إلى ملف الإعدادات المفضّلة المشتركة الذي تحدّده سلسلة المورد R.string.preference_file_key
ويفتحه باستخدام الوضع الخاص بحيث لا يمكن إلا لتطبيقك فقط الوصول إلى الملف:
Kotlin
val sharedPref = activity?.getSharedPreferences( getString(R.string.preference_file_key), Context.MODE_PRIVATE)
Java
Context context = getActivity(); SharedPreferences sharedPref = context.getSharedPreferences( getString(R.string.preference_file_key), Context.MODE_PRIVATE);
عند تسمية ملفات الإعدادات المفضّلة المشتركة، يجب استخدام اسم يسهل التعرّف عليه لتطبيقك. وأفضل طريقة لإجراء ذلك هي بادئة اسم الملف بـ معرّف التطبيق. مثلاً:
"com.example.myapp.PREFERENCE_FILE_KEY"
بدلاً من ذلك، إذا كنت بحاجة إلى ملف اختيار واحد مفضّل مشترك لنشاطك،
يمكنك استخدام طريقة getPreferences()
كما يلي:
Kotlin
val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE)
Java
SharedPreferences sharedPref = getActivity().getPreferences(Context.MODE_PRIVATE);
إذا كنت تستخدم واجهة برمجة تطبيقات SharedPreferences
لحفظ إعدادات التطبيق، عليك
بدلاً من ذلك استخدام getDefaultSharedPreferences()
للحصول على ملف الإعدادات المفضّلة المشتركة التلقائية لتطبيقك بالكامل. ولمزيد من المعلومات، يمكنك الاطّلاع على
دليل مطوّر الإعدادات.
الكتابة إلى الإعدادات المفضّلة المشترَكة
للكتابة إلى ملف إعدادات مفضّلة تمّت مشاركته، أنشِئ SharedPreferences.Editor
من خلال طلب الرقم edit()
على SharedPreferences
.
مرِّر المفاتيح والقيم التي تريد كتابتها باستخدام طُرق مثل:
putInt()
وputString()
. بعد ذلك، يمكنك الاتصال بالرقم apply()
أو
commit()
لحفظ التغييرات. مثلاً:
Kotlin
val sharedPref = activity?.getPreferences(Context.MODE_PRIVATE) ?: return with (sharedPref.edit()) { putInt(getString(R.string.saved_high_score_key), newHighScore) apply() }
Java
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()
متزامن، يجب تجنُّب طلبه من سلسلة التعليمات الرئيسية لأنّ ذلك قد يؤدي إلى إيقاف عرض واجهة المستخدم مؤقتًا.
القراءة من الإعدادات المفضّلة المشتركة
لاسترداد القيم من ملف الإعدادات المفضّلة المشتركة، يمكن استخدام طُرق استدعاء مثل getInt()
وgetString()
مع توفير المفتاح للقيمة التي تريدها، واختيار قيمة تلقائية لعرضها في حال عدم توفّر المفتاح. على سبيل المثال:
Kotlin
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)
Java
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);