DataStore

تخزين البيانات بشكل غير متزامن ومتسق ومعاملي، مع التغلب على بعض عيوب SharedPreferences
آخر تعديل الإصدار المستقر إصدار مرشح الإصدار التجريبي الإصدار الأولي
29 تشرين الثاني (نوفمبر) 2023 1.0.0 - - 1.1.0-alpha07

تعريف التبعيات

لإضافة تبعية على DataStore، يجب إضافة مستودع Google Maven إلى مشروعك. يمكنك الاطّلاع على مستودع Maven الذي يضم أدوات Google للحصول على مزيد من المعلومات.

هناك نوعان من عمليات تنفيذ DataStore: الإعدادات المفضّلة والنموذج الأوّلي. اختَر أحد الخيارَين. يمكنك أيضًا إضافة تبعيات خالية من Android إلى أي من التنفيذ.

أضِف التبعيات للتنفيذ الذي تحتاجه في ملف build.gradle لتطبيقك أو الوحدة:

الإعدادات المفضّلة DataStore

رائع

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.0.0"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.0.0"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.0.0"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.0.0"
    }

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.0.0")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.0.0")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.0.0")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.0.0")
    }

Proto DataStore

رائع

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.0.0"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.0.0"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.0.0"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.0.0"
    }

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.0.0")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.0.0")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.0.0")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.0.0")
    }

ملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إخبارنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مشكلة جديدة. يمكنك إضافة تصويتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء عدد جديد

راجع مستندات أداة تتبُّع المشاكل للحصول على مزيد من المعلومات.

الإصدار 1.1

الإصدار 1.1.0-alpha07

29 تشرين الثاني (نوفمبر) 2023

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha07". يحتوي الإصدار 1.1.0-alpha07 على هذه الالتزامات.

تغييرات واجهة برمجة التطبيقات

  • عليك إزالة تعليقات @ExperimentalMultiProcessDataStore التوضيحية للتأكّد من أنّ طُرق MultiProcessDataStoreFactory لم تعُد تجريبية. (Ieee54)

إصلاح الأخطاء

  • طرح خيار إزالة تعليقات @ExperimentalMultiProcessDataStore التوضيحية في الإصدار 1.1.0-alpha07. (I8e607)

الإصدار 1.1.0-alpha06

1 تشرين الثاني (نوفمبر) 2023

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha06". يحتوي الإصدار 1.1.0-alpha06 على هذه الالتزامات.

تغييرات واجهة برمجة التطبيقات

  • تتلقّى الآن طريقة المصنع في createSingleProcessCoordinator مسار ملف (String وjava.io.File وokio.Path) لتكون متوافقة مع createMultiProcessCoordinator. (I211c8، b/305755935)

الإصدار 1.1.0-alpha05

6 أيلول (سبتمبر) 2023

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha05". يحتوي الإصدار 1.1.0-alpha05 على هذه الالتزامات.

تغييرات واجهة برمجة التطبيقات

  • أصبح مخزن البيانات FileStorage متاحًا للجميع الآن، لذا يمكن للعملاء توفير مَعلمات مخصّصة. (Icb985)
  • تم تغيير الدالة الإنشائية OkioStorage لقبول InterProcessCoordinator بحيث يمكن استخدامها على Android مع MultiProcessCoordinator. (Iecea3)

إصلاح الأخطاء

  • إصلاح MultiProcessCoordinator تعذُّر مراقبة عدة ملفات في الدليل نفسه
  • إصلاح تعذُّر رصد الملفات المكرّرة في حال عدم تسوية مسارات الملفات
  • أصلِح القيم الخاطئة التي تم إرجاعها من RxDataStore#isDisposed.
  • إصلاح إعدادات Proguard غير المتوفّرة لعنصر datstore-preferences-core.

الإصدار 1.1.0-alpha04

5 نيسان (أبريل) 2023

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha04". يحتوي الإصدار 1.1.0-alpha04 على هذه الالتزامات.

إصلاح الأخطاء

  • يمكنك تحسين عملية التنفيذ الداخلية لتجنُّب حدوث مشكلة متعلّقة بالسباق قد ينتج من تدفق بيانات DataStore قيمة قديمة بعد إجراء تحديث.

