原生移动开发 / 系统课时
Preferences DataStore
Preferences DataStore
Preferences DataStore 适合保存主题、通知开关、排序方式等少量键值偏好。它用协程完成异步写入,并以 Flow 暴露持续变化的数据。本课完成一个可运行的设置仓库:写入深色模式和主题值,再从同一数据流读取并验证结果。
学习目标
- 能创建单例 Preferences DataStore 并定义类型匹配的键
- 能使用
data与edit完成异步读取和事务式更新 - 能判断哪些数据不应该放进 Preferences DataStore
添加依赖并创建唯一实例
在应用模块的 build.gradle.kts 中加入稳定版 Preferences DataStore 依赖:
dependencies {
implementation("androidx.datastore:datastore-preferences:1.2.1")
}Gradle 同步成功后,项目即可使用 preferencesDataStore、Preferences 与各种 *PreferencesKey API。对同一个文件名,应在同一进程中只创建一个 DataStore 实例;最简单的方式是在 Kotlin 文件顶层声明属性委托。
用一个仓库封装读写
下面示例假设项目已有标准 AndroidX Activity 与 Lifecycle 依赖。settingsDataStore 是整个应用共享的入口,仓库把磁盘中的键值映射为业务对象,并把写入集中在挂起函数中。
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")
}
}
}预期输出
darkMode=true, theme=darkLogcat 可能还会先看到默认值或中间状态,因为 Flow 会在数据变化时持续发射;最终应出现上面的组合。日志时间、进程号等环境字段会因设备不同而变化,因此这里只列出消息正文。
读写机制要抓住两点
settingsDataStore.data 不是一次性读取,而是 Flow<Preferences>。磁盘值变化后,映射得到的 UserSettings 会继续发射新值,界面层可以再把它转换成适合自身生命周期的状态。
edit 是挂起函数,适合从协程调用。传入的代码块对当前 Preferences 做一次原子更新,因此相关键如果必须同时保持一致,应放在同一次 edit 中,而不是拆成互不相关的多次写入。
哪些数据不要放进 Preferences DataStore
Preferences DataStore 适合小规模偏好,不适合消息列表、订单、复杂筛选或多表关系;这类结构化数据应优先考虑 Room。图片、音频和下载包也应使用文件系统,而不是把大块内容塞进键值存储。
它也不是“安全保险箱”。敏感令牌、密码或需要专门密钥保护的材料,不应仅因为写进 DataStore 就视为已加密。先根据安全要求选择合适的凭据或加密方案,再决定是否需要 DataStore 参与保存非敏感状态。
把 Preferences DataStore 放在数据层并通过仓库暴露 Flow,可以让界面只关心“当前设置是什么”和“如何更新设置”,而不用直接操作持久化文件。这也是偏好数据最稳妥、最容易测试和演进的使用方式。