ComposeDataSaver

// booleanExample 初始化值为 false
// 之后会自动读取本地数据
var booleanExample by rememberDataSaverState("KEY_BOOLEAN_EXAMPLE", false)
// 直接赋值即可完成持久化
booleanExample = true
// 或者在 ViewModel 中
class MyViewModel: ViewModel() {
 // 当存储一个 int 值且默认值为 0 时,我们建议您显式地标记变量的类型为 `Int` 以避免被默认视为 `Long`
 var intExample by mutableDataSaverStateOf<Int>(
 dataSaverInterface = AppConfig.dataSaver,
 key = "KEY_INT_EXAMPLE",
 initialValue = 0
 )
 fun increment() {
 intExample++ // 当值变化时,数据会自动保存
 }
}

引入

dependencyResolutionManagement {
 repositories {
 mavenCentral()
 }
}

dependencies {
 implementation "io.github.funnysaltyfish:data-saver-core:1.2.3"
}

示例代码

配置

Android

Perference

// init preferences
val dataSaverPreferences = DataSaverPreferences(applicationContext)
CompositionLocalProvider(LocalDataSaver provides dataSaverPreferences){
	ExampleComposable()
}

MMKV

// if you want to use mmkv
implementation "io.github.funnysaltyfish:data-saver-mmkv:1.2.3"
implementation 'com.tencent:mmkv:1.2.14'

// 全局初始化 MMKV,比如在 Application 的 onCreate 中
MMKV.initialize(applicationContext)
...
val dataSaverMMKV = DefaultDataSaverMMKV
// DefaultDataSaverMMKV 是我们提供的默认实现,您可以在任何地方使用它,就像一个 MMKVUtils 那样
// 如果有定制 MMKV 的需要,可以选择 DataSaverMMKV(MMKV.defaultMMKV())
CompositionLocalProvider(LocalDataSaver provides dataSaverMMKV){
 // ...
}

DataStorePreference

// if you want to use DataStore
implementation "io.github.funnysaltyfish:data-saver-data-store-preferences:1.2.3"
def data_store_version = "1.0.0"
implementation "androidx.datastore:datastore:$data_store_version"
implementation "androidx.datastore:datastore-preferences:$data_store_version"

val Context.dataStore : DataStore<Preferences> by preferencesDataStore("dataStore")
val dataSaverDataStorePreferences = DataSaverDataStorePreferences(applicationContext.dataStore)
CompositionLocalProvider(LocalDataSaver provides dataSaverDataStorePreferences){
 // ...
}

JVM Desktop

// init properties
val dataSaver = DataSaverProperties("$userHome/$projectName/config.properties")
CompositionLocalProvider(LocalDataSaver provides dataSaver){
 ExampleComposable()
}

val dataSaver = DataSaverEncryptedProperties("$userHome/$projectName/data_saver_encrypted.properties", "FunnySaltyFish")
CompositionLocalProvider(LocalDataSaver provides dataSaver){
 ExampleComposable()
}

iOS

// 使用默认的 NSUserDefaults 实例
val dataSaver = DefaultDataSaverNSUserDefaults
CompositionLocalProvider(LocalDataSaver provides dataSaver){
 ExampleComposable()
}
// 或者自定义配置
val customDataSaver = DataSaverNSUserDefaults(
 userDefaults = NSUserDefaults.standardUserDefaults,
 senseExternalDataChange = true // 启用外部变更监听
)

WASM

// 使用默认配置
val dataSaver = DefaultDataSaverLocalStorage
CompositionLocalProvider(LocalDataSaver provides dataSaver){
 ExampleComposable()
}
// 或者自定义键前缀
val customDataSaver = DataSaverLocalStorage(
 keyPrefix = "MyApp_", // 自定义键前缀,避免冲突
 senseExternalDataChange = false // WASM 暂不支持外部变更监听
)

保存数据

// booleanExample 初始化值为 false
// 之后会自动读取本地数据
var booleanExample by rememberDataSaverState("KEY_BOOLEAN_EXAMPLE", false)
// 直接赋值即可完成持久化
booleanExample = true

