حفظ البيانات البسيطة باستخدام 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);