為 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 只有這個部分必須位於特定平台來源集中。

通用

// 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()
        }
    )
)

網頁

如要在網頁上建立 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) }
    )
)