@Serializable
data class ExampleBean(var id: Int, val label: String)
// ------------ //
// 在初始化时调用registerTypeConverters方法注册对应转换方法
// 该方法接收两个参数:分别用于 转成可序列化类型以保存 和 反序列化为您的Bean
// 此处使用 Json.encodeToString 和 Json.decodeFromString, 您也可以用 Gson、Fastjson 等
registerTypeConverters<ExampleBean>(
	save = { bean -> Json.encodeToString(bean) },
	restore = { str -> Json.decodeFromString(str) }
)
// 或者,如果你只需要对某个 state 编写转换器,可以直接传入 `typeConverter` 参数
// 此参数如有,则其优先级高于 `registerTypeConverters` 方法注册的全局转换器
var array by rememberDataSaverState(
 "custom_type_converter_example",
 intArrayOf(1, 2, 3, 4, 5),
 // 参数类型为 ITypeConverter,这里的 ClassTypeConverter 是基于 type 类型 accept 的子类
 typeConverter = object : ClassTypeConverter(type = typeOf<IntArray>()) {
 override fun save(data: Any?): String {
 return (data as IntArray).joinToString(",")
 }
 override fun restore(str: String): Any {
 return str.split(",").map { it.toInt() }.toIntArray()
 }
 }
)

inline fun <reified T> registerTypeConverters(
 noinline save: (T) -> String,
 noinline restore: (String) -> T,
 noinline acceptCondition: (T) -> Boolean
)

在 Composable 函数外使用

object AppConfig {
 val dataSaver = DataSaverMMKV(...)
}
class MyViewModel: ViewModel() {
 var username: String by mutableDataSavarStateOf(AppConfig.dataSaver, "username", "")
}

使用其他存储框架

abstract class DataSaverInterface(val senseExternalDataChange: Boolean = false) {
 abstract fun <T> saveData(key: String, data: T)
 abstract fun <T> readData(key: String, default: T): T
 open suspend fun <T> saveDataAsync(key: String, data: T) = saveData(key, data)
 abstract fun remove(key: String)
 abstract fun contains(key: String): Boolean
 var externalDataChangedFlow: MutableSharedFlow<Pair<String, Any?>>? =
 if (senseExternalDataChange) MutableSharedFlow(replay = 1) else null
}

val dataSaverXXX = DataSaverXXX()
CompositionLocalProvider(LocalDataSaver provides dataSaverXXX){
 ExampleComposable()
}

感知外部数据变化

val dataSaverXXX = DataSaverXXX(senseExternalDataChange = true)
CompositionLocalProvider(LocalDataSaver provides dataSaverXXX){
 val stringExample by rememberDataSaverState(
 key = key,
 initialValue = "Hello World(1)",
 senseExternalDataChange = true
 )
 ...
 onClick = {
 // 外部修改了key对应的值,此时Composable会自动更新
 dataSaverXXX.saveData(key, "Hello World(2)")
 }
}

高级设置

控制保存策略

open class SavePolicy {
 /**
 * 默认模式,每次给state的value赋新值时就做持久化
 */
 object IMMEDIATELY : SavePolicy()
 /**
 * Composable `onDispose` 时做数据持久化,适合数据变动比较频繁、且此Composable会进入onDispose的情况。
 * **慎用此模式,因为有些情况下onDispose不会被回调**
 */
 object DISPOSED: SavePolicy()
 /**
 * 不会自动做持久化操作,请按需自行调用`state.saveData()`。
 * Example: `onClick = { state.saveData() }`
 */
 object NEVER : SavePolicy()
}

设置库参数

/**
 * 1. DEBUG: 是否输出库的调试信息
 */
object DataSaverConfig {
 var DEBUG = true
}

异步保存

@Preview 支持

@Composable
@ReadOnlyComposable
fun getLocalDataSaverInterface() =
 if (LocalInspectionMode.current) DefaultDataSaverInMemory else LocalDataSaver.current

使用的项目