الإصدار 1.1.0-alpha03

24 آذار (مارس) 2023

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha03".

إصلاح الأخطاء

  • تمت إزالة قيود التبعية من عناصر Maven لحل مشكلة إنشاء في Kotlin Native Targets (b/274786186، KT-57531).

الإصدار 1.1.0-alpha02

22 آذار (مارس) 2023

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha02". يحتوي الإصدار 1.1.0-alpha02 على هذه الالتزامات.

ملاحظة

تجدر الإشارة إلى أنّ هذا الإصدار يتضمّن عملية إعادة هيكلة داخلية مهمة تدمج عمليات التنفيذ لعمليات تنفيذ DataStore على مستوى العمليات الفردية ومتعددة العمليات. يُرجى مراقبة التغييرات المحتملة في السلوك غير المقصود (على سبيل المثال، توقيت إشعارات التعديلات). يمكنك استخدام مكوِّن أداة تتبُّع المشاكل للإبلاغ عن هذه التغييرات.

الميزات الجديدة

  • يمكنك الآن استخدام DataStore في مشاريع KMM. تجدر الإشارة إلى أنّ استهدافات DataStore التي لا تعمل بنظام التشغيل Android ما زالت في مرحلة تجريبية، ولكنّنا قرّرنا دمج الإصدارات لتسهيل تجربة المطوّرين عليها.
  • تم نقل الميزات المتعددة العمليات من androidx.datastore.multiprocess إلى androidx.datastore.core.
  • يمكنك إضافة طريقة جديدة على الإعدادات الأصلية في androidx.datastore.core.MultiProcessDataStoreFactory لإنشاء مثيلات DataStore باستخدام عناصر Storage لمعالجة الملفات.
  • يمكنك إضافة واجهة InterProcessCoordinator جديدة تساعد مثيلات DataStore متعددة في التواصل عبر العمليات. يُرجى العلم أنّ تنفيذ InterProcessCoordinator في عمليات متعددة متوفّرة على نظام التشغيل Android فقط.

تغييرات واجهة برمجة التطبيقات

  • إضافة InterProcessCoordinator إلى StorageConnection في واجهة مخزن البيانات الأساسية (I555bb)
  • عليك تغيير واجهات برمجة التطبيقات في MultiProcessDataStoreFactory الخاص بمخزن البيانات الأساسي لاستخدام مساحة التخزين. (Iac02f)
  • نقل واجهات برمجة التطبيقات العامة في عملية تخزين البيانات المتعددة العمليات إلى وحدة مخزن البيانات الأساسية (I76d7c)
  • تم الكشف عن PreferencesSerializer من datastore-preferences-core (I4b788).
  • إضافة تعليق @JvmDefaultWithCompatibility التوضيحي (I8f206)

الإصدار 1.1.0-alpha01

تشرين الثاني (نوفمبر) 2022

تم إصدار "androidx.datastore:datastore-*:1.1.0-alpha01". يحتوي الإصدار 1.1.0-alpha01 على هذه الالتزامات.

الميزات الجديدة

  • دعم حالات الاستخدام متعدد العمليات التي يتم فيها ضمان اتساق البيانات بين DataStore مثيل في جميع العمليات يُرجى إضافة MultiProcessDataStoreFactory#create لإنشاء DataStore مثيل.
  • واجهة مساحة تخزين جديدة تسمح بالتبديل إلى آلية التخزين الأساسية لـ Datastore يتم توفير عمليات تنفيذ لـ java.io وokio. تتضمن مصانع DataStore طرقًا جديدة تقبل عنصر التخزين هذا.

تغييرات واجهة برمجة التطبيقات

  • عليك تغيير واجهات برمجة التطبيقات في MultiProcessDataStoreFactory الخاص بمخزن البيانات الأساسي لاستخدام مساحة التخزين. (Iac02f)
  • نقل واجهات برمجة التطبيقات العامة في عملية تخزين البيانات المتعددة العمليات إلى وحدة مخزن البيانات الأساسية (I76d7c)
  • تم الكشف عن PreferencesSerializer من datastore-preferences-core (I4b788).

الإصدار 1.0.0

الإصدار 1.0.0

4 آب (أغسطس) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0". يحتوي الإصدار 1.0.0 على هذه الالتزامات.

