为 KMP 设置 DataStore

DataStore 库以异步、一致且事务性的方式存储数据，克服了 SharedPreferences 的一些缺陷。本页重点介绍如何在 Kotlin Multiplatform (KMP) 项目中创建 DataStore。有关 DataStore 的更多信息，请参阅 DataStore 主要文档和官方示例。

设置依赖项

若要在 KMP 项目中设置 DataStore，请将工件依赖项添加到模块的 build.gradle.kts 文件中。

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

定义 DataStore 类

您可以在共享 KMP 模块的通用源码中，使用 DataStoreFactory 定义 DataStore 类。将这些类放置在通用源码中，可以使它们在所有目标平台之间共享。您可以使用 actual 和 expect 声明来创建特定于平台的实现。

创建 DataStore 实例

您需要定义如何在每个平台上实例化 DataStore 对象。由于文件系统 API 存在差异，这是 API 中唯一需要放在特定平台源码集中的部分。

通用 (Common)

// 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

要在 Android 上创建 DataStore 实例，您需要一个 Context 以及路径。

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

fun createDataStore(): DataStore<Preferences> = createDataStore(
    storage = FileStorage(
        serializer = PreferencesSerializer,
        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()
        }
    )
)

Web

要在 Web 上创建 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 (桌面端)

要在 JVM（桌面端）上创建 DataStore 实例，请使用 Java 或 Kotlin API 提供路径。

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

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