استخدام قيم "الإعدادات المفضّلة" المحفوظة جزء من Android Jetpack.

توضح هذه الوثيقة كيفية تخزين واستخدام قيم Preference المحفوظة من خلال مكتبة التفضيلات.

تخزين البيانات كتفضيل

يوضّح هذا القسم كيفية احتفاظ Preference بالبيانات.

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

بشكل تلقائي، يستخدم Preference وفِّر SharedPreferences القيم. SharedPreferences API تتيح قراءة النصوص وكتابتها بسهولة أزواج المفتاح/القيمة من ملف يتم حفظه في جلسات التطبيق. تشير رسالة الأشكال البيانية تستخدم مكتبة الإعدادات المفضّلة مثيل SharedPreferences خاصًا بحيث لا يتم الوصول إليها.

لنفترض مثلًا أن ما يلي: SwitchPreferenceCompat:

<SwitchPreferenceCompat
        app:key="notifications"
        app:title="Enable message notifications"/>

عندما يبدِّل المستخدم مفتاح التبديل هذا إلى "تفعيل" الحالة، ملف SharedPreferences باستخدام زوج المفتاح/القيمة "notifications" : "true". المفتاح المستخدم هو نفس مجموعة المفاتيح لـ Preference.

لمزيد من المعلومات حول واجهة برمجة تطبيقات SharedPreferences، يمكنك الاطّلاع على حفظ قيمة المفتاح.

للحصول على معلومات حول الطرق المختلفة لتخزين البيانات على Android، يُرجى الاطّلاع على البيانات. ونظرة عامة على تخزين الملفات.

متجر PreferenceDataStore

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

PreferenceDataStore يتيح لك استخدام خلفية مساحة تخزين مخصّصة للاحتفاظ بقيم Preference. لمزيد من المعلومات، معلومات، يُرجى الاطّلاع على استخدام مخزن بيانات مخصَّص.

قراءة القيم المفضَّلة

لاسترداد كائن SharedPreferences المستخدم، يمكنك استدعاء دالة الرسم PreferenceManager.getDefaultSharedPreferences() على الرغم من أنّ هذه الطريقة تعمل من أي مكان في تطبيقك، نقترح عليك ما يلي: تقوم بتقسيم التطبيق إلى طبقات. لمزيد من المعلومات، راجع البيانات .

على سبيل المثال، إذا كان الرمز EditTextPreference مع مفتاح "signature"، على النحو التالي: التالي:

<EditTextPreference
        app:key="signature"
        app:title="Your signature"/>

يمكنك استرداد القيمة المحفوظة لهذه Preference في جميع أنحاء العالم، كما يلي:

Kotlin

val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(this /* Activity context */)
val name = sharedPreferences.getString("signature", "")

Java

SharedPreferences sharedPreferences =
        PreferenceManager.getDefaultSharedPreferences(this /* Activity context */);
String name = sharedPreferences.getString("signature", "");

معرفة التغييرات في قيم التفضيلات

للاستماع إلى التغييرات في قيم Preference، يمكنك الاختيار بين قيمتين. الواجهات:

• Preference.OnPreferenceChangeListener
• SharedPreferences.OnSharedPreferenceChangeListener

يوضّح الجدول التالي مدى اختلاف الواجهتين:

OnPreferenceChangeListener	OnSharedPreferenceChangeListener
الضبط على Preference واحد	ينطبق هذا الإعداد على كل العناصر البالغ عددها Preference.
يتم استدعاء هذه الدالة عندما تكون قيمة Preference على وشك تغيير القيمة المحفوظة، حتى إذا كانت القيمة في انتظار المراجعة مماثلة للقيمة المحفوظة	لا يتم استدعاء هذا الإجراء إلا عند تغيير القيمة المحفوظة في Preference.
تم طلبها فقط من خلال مكتبة Preference. جزء منفصل للتطبيق تغيير القيمة المحفوظة.	يتم استدعاء هذا الإجراء عند تغيير القيمة المحفوظة، حتى إذا كانت من قيمة من التطبيق.
تم استدعاء هذه الدالة قبل حفظ القيمة في انتظار المراجعة.	يتم طلبه بعد حفظ القيمة.
يتم الاتصال به عند استخدام SharedPreferences أو PreferenceDataStore	لا يتم الاتصال به إلا عند استخدام "SharedPreferences".