الميزات الرئيسية للإصدار 1.0.0

إنّ Jetpack DataStore هو حلّ لتخزين البيانات يسمح لك بتخزين أزواج المفتاح/القيمة أو العناصر المكتوبة باستخدام مخازن البروتوكولات المؤقتة. يستخدم DataStore الكوروتينات والتدفق في لغة Kotlin لتخزين البيانات بشكلٍ غير متزامن ومتسق وإجراء المعاملات.

الإصدار 1.0.0-rc02

21 تموز (يوليو) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-rc02". يحتوي الإصدار 1.0.0-rc02 على هذه الالتزامات.

إصلاح الأخطاء

  • وضِّح له أنّه لا يتم تشغيل "SharedPreferencesMigration" إذا لم تكن هناك مفاتيح. (Icfa32، b/192824325)
  • إصلاح الخطأ الذي يؤدي فيه إنشاء SharedPreferencesMigration باستخدام MIGRATE_ALL_KEYS إلى إنشاء استثناء إذا لم يكن المفتاح المطلوب متوفرًا بعد. (Ie318a، b/192824325)

الإصدار 1.0.0-rc01

30 حزيران (يونيو) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-rc01". يحتوي الإصدار 1.0.0-rc01 على هذه الالتزامات.

إصلاح الأخطاء

  • إصلاح الخطأ المتمثل في إضافة ملف .java عن غير قصد إلى الوعاء النهائي (I65d96 ، b/188985637)

الإصدار 1.0.0-beta02

16 حزيران (يونيو) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-beta02". يتضمّن الإصدار 1.0.0-beta02 هذه الالتزامات.

إصلاح الأخطاء

الإصدار 1.0.0-beta01

21 نيسان (أبريل) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-beta01". يتضمّن الإصدار 1.0.0-beta01 هذه الالتزامات.

تغييرات واجهة برمجة التطبيقات

  • إزالة أعباء JavaScript الإضافية لطرق Kotlin فقط (I2adc7)

إصلاح الأخطاء

  • تم إصلاح الخطأ الذي قد يتسبب في أن يؤدي المفوَّضون في مخزن البيانات إلى تسريب السياقات (Ie96fc، b/184415662)

الإصدار 1.0.0-alpha08

10 آذار (مارس) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-alpha08". يحتوي الإصدار 1.0.0-alpha08 على هذه الالتزامات.

تغييرات واجهة برمجة التطبيقات

  • يمكنك الآن إضافة عملية نقل بيانات تعتمد على السياق إلى تفويض موقعك الإلكتروني على dataStore وpreferencesDataStore. (I4ef69، b/173726702)
  • تتم إضافة الدوال المساعدة للحصول على اسم الملف إذا لم تعُد تستخدم تفويض تخزين البيانات أوcontext.createDataStore (I60f9a).
  • يتم التعليق الآن في Serializer writeTo وreadFrom. إذا تم تنفيذ Serializer، ستحتاج إلى تحديث الدوال لتعليق الدوال. (I1e58e)
  • تمت إضافة تفويضات الموقع لمستخدمي RxDataStore. (Ied768، b/173726702)

إصلاح الأخطاء

  • فرض قيود على الاستخدام العام لواجهات برمجة التطبيقات التجريبية (I6aa29، b/174531520)

الإصدار 1.0.0-alpha07

24 شباط (فبراير) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-alpha07". يحتوي الإصدار 1.0.0-alpha07 على هذه الالتزامات.

تغييرات واجهة برمجة التطبيقات

  • تمت إزالة وظيفة الإضافة "Context.createDataStore" واستبدالها بتفويض الموقع على GlobalDataStore. يمكنك طلب GlobalDataStore مرة واحدة في المستوى الأعلى في ملف Kotlin. مثلاً:

    val Context.myDataStore by dataStore(...)

    ضع هذا في المستوى الأعلى من ملف kotlin حتى لا يكون هناك سوى مثيل واحد منه. (I57215، b/173726702)

  • تتوفّر دوال RxDataStore الآن ضمن فئة RxDataStore بدلاً من دوال الإضافات في DataStore. (Idccdb، b/177691248)

  • إذا كنت تريد نقل EncryptedSharedPreferences (أو "التمهيد المشترك للأدلّة المشتركة") إلى DataStore، يمكنك الآن إجراء ذلك باستخدام الدالة الإنشائية الجديدة لـ SharedPreferencesMigrate التي تتيح لك إدخال "SharedPreferences". (I8e04e، b/177278510)

