原生移动开发 / 系统课时

Preferences DataStore

Preferences DataStore

Preferences DataStore 适合保存主题、通知开关、排序方式等少量键值偏好。它用协程完成异步写入,并以 Flow 暴露持续变化的数据。本课完成一个可运行的设置仓库:写入深色模式和主题值,再从同一数据流读取并验证结果。

学习目标

  • 能创建单例 Preferences DataStore 并定义类型匹配的键
  • 能使用 data 与 edit 完成异步读取和事务式更新
  • 能判断哪些数据不应该放进 Preferences DataStore

添加依赖并创建唯一实例

在应用模块的 build.gradle.kts 中加入稳定版 Preferences DataStore 依赖:

kotlin
dependencies {
    implementation("androidx.datastore:datastore-preferences:1.2.1")
}

Gradle 同步成功后,项目即可使用 preferencesDataStore、Preferences 与各种 *PreferencesKey API。对同一个文件名,应在同一进程中只创建一个 DataStore 实例;最简单的方式是在 Kotlin 文件顶层声明属性委托。

用一个仓库封装读写

下面示例假设项目已有标准 AndroidX Activity 与 Lifecycle 依赖。settingsDataStore 是整个应用共享的入口,仓库把磁盘中的键值映射为业务对象,并把写入集中在挂起函数中。

kotlin
package com.example.datastore

import android.content.Context
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.launch

val Context.settingsDataStore: DataStore<Preferences> by preferencesDataStore(
    name = "settings"
)

data class UserSettings(
    val darkMode: Boolean,
    val theme: String
)

class SettingsRepository(private val context: Context) {
    private object Keys {
        val darkMode = booleanPreferencesKey("dark_mode")
        val theme = stringPreferencesKey("theme")
    }

    val settings: Flow<UserSettings> = context.settingsDataStore.data.map { prefs ->
        UserSettings(
            darkMode = prefs[Keys.darkMode] ?: false,
            theme = prefs[Keys.theme] ?: "system"
        )
    }

    suspend fun setDarkMode(enabled: Boolean) {
        context.settingsDataStore.edit { prefs ->
            prefs[Keys.darkMode] = enabled
        }
    }

    suspend fun setTheme(value: String) {
        context.settingsDataStore.edit { prefs ->
            prefs[Keys.theme] = value
        }
    }
}

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val repository = SettingsRepository(applicationContext)

        lifecycleScope.launch {
            repository.settings.collect { settings ->
                Log.i(
                    "Settings",
                    "darkMode=${settings.darkMode}, theme=${settings.theme}"
                )
            }
        }

        lifecycleScope.launch {
            repository.setDarkMode(true)
            repository.setTheme("dark")
        }
    }
}

预期输出

text
darkMode=true, theme=dark

Logcat 可能还会先看到默认值或中间状态,因为 Flow 会在数据变化时持续发射;最终应出现上面的组合。日志时间、进程号等环境字段会因设备不同而变化,因此这里只列出消息正文。

读写机制要抓住两点

settingsDataStore.data 不是一次性读取,而是 Flow<Preferences>。磁盘值变化后,映射得到的 UserSettings 会继续发射新值,界面层可以再把它转换成适合自身生命周期的状态。

edit 是挂起函数,适合从协程调用。传入的代码块对当前 Preferences 做一次原子更新,因此相关键如果必须同时保持一致,应放在同一次 edit 中,而不是拆成互不相关的多次写入。

哪些数据不要放进 Preferences DataStore

Preferences DataStore 适合小规模偏好,不适合消息列表、订单、复杂筛选或多表关系;这类结构化数据应优先考虑 Room。图片、音频和下载包也应使用文件系统,而不是把大块内容塞进键值存储。

它也不是“安全保险箱”。敏感令牌、密码或需要专门密钥保护的材料,不应仅因为写进 DataStore 就视为已加密。先根据安全要求选择合适的凭据或加密方案,再决定是否需要 DataStore 参与保存非敏感状态。

把 Preferences DataStore 放在数据层并通过仓库暴露 Flow,可以让界面只关心“当前设置是什么”和“如何更新设置”,而不用直接操作持久化文件。这也是偏好数据最稳妥、最容易测试和演进的使用方式。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Preferences DataStore

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通