تنفيذ OnPreferenceChangeListener

يتيح تنفيذ OnPreferenceChangeListener إمكانية الاستماع إلى حالة "في انتظار المراجعة" للتغيير إلى قيمة Preference. بعد ذلك، يمكنك التحقق مما إذا كان التغيير تحدث المقابلة. على سبيل المثال، يوضح الرمز التالي كيفية الاستماع إلى تغيير في قيمة EditTextPreference مع مفتاح "name":

Kotlin

override fun onPreferenceChange(preference: Preference, newValue: Any): Boolean {
    Log.e("preference", "Pending Preference value is: $newValue")
    return true
}

Java

@Override
public boolean onPreferenceChange(Preference preference, Object newValue) {
    Log.e("preference", "Pending Preference value is: " + newValue);
    return true;
}

بعد ذلك، عليك ضبط هذا المستمع مباشرةً setOnPreferenceChangeListener()، على النحو التالي:

Kotlin

preference.onPreferenceChangeListener = ...

Java

preference.setOnPreferenceChangeListener(...);

تنفيذ OnSharedPreferenceChangeListener

عند الاحتفاظ بقيم Preference باستخدام SharedPreferences، يمكنك أيضًا استخدام SharedPreferences.OnSharedPreferenceChangeListener للاستماع إلى التغييرات. ويتيح لك ذلك الانتباه إلى وقت تغيير القيم المحفوظة من خلال Preference، مثل مزامنة الإعدادات مع خادم. يوضح المثال التالي كيفية الاستماع إلى التغيّر في قيمة EditTextPreference باستخدام مفتاح "name":

Kotlin

override fun onSharedPreferenceChanged(sharedPreferences: SharedPreferences, key: String) {
    if (key == "signature") {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""))
    }
}

Java

@Override
public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    if (key.equals("signature")) {
        Log.i(TAG, "Preference value was updated to: " + sharedPreferences.getString(key, ""));
    }
}

تسجيل المستمع باستخدام registerOnSharedPreferenceChangedListener()، على النحو التالي:

Kotlin

preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(...)

Java

getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(...);

تحذير: لمنع جمع البيانات غير المقصودة، يمكنك تخزين إشارة قوية إلى المستمع. عند الاتصال بـ registerOnSharedPreferenceChangeListener()، لا يخزِّن SharedPreferenceManager إشارة قوية إلى المستمع. إلى يمكنك حلّ هذه المشكلة، يمكنك تنفيذ onSharedPreferenceChanged() مباشرةً في PreferenceFragmentCompat يمكنك أيضًا إنشاء متغير مثيل، كما هو موضح في المثال التالي:

Kotlin

    val listener: SharedPreferences.OnSharedPreferenceChangeListener =
            SharedPreferences.OnSharedPreferenceChangeListener {...}
    

Java

    SharedPreferences.OnSharedPreferenceChangeListener listener =
            new SharedPreferences.OnSharedPreferenceChangeListener() {...}
    

لإدارة مراحل النشاط في Activity أو Fragment بشكل سليم، يُرجى التسجيل إلغاء تسجيل المستمع هذا في استدعاءات onResume() وonPause()، كما هو موضح في المثال التالي:

Kotlin

override fun onResume() {
    super.onResume()
    preferenceManager.sharedPreferences.registerOnSharedPreferenceChangeListener(this)
}

override fun onPause() {
    super.onPause()
    preferenceManager.sharedPreferences.unregisterOnSharedPreferenceChangeListener(this)
}