إصلاح الأخطاء

  • سيطرح DataStore الآن استثناء إذا كان هناك العديد من مستودعات البيانات النشطة للملف نفسه. إذا لم تكن تدير DataStore على أنّه مفرد أو لم تكن تضمن عدم تنشيط أي مثيلين من DataStore في آنٍ واحد لملف، قد تظهر لك الآن استثناءات عند القراءة أو الكتابة إلى DataStore. ويمكن حلّ هذه المشاكل من خلال إدارة DataStore على أنّه كائن مفرد. (Ib43f4، b/177691248)
  • إصلاح سلوك الإلغاء عند إلغاء نطاق المتصل. (I2c7b3)

الإصدار 1.0.0-alpha06

13 كانون الثاني (يناير) 2021

تم إصدار "androidx.datastore:datastore-*:1.0.0-alpha06". يحتوي الإصدار 1.0.0-alpha06 على هذه الالتزامات.

الميزات الجديدة

  • تمت إضافة برامج تضمين RxJava لتطبيق DataStore. تحتوي عناصر datastore-rxjava2/3 على برامج تضمين لواجهات برمجة تطبيقات DataStore API الأساسية (RxDataStore وRxDataStoreBuilder وRxDataMigration). تحتوي عناصر datastore-preferences-rxjava2/3 على أداة إنشاء لإنشاء واجهة برمجة تطبيقات الإعدادات المفضّلة.

تغييرات واجهة برمجة التطبيقات

  • إخفاء واجهة CorruptionHandler. لم يكن هناك سبب ليكون متاحًا للجميع لأنّ مصنع DataStore لا يقبل إلا نوعReplaceFileCorruptionHandler. (I0b3b3، b/176032264)
  • تمت إزالة طريقة preferencesKey<T>(name: String): Key<T> واستبدالها بطرق خاصة بكل نوع متوافق، على سبيل المثال preferencesKey<Int>("int") أصبح الآن intPreferencesKey("int") (Ibcfac، b/170311106).

إصلاح الأخطاء

  • إصلاح المستندات الموجودة في DataStoreلقد لم يتم إنشاء ملف مخزن البيانات في الدليل الفرعي "datastore/ ". (Ica222)

الإصدار 1.0.0-alpha05

2 كانون الأول (ديسمبر) 2020

تم إصدار "androidx.datastore:datastore-*:1.0.0-alpha05". يحتوي الإصدار 1.0.0-alpha05 على هذه الالتزامات.

إصلاح الأخطاء

  • يمكنك إضافة وثائق واستثناءات أفضل حول عمليات الكتابة المتزامنة من مخزن البيانات. (Ia98a2، b/173522155، b/173726702)
  • نسمح الآن (ولكن لا نطلب ذلك) بإغلاق OUTStream التي تم تمريرها إلى Serializer.writeTo(). (I5c9bf، b/173037611)

الإصدار 1.0.0-alpha04

17 تشرين الثاني (نوفمبر) 2020

تم إصدار "androidx.datastore:datastore-*:1.0.0-alpha04". يحتوي الإصدار 1.0.0-alpha04 على هذه الالتزامات.

إصلاح الأخطاء

  • تم إصلاح مشكلة في حزم البيانات تؤدي إلى حدوث العطل التالي في التفضيلات في مخزن البيانات 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

الإصدار 1.0.0-alpha03

11 تشرين الثاني (نوفمبر) 2020

تم إصدار "androidx.datastore:datastore-*:1.0.0-alpha03". يحتوي الإصدار 1.0.0-alpha03 على هذه الالتزامات.

الميزات الجديدة

  • تتوافق الإعدادات المفضّلة الآن مع القيم المزدوجة (وهو أمر مفيد إذا كنت بحاجة إلى دقة أكبر من القيم العشرية) (I5be8f ، b/169471808)

