DataStore (Kotlin Multiplatform)

تخزِّن مكتبة 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
    }
)