Android Academy · درس

Proto DataStore

خزّن البيانات المهيكلة محددة النوع

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

Proto DataStore

يخزّن Proto DataStore كائنات منظمة محددة النوع بدلًا من أزواج مفتاح وقيمة غير مقيّدة. وتعرّف مخططًا، ثم يخزّن DataStore كائنًا واحدًا محدد النوع لكل ملف.

وهو مثالي عندما تشكّل إعداداتك نموذجًا مترابطًا.

سبب استخدام البيانات محددة النوع

إن Preferences DataStore غير محدد النوع؛ فالخطأ الإملائي في مفتاح أو قراءة النوع الخاطئ لا يفشلان إلا أثناء التشغيل. أما Proto DataStore فيمنحك أمان الأنواع في وقت الترجمة لكائن الإعدادات بأكمله.

لا توجد مفاتيح نصية يمكن كتابة أسمائها خطأً
تُعرّف القيم الافتراضية في المخطط
حقول يسهل إعادة هيكلتها

اختيار تنسيق Serializer

يستخدم الأسلوب التقليدي Protocol Buffers ‏(proto) لتعريف المخطط. ويمكنك أيضًا إجراء التسلسل باستخدام kotlinx.serialization أو أي تنسيق مخصص. ويصف المخطط الحقول وأنواعها.

تعريف مخطط Proto

تكتب ملف .proto يصف رسالة إعداداتك. وينشئ مترجم protobuf فئة Kotlin/Java منه.

syntax = "proto3";

option java_package = "com.example.app";
option java_multiple_files = true;

message UserSettings {
  bool dark_mode = 1;
  int32 font_size = 2;
  string username = 3;
}

تنفيذ Serializer

يحتاج DataStore إلى Serializer يعرف كيفية قراءة نوعك وكتابته إلى تدفق، بالإضافة إلى defaultValue تُستخدم عندما يكون الملف فارغًا.

object UserSettingsSerializer : Serializer<UserSettings> {
    override val defaultValue: UserSettings = UserSettings.getDefaultInstance()

    override suspend fun readFrom(input: InputStream): UserSettings =
        UserSettings.parseFrom(input)

    override suspend fun writeTo(t: UserSettings, output: OutputStream) =
        t.writeTo(output)
}

إنشاء Proto DataStore

استخدم delegate‏ dataStore، وليس preferencesDataStore، مع تمرير اسم الملف وSerializer الخاص بك.

val Context.settingsStore: DataStore<UserSettings> by dataStore(
    fileName = "user_settings.pb",
    serializer = UserSettingsSerializer
)

قراءة البيانات محددة النوع

تتم عمليات القراءة عبر settingsStore.data، لكن نوع التدفق الآن هو نوع النموذج الخاص بك. لا مفاتيح ولا تحويل للأنواع؛ بل يمكنك الوصول إلى الحقول مباشرةً.

val darkMode: Flow<Boolean> = context.settingsStore.data
    .map { settings -> settings.darkMode }

الكتابة باستخدام updateData

يستبدل Proto DataStore‏ edit بدالة suspend‏ updateData. تحصل على الكائن الحالي وتُرجع كائنًا جديدًا. ومع protobuf، تستخدم الـ builder الذي تم إنشاؤه.

suspend fun setDarkMode(enabled: Boolean) {
    context.settingsStore.updateData { current ->
        current.toBuilder()
            .setDarkMode(enabled)
            .build()
    }
}

التحديثات غير القابلة للتغيير

لاحظ أنك لا تعدّل الكائن الموجود مطلقًا؛ بل تنشئ كائنًا جديدًا وتُرجعه. وهذه اللا قابلية للتغيير هي ما يجعل التحديثات ذرية ومتسقة لدى جميع المراقبين.

معالجة تلف البيانات

إذا أصبح الملف المخزّن غير قابل للقراءة، يطرح DataStore‏ CorruptionException. ويمكنك توفير corruptionHandler يعيد قيمة افتراضية آمنة بدلًا من تعطل التطبيق.

val Context.settingsStore by dataStore(
    fileName = "user_settings.pb",
    serializer = UserSettingsSerializer,
    corruptionHandler = ReplaceFileCorruptionHandler {
        UserSettings.getDefaultInstance()
    }
)

Preferences مقابل Proto

اختر بناءً على احتياجاتك:

Preferences: عدة علامات غير مرتبطة، إعداد سريع، ومن دون مخطط
Proto: نموذج إعدادات منظم، وأمان للأنواع، وقيم افتراضية محددة

يشترك كلاهما في الأساس غير المتزامن والمعاملاتي والقائم على Flow.

اختبار سريع

اختبر مدى فهمك لـ Proto DataStore.

مراجعة

تعلّمت تخزين البيانات محددة النوع باستخدام Proto DataStore:

عرّف مخططًا، غالبًا باستخدام Protocol Buffers
نفّذ Serializer مع defaultValue
أنشئ المخزن عبر delegate‏ dataStore
اقرأ الحقول مباشرةً، واكتب باستخدام updateData
عالج التلف باستخدام معالج يعيد قيمة افتراضية

لقد أتممت دورة DataStore.

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

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

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

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

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

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

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

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

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

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

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

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

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