تغييرات واجهة برمجة التطبيقات

  • تم إنشاء تبعية تامة للغة Kotlin لمخزن البيانات للسماح بالتجميع بشكل أسرع. يحتوي androidx.datastore:datastore-core على واجهات برمجة التطبيقات الأساسية فقط في لغة kotlin، بينما يحتوي androidx.datastore:datastore على واجهات برمجة التطبيقات التي تعتمد على Android (بما في ذلك SharedPreferencesMigration والأداة الإنشائية Context.createDataStore.)(I42d75، b/168512698)
  • تقسيم الأهداف لتخزين بيانات الإعدادات المفضّلة لتجميع بيانات لغة البرمجة Kotlin بشكل أسرع (Ia3c19)

  • تتطلب برامج التسلسل الآن خاصية جديدة للقيمة التلقائية التي سيتم استخدامها في حال عدم وجود بيانات على القرص. يسهّل ذلك تنفيذ التسلسلات المخصّصة بحيث لا يضطر المستخدمون إلى استخدام ساحات مشاركات إدخال فارغة بحالة خاصة (لا يتم تحليل ساحات المشاركات الفارغة باستخدام تنسيق json).

    • كما تتوفر الآن عملية تحقق للتأكد من أن ساحة مشاركات الإخراج المقدمة إلى writeTo() لم يتم إغلاقها، وإذا تم إغلاقها، ستظهر استثناءات (I16e29).

  • إنشاء الدالة الإنشائية لـ SharedPreferencesView الداخلية. وقد كان متاحًا للجميع في الأصل للسماح بالاختبار. بدلاً من ذلك، يجب على الاختبارات إنشاء SharedPreferences Migration وإجراء اختبار وفقًا لذلك. (I93891)

إصلاح الأخطاء

  • المعلمة produceFile في DataStoreFactory وPreferenceDataStoreFactory هي الآن المعلمة الأخيرة في القائمة، لذلك فهي تتيح لك استخدام بنية lambda اللاحقة kotlin. (Ibe7f1، b/169425442)
  • اتّباع المتطلبات الصريحة الجديدة لواجهة برمجة التطبيقات في لغة kotlin (I5ae1e)

المشاكل المعروفة

  • تعطُّل التفضيلات في مخزن البيانات في java.lang.NoClassDefFoundError (b/173036843)

الإصدار 1.0.0-alpha02

14 تشرين الأول (أكتوبر) 2020

تم إصدار androidx.datastore:datastore-core:1.0.0-alpha02 وandroidx.datastore:datastore-preferences:1.0.0-alpha02. يحتوي الإصدار 1.0.0-alpha02 على هذه الالتزامات.

إصلاح الأخطاء

  • تمت إضافة حماية من التغيير في البيانات الأساسية لمخزن البيانات. تغيير يعطّل استخدام مخزن البيانات للأشخاص الذين يستخدمون مخزن البيانات بأنواع غير أولية/غير تفضيلات (I6aa84)
  • تمت إضافة طريقة toString إلى Preferences.kt لتسهيل تصحيح أخطاء الحالة الحالية (I96006).
  • تمت إضافة استثناء للحماية من إساءة استخدام DataStore.Preferences (I1134d)
  • تم إصلاح الخطأ الذي قد يتسبب في تعطُّل التطبيق عند بدء التشغيل (I69237، b/168580258)

الإصدار 1.0.0-alpha01

2 أيلول (سبتمبر) 2020

تم إصدار androidx.datastore:datastore-core:1.0.0-alpha01 وandroidx.datastore:datastore-preferences:1.0.0-alpha01. يحتوي الإصدار 1.0.0-alpha01 على هذه الالتزامات.

الميزات الجديدة

إنّ Jetpack DataStore هو حلّ جديد ومحسّن لتخزين البيانات يهدف إلى استبدال "الإعدادات المفضّلة المشتركة". ويستند DataStore إلى الكوروتينات والتدفق في لغة Kotlin، ويقدّم تطبيقَين مختلفَين:

  • Proto DataStore، الذي يتيح لك تخزين الكائنات المكتوبة (بتنسيق مخازن مؤقتة للبروتوكول)
  • التفضيلات DataStore، الذي يخزِّن أزواج المفتاح/القيمة

يتم تخزين البيانات على نحو غير متزامن وبشكل متسق ومعاملي، مما يؤدي إلى التغلب على معظم عيوب SharedPreferences.