第20篇鸿蒙应用数据持久化——Preferences 首选项详解一、引言数据持久化是应用开发的基础需求。在鸿蒙中Preferences 首选项 API 提供了轻量级的数据持久化能力适合存储键值对形式的配置数据。DriverLicenseExam 项目使用 Preferences 来存储深色模式、服务卡片 ID 等用户偏好数据。本文将深入解析其实现。二、PreferencesUtil 封装2.1 单例封装// commons/commonLib/src/main/ets/utils/PreferencesUtil.etsexportclassPreferencesUtil{privatestaticpreferencesUtil: PreferencesUtil;privatestaticreadonlyMY_STORE:stringmyStore;publicstaticgetInstance(): PreferencesUtil{if(!PreferencesUtil.preferencesUtil) { PreferencesUtil.preferencesUtil newPreferencesUtil(); }returnPreferencesUtil.preferencesUtil; } }2.2 核心方法// 获取 Preferences 实例getPreferences(context:Context): preferences.Preferences{try{ preferences.removePreferencesFromCacheSync(context,MY_STORE); }catch(e) {}returnpreferences.getPreferencesSync(context, {name:MY_STORE}); }// 写入数据preferencesPut(preferences: preferences.Preferences,key:string,value: preferences.ValueType):void{ preferences.putSync(key, value);this.preferencesFlush(preferences); }// 读取数据getPreferencesValue(preferences: preferences.Preferences,key:string): preferences.ValueType{if(preferences null) {Logger.error(TAG,preferences is null);return; }returnpreferences.getSync(key,); }// 检查 key 是否存在hasPreferencesKey(preferences: preferences.Preferences,key:string):boolean{if(preferences null)returnfalse;returnpreferences.hasSync(key); }// 刷新同步到磁盘preferencesFlush(preferences: preferences.Preferences) {try{ preferences.flush((err) {if(err) {Logger.error(TAG,Failed to flush. Code: ${err.code}, message: ${err.message}); } }); }catch(e) {Logger.error(TAG,Failed to call preferences.flush: ${JSON.stringify(e)}); } }三、实际应用场景3.1 深色模式持久化// EntryAbility.ets 中恢复深色模式privatesetLightOrDarkMode(context: Context){ const preferencesUtil PreferencesUtil.getInstance(); const preference preferencesUtil.getPreferences(context); const value preferencesUtil.getPreferencesValue(preference, lightDarkMode)||0;AppStorage.setOrCreate(lightDarkMode,value);if(value0) { context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET); }elseif(value1) { context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT); }elseif(value2) { context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK); } }3.2 服务卡片数据持久化// MainEntry.ets 中更新卡片数据updateForm(index:number){ const preferencesUtil PreferencesUtil.getInstance(); const preference preferencesUtil.getPreferences(this.getUIContext().getHostContext()asContext); preferencesUtil.preferencesPut(preference, tabIndex,index); preferencesUtil.preferencesPut(preference, didCount,this.didCount); preferencesUtil.preferencesPut(preference, totalCount,this.totalCount);// 更新服务卡片const formInfo formBindingData.createFormBindingData(newData); formIds.forEach((id:string) { formProvider.updateForm(id,formInfo); }); }3.3 表单 ID 管理// 获取所有表单 IDgetFormIds(preferences:preferences.Preferences): Arraystring {if(preferencesnull) return[]; return preferences.getSync(formIdList, [])asArraystring; }// 添加表单 IDaddFormId(preferences:preferences.Preferences,formId:string): void {if(preferences.hasSync(formIdList)) {letformIds this.getFormIds(preferences);if(formIds.indexOf(formId)-1) { formIds.push(formId); this.preferencesPut(preferences, formIdList,formIds); } }else{ this.preferencesPut(preferences, formIdList, [formId]); } }// 移除表单 IDremoveFormId(context: Context,formId:string){letpreferences this.getPreferences(context);if(preferences.hasSync(formIdList)) {letformIds this.getFormIds(preferences);letindex formIds.indexOf(formId);if(index ! -1) { formIds.splice(index,1); this.preferencesPut(preferences, formIdList,formIds); } } }四、Preferences 最佳实践4.1 使用原则// 1. 缓存清除每次获取前清除缓存确保数据最新preferences.removePreferencesFromCacheSync(context, MY_STORE);// 2. 写入后立即刷新preferences.putSync(key, value);this.preferencesFlush(preferences);// 立即同步到磁盘// 3. 异常处理所有操作都需 try-catchtry{ preferences.putSync(key, value); }catch(e) { Logger.error(TAG,Failed to put preferences: ${JSON.stringify(e)}); }4.2 适用场景用户偏好设置深色模式、字体大小等应用配置数据缓存少量结构化数据服务卡片相关数据五、总结Preferences 首选项是鸿蒙应用中最常用的轻量级数据持久化方案。通过 PreferencesUtil 的封装项目实现了统一的数据读写接口支持深色模式、服务卡片等场景的数据持久化。关键源码文件commons/commonLib/src/main/ets/utils/PreferencesUtil.ets— 首选项封装products/entry/src/main/ets/entryability/EntryAbility.ets— 深色模式持久化products/entry/src/main/ets/pages/MainEntry.ets— 卡片数据持久化
