《个人头像上传》二、Preferences用户首选项使用指南 HarmonyOS ohos.data.preferences 用户首选项完全指南轻量级数据持久化实战适用版本HarmonyOS API 23| DevEco Studio 6.1关键词preferences、用户首选项、键值存储、数据持久化、getPreferencesSync效果一、前言在移动应用开发中我们经常需要保存一些轻量级数据——用户设置、主题偏好、登录状态标记等。这些数据不需要关系型数据库但又不能每次启动都重新获取。HarmonyOS 提供了ohos.data.preferences用户首选项模块为应用提供 Key-Value 键值型数据持久化能力。它的特点是轻量级适合存储配置信息、简单状态数据自动持久化写入后自动保存到本地文件同步/异步双模式灵活适配不同场景数据监听支持监听数据变化事件本文将全面讲解 Preferences API 的使用方法并提供完整可运行的实例代码。二、模块导入import{preferences}fromkit.ArkData;首批接口从API version 9开始支持。三、基本概念3.1 数据存储模型Preferences 采用Key-Value键值对存储项限制Key 最大长度1024 字节Value 最大长度16MB3.2 支持的 ValueTypetypeValueTypenumber|string|boolean|Arraynumber|Arraystring|Arrayboolean不支持存储对象类型。如需存储对象请先JSON.stringify()转为字符串。四、获取 Preferences 实例4.1 同步获取推荐import{preferences}fromkit.ArkData;import{common}fromkit.AbilityKit;// 在 UIAbility 或组件中获取 Contextconstcontextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;// 同步获取 Preferences 实例conststorepreferences.getPreferencesSync(context,{name:my_store});4.2 异步获取// Promise 方式conststoreawaitpreferences.getPreferences(context,{name:my_store});// Callback 方式preferences.getPreferences(context,{name:my_store},(err,store){if(err){console.error(Failed to get preferences:,err);return;}// 使用 store});4.3 关键区别方法返回值适用场景getPreferencesSyncPreferences启动时初始化不阻塞UIgetPreferencesPromisePreferences需要异步等待的场景注意同一个name在同一应用内会返回同一个缓存实例不会重复创建文件。五、CRUD 操作详解5.1 写入数据put// 同步写入store.putSync(username,张三);store.putSync(age,25);store.putSync(isVip,true);store.putSync(scores,[98,85,92]);// 数组也支持// 异步写入awaitstore.put(username,张三);awaitstore.put(age,25);重要put只写入内存缓存必须调用flush才能持久化到磁盘5.2 读取数据get// 同步读取第二个参数是默认值constusernamestore.getSync(username,)asstring;constagestore.getSync(age,0)asnumber;constisVipstore.getSync(isVip,false)asboolean;// 异步读取constusernameawaitstore.get(username,)asstring;get的第二个参数是默认值当 key 不存在时返回该值。5.3 检查 Key 是否存在has// 同步检查constexistsstore.hasSync(username);// 异步检查constexistsawaitstore.has(username);5.4 删除数据delete// 同步删除store.deleteSync(username);// 异步删除awaitstore.delete(username);5.5 刷盘持久化flush// 同步刷盘store.flushSync();// 异步刷盘awaitstore.flush();最佳实践批量写入后统一调用一次flush避免频繁磁盘IO。5.6 清空所有数据clear// 同步清空store.clearSync();// 异步清空awaitstore.clear();5.7 获取全部数据getAll// 同步获取constallDatastore.getAllSync()asRecordstring,preferences.ValueType;// 异步获取constallDataawaitstore.getAll()asRecordstring,preferences.ValueType;六、数据变化监听6.1 监听数据变化// ✅ 推荐监听 change 事件API 9回调参数为变化的 keyconstonChange(key:string){console.log(Key ${key} changed);};store.on(change,onChange);// 监听 multiProcessChange 事件API 10多进程场景constonMultiProcessChange(key:string){console.log(Multi-process: Key ${key} changed);};store.on(multiProcessChange,onMultiProcessChange);⚠️ 注意dataChange事件API 12的签名要求传入keys: string[]数组参数回调返回Recordstring, ValueType而非简单的无参回调。不要误用store.on(dataChange, () {})这会导致编译错误。// ⚠️ dataChange 需要传入监听的 key 数组store.on(dataChange,[username,theme],(data:Recordstring,preferences.ValueType){console.log(Changed data:,JSON.stringify(data));});6.2 取消监听store.off(change,onChange);store.off(multiProcessChange,onMultiProcessChange);七、完整实战实例用户设置持久化以下是一个完整的用户设置页面演示 Preferences 的综合应用import{preferences}fromkit.ArkData;import{common}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;constTAGPreferencesDemo;/** * 用户设置管理器 */classSettingsManager{privatestore:preferences.Preferences|nullnull;init(context:common.UIAbilityContext):void{this.storepreferences.getPreferencesSync(context,{name:app_settings});}// 保存用户设置saveSettings(nickname:string,themeMode:string,fontSize:number):void{if(!this.store)return;this.store.putSync(nickname,nickname);this.store.putSync(themeMode,themeMode);this.store.putSync(fontSize,fontSize);this.store.putSync(updateTime,Date.now().toString());this.store.flushSync();}// 加载用户设置loadSettings():{nickname:string;themeMode:string;fontSize:number}{if(!this.store){return{nickname:默认用户,themeMode:light,fontSize:16};}return{nickname:this.store.getSync(nickname,默认用户)asstring,themeMode:this.store.getSync(themeMode,light)asstring,fontSize:this.store.getSync(fontSize,16)asnumber};}// 清除所有设置clearAll():void{if(!this.store)return;this.store.clearSync();this.store.flushSync();}}EntryComponentstruct PreferencesDemo{Statenickname:string;StatethemeMode:stringlight;StatefontSize:number16;StatestatusMessage:string;privatesettingsMgr:SettingsManagernewSettingsManager();aboutToAppear():void{constcontextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;if(context){this.settingsMgr.init(context);constsavedthis.settingsMgr.loadSettings();this.nicknamesaved.nickname;this.themeModesaved.themeMode;this.fontSizesaved.fontSize;}}build(){Column({space:16}){Text(用户设置).fontSize(22).fontWeight(FontWeight.Bold).margin({top:40});// 昵称输入Row(){Text(昵称).width(80);TextInput({text:this.nickname,placeholder:请输入昵称}).layoutWeight(1).onChange((value:string){this.nicknamevalue;});}.width(90%);// 主题选择Row(){Text(主题).width(80);Radio({value:light,group:theme}).checked(this.themeModelight).onChange((isChecked:boolean){if(isChecked)this.themeModelight;});Text(浅色).margin({right:16});Radio({value:dark,group:theme}).checked(this.themeModedark).onChange((isChecked:boolean){if(isChecked)this.themeModedark;});Text(深色);}.width(90%);// 字体大小Row(){Text(字号).width(80);Slider({value:this.fontSize,min:12,max:24,step:1}).layoutWeight(1).onChange((value:number){this.fontSizevalue;});Text(${this.fontSize}px).width(50);}.width(90%);// 保存按钮Button(保存设置).width(70%).height(44).onClick((){this.settingsMgr.saveSettings(this.nickname,this.themeMode,this.fontSize);this.statusMessage✓ 设置已保存;});// 清除按钮Button(恢复默认).width(70%).height(44).fontColor(#FF4444).backgroundColor(#FFF0F0).onClick((){this.settingsMgr.clearAll();this.nickname默认用户;this.themeModelight;this.fontSize16;this.statusMessage✓ 已恢复默认设置;});// 状态提示if(this.statusMessage){Text(this.statusMessage).fontSize(14).fontColor(#4CAF50).margin({top:10});}}.width(100%).height(100%);}}八、同步 vs 异步 API 选择策略场景推荐方式原因应用启动初始化getPreferencesSync快速获取实例不影响启动速度页面加载时读取配置getSync数据量小同步读取更简单保存用户设置putSyncflushSync确保立即持久化后台批量数据写入putflush(async)避免阻塞主线程大体积数据写入putflush(async)16MB上限内的大数据异步更安全九、常见问题与最佳实践Q1Preferences 适合存什么数据适合用户昵称、主题模式、字体大小、登录标记、简单配置项。不适合大量结构化数据用关系型数据库 RDB、二进制文件用文件IO、敏感信息用加密存储。Q2put 后必须 flush 吗是的。put只修改内存中的值不调用flush的话应用重启后数据会丢失。Q3多进程可以共用一个 Preferences 吗不推荐。Preferences 无法保证进程并发安全。多进程场景请使用on(multiProcessChange)监听或改用 RDB 数据库。Q4如何存储对象Preferences 不直接支持对象需要序列化// 存储constuserObj{name:张三,age:25};store.putSync(user,JSON.stringify(userObj));store.flushSync();// 读取constrawstore.getSync(user,)asstring;constuserObjJSON.parse(raw)as{name:string;age:number};Q5如何删除 Preferences 文件// 删除首选项文件awaitpreferences.deletePreferences(context,{name:my_store});// 从缓存移除实例preferences.removePreferencesFromCacheSync(context,{name:my_store});十、API 版本演进API版本新增能力9基础 CRUD、getPreferences、flush10getPreferencesSync、getSync、putSync、flushSync、clearSync、hasSync10multiProcessChange 监听12dataChange 事件监听14flushSync 同步刷盘18StorageType 存储类型、isStorageTypeSupported十一、总结ohos.data.preferences是 HarmonyOS 中轻量级数据持久化的首选方案。核心要点getPreferencesSync获取实例简单直接putSync flushSync组合完成同步写入和持久化getSync读取数据第二参数为默认值JSON.stringify序列化对象后再存储on(‘change’)监听数据变化注意dataChange需要传入 keys 数组不适用于大数据量或多进程并发场景