Preferences 键值存储 — 轻量级配置数据的持久化方案一、引言在应用开发中大量的配置类数据如用户偏好、开关状态、简单缓存不需要复杂的数据库支持只需要一个轻量级的键值存储方案。鸿蒙系统的 Preferences首选项正是为此类场景设计它以简洁的 API、异步的操作和良好的性能成为配置数据持久化的首选方案。MoneyTrack 在提醒设置、预算金额等场景中大量使用 Preferences实现了配置数据的快速读写和持久化。二、核心知识点2.1 Preferences 完整使用步骤Preferences 的使用遵循「获取实例 → 读写数据 → 刷入磁盘」的标准流程import{preferences}fromkit.ArkDataasyncfunctiondemoPreferences(context:Context){// 第一步获取 Preferences 实例// getPreferences 是异步操作返回 Preferences 对象// 文件名 demo_pref 对应磁盘上的一个 XML 文件constprefawaitpreferences.getPreferences(context,demo_pref)// 第二步写入数据修改在内存中尚未落盘awaitpref.put(username,alice)// stringawaitpref.put(age,25)// numberawaitpref.put(is_vip,true)// booleanawaitpref.put(tags,[premium,yearly])// Arraystring// 第三步刷入磁盘必须显式调用 flush// flush 将内存中的所有修改批量写入磁盘文件awaitpref.flush()// 读取数据需指定默认值防止首次读取返回 undefinedconstusernameawaitpref.get(username,default_user)constageawaitpref.get(age,18)constisVipawaitpref.get(is_vip,false)}关于 flush 的说明flush()是异步批量写入操作调用后不保证立即完成。在应用进入后台或即将退出前调用flush()可确保数据安全。2.2 异步读写流程磁盘 XML内存缓存Preferences API应用层磁盘 XML内存缓存Preferences API应用层其他页面修改数据时getPreferences(context, name)读取 XML 文件返回数据加载到内存缓存返回 Preferences 实例put(key, value)更新内存缓存voidget(key, default)从内存读取valuevalueflush()批量写入磁盘写入完成voidon(change, callback)注册监听触发 change 回调2.3 多实例隔离Preferences 支持基于文件名创建多个独立实例不同模块使用不同的文件实现数据隔离// 不同模块使用独立的 Preferences 文件constreminderPrefawaitpreferences.getPreferences(context,reminder_settings)constthemePrefawaitpreferences.getPreferences(context,theme_settings)constbudgetPrefawaitpreferences.getPreferences(context,budget_settings)// 每个文件独立存储互不干扰awaitreminderPref.put(enabled,true)awaitthemePref.put(theme,dark)awaitbudgetPref.put(monthly_limit,5000)多实例隔离的好处模块间数据解耦修改一个模块的配置不影响其他模块文件粒度的管理方便单独清除某个模块的缓存减少单个文件大小提升读写性能2.4 数据删除操作除了读写Preferences 还提供了数据删除能力// 删除指定的 key-valueawaitpref.delete(temp_setting)// 检查某个 key 是否存在consthasKeyawaitpref.has(reminder_enabled)// 清空所有数据谨慎使用awaitpref.clear()// 删除 Preferences 文件释放磁盘空间awaitpreferences.deletePreferences(context,obsolete_settings)// 注意delete 和 clear 后都需要 flush 才能持久化awaitpref.flush()2.5 数据变更监听Preferences 支持通过on(change)事件监听数据变更这在多页面共享同一配置时特别有用——当某个页面修改了配置其他页面可以实时感知变化并更新 UIpreferences.on(change,(key){if(keyreminder_enabled){this.refreshUI()}})三、项目代码案例3.1 ReminderSettingVM 完整实现在products/entry/src/main/ets/viewmodel/reminder/ReminderSettingVM.ets中ReminderSettingVM 封装了提醒设置的全部逻辑exportclassReminderSettingVM{privatepref:preferences.Preferences|nullnullprivatecontext:Context// 持久化键值privatestaticreadonlyKEY_ENABLEDreminder_enabledprivatestaticreadonlyKEY_TIMEreminder_timeprivatestaticreadonlyKEY_PERIODreminder_periodprivatestaticreadonlyPREF_NAMEreminder_settingsconstructor(context:Context){this.contextcontext}// 初始化加载偏好设置asyncinit():Promisevoid{this.prefawaitpreferences.getPreferences(this.context,ReminderSettingVM.PREF_NAME)// 注册监听this.pref.on(change,(key){console.log(提醒设置变更:,key)})}// 读取提醒是否开启asyncisEnabled():Promiseboolean{returnawaitthis.pref!.get(ReminderSettingVM.KEY_ENABLED,false)}// 设置提醒开关asyncsetEnabled(enabled:boolean):Promisevoid{awaitthis.pref!.put(ReminderSettingVM.KEY_ENABLED,enabled)awaitthis.pref!.flush()}// 读取提醒时间asyncgetReminderTime():Promisestring{returnawaitthis.pref!.get(ReminderSettingVM.KEY_TIME,08:00)}// 设置提醒时间asyncsetReminderTime(time:string):Promisevoid{awaitthis.pref!.put(ReminderSettingVM.KEY_TIME,time)awaitthis.pref!.flush()}}3.2 预算金额持久化在预算管理模块中月度预算金额通过 Preferences 持久化// 键budget_{year}_{month}支持分别存储每个月的预算asyncsaveMonthlyBudget(year:number,month:number,amount:number){constprefawaitpreferences.getPreferences(this.context,budget_settings)constkeybudget_${year}_${month}awaitpref.put(key,amount)awaitpref.flush()}asyncloadMonthlyBudget(year:number,month:number):Promisenumber{constprefawaitpreferences.getPreferences(this.context,budget_settings)constkeybudget_${year}_${month}returnawaitpref.get(key,0)}3.3 使用注意事项及时 flush修改后调用flush()确保数据落盘避免应用退出导致数据丢失默认值使用get()方法时始终提供合理的默认值处理首次使用场景键名规范使用有意义的键名如module_key的命名模式数据量控制Preferences 适合少量配置数据建议不超过 100 个 key大量数据应使用 RDB避免频繁 flush多次 put 后统一 flush 一次减少磁盘 I/O四、参考文档Preferences 首选项指南Preferences API 参考数据存储安全建议
