本篇深入剖析 ImportantDays 项目的数据持久化方案——基于 HarmonyOS ArkData 模块的 Preferences 轻量级存储，以及 PreferenceUtil 工具类的单例封装。
一、HarmonyOS 数据存储方案对比
HarmonyOS 提供了多种数据存储方案：
| 方案 | 适用场景 | 特点 |
|---|---|---|
| Preferences | 轻量级 KV 数据 | 同步操作，适合少量数据 |
| 关系型数据库 (RDB) | 结构化数据 | SQLite，支持复杂查询 |
| 分布式数据 (DDS) | 跨设备同步 | 多设备数据一致性 |
| 文件存储 | 大文件 | 直接读写文件系统 |
ImportantDays 选择 Preferences 的原因：
- 数据量小（通常几十条重要日）
- 数据结构简单（JSON 字符串）
- 不需要复杂查询
- 同步操作，代码简洁
二、PreferenceUtil 工具类
2.1 完整实现
// utils/PreferenceUtil.etsimport{preferences}from'@kit.ArkData';import{common}from'@kit.AbilityKit';import{Logger}from'./Logger';exportclassPreferenceUtil{privatestaticpreferenceRecord:Map<string,PreferenceUtil>=newMap();privatedataPreferences:preferences.Preferences|null=null;privateconstructor(context:Context,fileName:string){preferences.removePreferencesFromCacheSync(context,fileName);this.dataPreferences=preferences.getPreferencesSync(context,{name:fileName});Logger.info(`PreferenceUtil:${fileName}init:${this.dataPreferences!=null}`);}publicstaticgetInstance(context?:Context,fileName:string='default'):PreferenceUtil{if(PreferenceUtil.preferenceRecord.has(fileName)){returnPreferenceUtil.preferenceRecord.get(fileName)!;}constctx:Context=context||getContext()ascommon.UIAbilityContext;constpreferenceUtil:PreferenceUtil=newPreferenceUtil(ctx,fileName);PreferenceUtil.preferenceRecord.set(fileName,preferenceUtil);returnpreferenceUtil;}publicgetPreferences():preferences.Preferences|null{returnthis.dataPreferences;}publicput(key:string,value:object|string|number|boolean):void{if(!this.dataPreferences){Logger.info('PreferenceUtil: dataPreferences is null');return;}try{this.dataPreferences.putSync(key,value);this.dataPreferences.flushSync();Logger.info(`PreferenceUtil: put:${key}`);}catch(e){Logger.error(`PreferenceUtil: put error:${JSON.stringify(e)}`);}}publicget(key:string,defaultValue:object|string|number|boolean):object|string|number|boolean{if(!this.dataPreferences){returndefaultValue;}try{returnthis.dataPreferences.getSync(key,defaultValue)asobject|string|number|boolean;}catch(e){Logger.error(`PreferenceUtil: get error:${JSON.stringify(e)}`);returndefaultValue;}}publicdelete(key:string):void{if(!this.dataPreferences){return;}try{this.dataPreferences.deleteSync(key);this.dataPreferences.flushSync();Logger.info(`PreferenceUtil: delete:${key}`);}catch(e){Logger.error(`PreferenceUtil: delete error:${JSON.stringify(e)}`);}}}2.2 设计要点
单例模式（按文件名区分）
privatestaticpreferenceRecord:Map<string,PreferenceUtil>=newMap();publicstaticgetInstance(context?:Context,fileName:string='default'):PreferenceUtil{if(PreferenceUtil.preferenceRecord.has(fileName)){returnPreferenceUtil.preferenceRecord.get(fileName)!;}// ...创建新实例}使用Map按fileName维护多个实例，每个文件对应一个PreferenceUtil实例。
缓存清理
privateconstructor(context:Context,fileName:string){preferences.removePreferencesFromCacheSync(context,fileName);this.dataPreferences=preferences.getPreferencesSync(context,{name:fileName});}在创建实例前先从缓存中移除，确保获取的是最新实例。这是处理开发热重载时缓存残留的关键。
同步 API
this.dataPreferences.putSync(key,value);this.dataPreferences.flushSync();使用同步 API 而非异步，简化调用方代码。对于轻量级数据，同步操作的性能影响可以忽略。
容错处理
publicput(key:string,value:object|string|number|boolean):void{if(!this.dataPreferences){Logger.info('PreferenceUtil: dataPreferences is null');return;}try{this.dataPreferences.putSync(key,value);this.dataPreferences.flushSync();}catch(e){Logger.error(`PreferenceUtil: put error:${JSON.stringify(e)}`);}}所有操作都包含 try-catch，确保存储异常不会导致应用崩溃。
三、在 MainViewModel 中使用
3.1 初始化
// viewmodel/MainViewModel.etspublicasyncinit(context:Context):Promise<void>{this.prefUtil=PreferenceUtil.getInstance(context,AppConstants.PREF_FILE);this.loadDays();}常量定义：
// common/Constants.etsexportclassAppConstants{publicstaticreadonlyPREF_FILE:string='important_days';publicstaticreadonlyPREF_KEY_DAYS:string='important_day_list';}3.2 加载数据
privateloadDays():void{if(!this.prefUtil)return;constjsonStr=this.prefUtil.get(AppConstants.PREF_KEY_DAYS,'[]')asstring;try{constarr:string[]=JSON.parse(jsonStr);this.dayList=arr.map((json:string)=>ImportantDay.fromJSON(json)).filter((day:ImportantDay|null)=>day!==null)asImportantDay[];}catch(e){Logger.error(`MainViewModel: loadDays error:${JSON.stringify(e)}`);this.dayList=[];}}3.3 保存数据
privatesaveDays():void{if(!this.prefUtil)return;constarr:string[]=this.dayList.map((day:ImportantDay)=>day.toJSON());this.prefUtil.put(AppConstants.PREF_KEY_DAYS,JSON.stringify(arr));}3.4 数据存储格式
Preferences 中存储的数据结构：
文件: important_days 键: important_day_list 值: '["{\"id\":\"1690000000000_3456\",\"title\":\"妈妈生日\",\"date\":\"2026-03-15\",\"description\":\"记得买蛋糕\",\"colorIndex\":5,\"countMode\":0,\"repeatType\":1,\"advanceDays\":3,\"isPinned\":true,\"createdAt\":1690000000000,\"updatedAt\":1690000000000}"]'外层是一个 JSON 数组字符串，每个元素是ImportantDay.toJSON()的结果。这种嵌套设计的原因：
- Preferences 的
putSync只支持基本类型（string、number、boolean）和 string - 将数组序列化为字符串存储，可以一次性保存所有数据
- 加载时一次性反序列化，减少 IO 操作
四、putSync 与 flushSync 的区别
this.dataPreferences.putSync(key,value);// 写入内存缓存this.dataPreferences.flushSync();// 持久化到文件putSync：将数据写入内存缓存，速度极快flushSync：将内存缓存的数据刷写到磁盘文件，确保数据持久化
两者必须配合使用。如果只调用putSync而不flushSync，数据在应用关闭后会丢失。
五、removePreferencesFromCacheSync 的作用
preferences.removePreferencesFromCacheSync(context,fileName);这行代码在构造函数中调用，用于从内存缓存中移除指定文件的 Preferences 实例。这在以下场景中很重要：
- 开发阶段热重载：DevEco Studio 热重载时，旧的 Preferences 实例可能还留在缓存中
- 多实例场景：确保每次
getInstance获取的是最新状态 - 数据同步：防止缓存中的脏数据影响新实例
六、存储方案扩展思考
6.1 当前方案的局限
- 全量保存：每次修改都保存整个列表，数据量大时可能有性能问题
- 无索引：查询某日的重要日需要遍历整个列表
- 无事务：多步操作不具备原子性
6.2 如果使用 RDB
如果未来数据量增长，可以迁移到关系型数据库：
CREATETABLEimportant_days(idTEXTPRIMARYKEY,titleTEXTNOTNULL,dateTEXTNOTNULL,descriptionTEXT,color_indexINTEGERDEFAULT0,count_modeINTEGERDEFAULT0,repeat_typeINTEGERDEFAULT0,advance_daysINTEGERDEFAULT0,is_pinnedINTEGERDEFAULT0,created_atINTEGER,updated_atINTEGER);CREATEINDEXidx_dateONimportant_days(date);CREATEINDEXidx_pinnedONimportant_days(is_pinned);但当前 Preferences 方案对于这个应用规模完全够用，简单可靠。
七、小结
本篇详细介绍了 ImportantDays 项目的数据持久化方案。PreferenceUtil 通过单例模式封装 Preferences API，提供简洁的get/put/delete接口。MainViewModel 在每次 CRUD 操作后自动调用saveDays()持久化数据，确保数据不丢失。
