إعداد DataStore لـ KMP

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

إعداد التبعيات

لإعداد DataStore في مشروع KMP، أضِف الاعتماديات الخاصة بالعناصر في ملف build.gradle.kts للوحدة:

commonMain.dependencies {
  // DataStore library
  implementation("androidx.datastore:datastore:1.1.7")
  // The Preferences DataStore library
  implementation("androidx.datastore:datastore-preferences:1.1.7")
}

تحديد فئات DataStore

يمكنك تحديد الفئة DataStore باستخدام DataStoreFactory داخل المصدر المشترك لوحدة KMP المشترَكة. يسمح وضع هذه الفئات في مصادر مشتركة بمشاركتها على جميع المنصات المستهدَفة. يمكنك استخدام تعريفات actual وexpect لإنشاء عمليات تنفيذ خاصة بمنصات معيّنة.

إنشاء مثيل DataStore

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

الإعدادات الشائعة

// shared/src/commonMain/kotlin/createDataStore.kt

/**
 *   Gets the singleton DataStore instance, creating it if necessary.
 */
fun createDataStore(producePath: () -> String): DataStore<Preferences> =
        PreferenceDataStoreFactory.createWithPath(
            produceFile = { producePath().toPath() }
        )

internal const val dataStoreFileName = "dice.preferences_pb"

Android

لإنشاء مثيل DataStore على Android، يجب توفُّر Context مع المسار.

// shared/src/androidMain/kotlin/createDataStore.android.kt

fun createDataStore(context: Context): DataStore<Preferences> = createDataStore(
    producePath = { context.filesDir.resolve(dataStoreFileName).absolutePath }
)

iOS

على أجهزة iOS، يمكنك استرداد المسار من NSDocumentDirectory:

// shared/src/iosMain/kotlin/createDataStore.ios.kt

fun createDataStore(): DataStore<Preferences> = createDataStore(
    producePath = {
        val documentDirectory: NSURL? = NSFileManager.defaultManager.URLForDirectory(
            directory = NSDocumentDirectory,
            inDomain = NSUserDomainMask,
            appropriateForURL = null,
            create = false,
            error = null,
        )
        requireNotNull(documentDirectory).path + "/$dataStoreFileName"
    }
)

آلة جافا الافتراضية (على الكمبيوتر)

لإنشاء مثيل DataStore على جهاز JVM (كمبيوتر)، يجب توفير مسار باستخدام واجهات برمجة تطبيقات Java أو Kotlin:

// shared/src/jvmMain/kotlin/createDataStore.desktop.kt

fun createDataStore(): DataStore<Preferences> = createDataStore(
    producePath = {
      val file = File(System.getProperty("java.io.tmpdir"), dataStoreFileName)
      file.absolutePath
    }
)