Java

@Override
public void onResume() {
    super.onResume();
    getPreferenceManager().getSharedPreferences().registerOnSharedPreferenceChangeListener(this);
}

@Override
public void onPause() {
    super.onPause();
    getPreferenceManager().getSharedPreferences().unregisterOnSharedPreferenceChangeListener(this);
}

استخدام مخزن بيانات مخصص

مع أنّنا ننصح بالاحتفاظ بكائنات Preference باستخدام SharedPreferences، يمكنك أيضًا استخدام مخزن بيانات مخصص. يمكن أن يكون مخزن البيانات المخصص مفيدًا إذا كان التطبيق يحتفظ بالقيم في قاعدة بيانات أو إذا كانت القيم خاصة بالجهاز، كما هو موضح في الأمثلة التالية.

تنفيذ ملف تخزين البيانات

لتنفيذ مخزن بيانات مخصص، يمكنك إنشاء فئة تمتد PreferenceDataStore ينشئ المثال التالي مخزن بيانات يتعامل مع قيم String:

Kotlin

class DataStore : PreferenceDataStore() {
    override fun putString(key: String, value: String?) {
        // Save the value somewhere.
    }

    override fun getString(key: String, defValue: String?): String? {
        // Retrieve the value.
    }
}

Java

public class DataStore extends PreferenceDataStore {
    @Override
    public void putString(String key, @Nullable String value) {
        // Save the value somewhere.
    }
    @Override
    @Nullable
    public String getString(String key, @Nullable String defValue) {
        // Retrieve the value.
    }
}

ملاحظة: يمكنك إلغاء الطرق المستخدَمة فقط في كائنات Preference. إجراء المكالمات طريقة لم تنفذ نتائج في UnsupportedOperationException.

تنفيذ أي عمليات تستغرق وقتًا طويلاً خارج سلسلة التعليمات الرئيسية لتجنّب حظر المستخدم من واجهة pyplot. لأنّه من الممكن أن تحتوي السمة Fragment أو Activity على إتلاف مخزن البيانات أثناء الاحتفاظ بقيمة، فقم بنشر البيانات بشكل تسلسلي لا تفقد أي قيم غيرها المستخدم.

تفعيل مخزن البيانات

بعد تنفيذ مخزن البيانات، تعيين مخزن البيانات الجديد في onCreatePreferences() بحيث تحتفظ كائنات Preference بالقيم مع مخزن البيانات بدلاً من استخدام SharedPreferences التلقائي. يمكنك تمكين مخزن البيانات لكل Preference أو للتسلسل الهرمي بالكامل.

لتفعيل مخزن بيانات مخصّص لجهاز Preference محدّد، يُرجى الاتصال setPreferenceDataStore() في Preference، كما هو موضَّح في المثال التالي:

Kotlin

val preference: Preference? = findPreference("key")
preference?.preferenceDataStore = dataStore

Java

Preference preference = findPreference("key");
if (preference != null) {
    preference.setPreferenceDataStore(dataStore);
}

لتفعيل مخزن بيانات مخصص للتسلسل الهرمي بالكامل، اتصل setPreferenceDataStore() على PreferenceManager:

Kotlin

val preferenceManager = preferenceManager
preferenceManager.preferenceDataStore = dataStore

Java

PreferenceManager preferenceManager = getPreferenceManager();
preferenceManager.setPreferenceDataStore(dataStore);

إنّ مخزن البيانات الذي تم ضبطه على عنصر Preference محدّد يلغي أي مخزن بيانات يتم تعيينها للتسلسل الهرمي المقابل. في معظم الحالات، تقوم بتعيين مخزن بيانات التسلسل الهرمي بالكامل.

ملاحظة: إذا ضبطت مخزن بيانات لـ Preference بعد Preference مرفقة بالتسلسل الهرمي، فإن القيمة الأولية لـ Preference ليست مرة أخرى.