إعداد DataStore لـ KMP

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

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

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

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

تحديد فئات 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(storage: Storage<Preferences>): DataStore<Preferences> =
        DataStoreFactory.create(storage = storage)

internal const val dataStoreFileName = "dice.preferences_pb"

Android

لإنشاء مثيل DataStore على Android، تحتاج إلى Context مع المسار.

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

fun createDataStore(): DataStore<Preferences> = createDataStore(
    storage = FileStorage(
        serializer = PreferencesFileSerializer,
        produceFile = { context.filesDir.resolve(dataStoreFileName) }
    )
)

iOS

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

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

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

الويب

لإنشاء مثيل DataStore على الويب، يمكنك استخدام WebLocalStorage أو WebSessionStorage:

// shared/src/jsMain/kotlin/createDataStore.web.kt (also works for wasmJsMain)

fun createDataStore(): DataStore<Preferences> = createDataStore(
    storage = WebLocalStorage(
        serializer = PreferencesSerializer,
        name = dataStoreFileName
    )
)

‫JVM (أجهزة الكمبيوتر المكتبي)

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

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

fun createDataStore(): DataStore<Preferences> = createDataStore(
    storage = FileStorage(
        serializer = PreferencesFileSerializer,
        produceFile = { File(System.getProperty("java.io.tmpdir"), dataStoreFileName) }
    )
)