Android Academy · درس

Preferences DataStore

خزّن الإعدادات بصيغة مفتاح-قيمة بطريقة تفاعلية

Preferences DataStore درس مجاني في Android Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Android Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Android Academy 4 دروس في المجموع.

Preferences DataStore

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

يمكنك الوصول إلى القيم من خلال مفاتيح محددة النوع.

إنشاء DataStore

تنشئ مثيلًا واحدًا من DataStore لكل ملف باستخدام property delegate‏ preferencesDataStore في المستوى الأعلى من ملف Kotlin. وتصبح قيمة name اسم الملف على القرص.

import androidx.datastore.preferences.preferencesDataStore
import androidx.datastore.preferences.core.Preferences

val Context.dataStore: DataStore<Preferences> by
    preferencesDataStore(name = "settings")

سبب استخدام Delegate في المستوى الأعلى

يضمن الـ delegate وجود مثيل واحد فقط من DataStore لاسم الملف نفسه ضمن عملية التطبيق. ويؤدي إنشاء مثيلين للملف نفسه إلى طرح خطأ، لأنهما سيتنافسان على البيانات نفسها.

ويؤدي تعريفه باعتباره امتدادًا لـ Context في المستوى الأعلى إلى إبقائه singleton.

مفاتيح التفضيلات

تحتاج كل قيمة إلى مفتاح محدد النوع. إذ يحدد المفتاح اسم الإدخال ونوعه في الوقت نفسه. وتنشئ الدوال المساعدة مفاتيح لكل نوع مدعوم.

import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.intPreferencesKey

val USERNAME = stringPreferencesKey("username")
val DARK_MODE = booleanPreferencesKey("dark_mode")
val LAUNCH_COUNT = intPreferencesKey("launch_count")

أنواع المفاتيح المدعومة

يدعم Preferences DataStore أنواع المفاتيح البدائية التالية:

stringPreferencesKey
booleanPreferencesKey
intPreferencesKey وlongPreferencesKey وfloatPreferencesKey وdoublePreferencesKey
stringSetPreferencesKey

تعريف المفاتيح في مكان واحد

من الأنماط الشائعة جمع جميع المفاتيح داخل object لتسهيل العثور عليها وإعادة استخدامها، وتجنب الأخطاء الإملائية في أسماء السلاسل النصية.

object PrefKeys {
    val USERNAME = stringPreferencesKey("username")
    val DARK_MODE = booleanPreferencesKey("dark_mode")
    val FONT_SIZE = intPreferencesKey("font_size")
}

مفاتيح السلاسل النصية مقابل أسماء المتغيرات

تذكّر أن وسيطة السلسلة النصية، مثل "dark_mode"، هي ما يُكتب على القرص. وإذا أعدت تسميتها لاحقًا، فستصبح القيم القديمة غير قابلة للوصول. أما اسم Kotlin‏ val فهو مخصص لشفرتك فقط.

DataStore واحد لكل مجال

يمكنك إنشاء عدة مثيلات من DataStore لمجالات مختلفة، بحيث يكون لكل منها اسم ملف خاص به؛ مثل مخزن باسم "settings" وآخر باسم "user_session". اجمع المفاتيح المرتبطة معًا.

val Context.settingsStore by preferencesDataStore(name = "settings")
val Context.sessionStore by preferencesDataStore(name = "session")

الوصول من طبقة واجهة المستخدم

على الرغم من أن الـ delegate مرتبط بـ Context، فلا تقرأه مباشرةً في Composables. احقن DataStore في repository، ثم اعرض التدفقات على ViewModel. فهذا يحافظ على قابلية اختبار واجهة المستخدم.

بنية Repository بسيطة

يمنحك تغليف DataStore داخل فئة repository واجهة API واضحة ومكانًا واحدًا لتعريف المفاتيح ومنطق التحويل.

class SettingsRepository(private val dataStore: DataStore<Preferences>) {
    val darkMode: Flow<Boolean> = dataStore.data
        .map { it[PrefKeys.DARK_MODE] ?: false }
}

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

قد لا يكون المفتاح موجودًا بعد، لذلك تُرجع عمليات القراءة null. احرص دائمًا على توفير قيمة افتراضية باستخدام عامل Elvis‏ ?: عند تحويل قيمة تفضيل.

val fontSize: Flow<Int> = dataStore.data
    .map { prefs -> prefs[PrefKeys.FONT_SIZE] ?: 14 }

اختبار سريع

اختبر مدى فهمك لمفاتيح التفضيلات.

مراجعة

لقد أعددت Preferences DataStore:

أنشئ مثيلًا واحدًا باستخدام delegate‏ preferencesDataStore في المستوى الأعلى
عرّف مفاتيح محددة النوع باستخدام stringPreferencesKey وbooleanPreferencesKey وغيرهما
اجمع المفاتيح في object وغلّف الوصول إليها داخل repository
وفّر دائمًا قيمًا افتراضية للمفاتيح المفقودة

بعد ذلك: قراءة هذه الإعدادات وكتابتها فعليًا.

الأسئلة الشائعة

هل درس «Preferences DataStore» مجاني؟

نعم — نص درس «Preferences DataStore» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Android Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Android Academy 4 دروس في المجموع.

ماذا ستتعلم في «Preferences DataStore»؟

خزّن الإعدادات بصيغة مفتاح-قيمة بطريقة تفاعلية تتمرن على Android Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Android Academy؟

لا تُشترط خبرة سابقة. Android Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «Preferences DataStore»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Android Academy هذا؟

نعم. كل درس في Android Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Android Academy