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

إذا كان لديك مجموعة صغيرة نسبيًا من القيم الأساسية التي تريد حفظها، يمكنك استخدام واجهات برمجة تطبيقات 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);