引言在移动应用开发中持久化用户配置是最常见的需求之一——主题偏好、字体大小、自动保存开关、最后登录时间这些数据量小但读频繁不适合每次都读写文件更不需要数据库。HarmonyOS NEXT 提供了ohos.data.preferences模块作为轻量级键值对的持久化存储方案。ohos.data.preferences属于kit.ArkData是一个经典的 Key-Value 存储实现。它的 API 设计可以总结为一句话获取实例是异步的Promise操作数据是同步的Sync。存储的数据类型覆盖了 9 种 ValueType — 从基础的 number/string/boolean 到复杂的 Array/Uint8Array/object/bigint能够满足绝大多数配置存储需求。数据自动持久化为沙箱内的 XML 文件应用卸载时被系统清除无需额外权限。与 Android 的SharedPreferences有 apply/commit 两种写入模式和已知的性能陷阱和 iOS 的UserDefaultsFoundation 框架自动持久化但类型支持有限不同鸿蒙的 Preferences 采用了更现代的设计显式的flushSync()控制落盘时机on/off(change)事件监听数据变更deleteSync单一键删除而非必须整个清除。这种精确控制 事件驱动的组合让开发者可以灵活地平衡性能和数据一致性。本文将深入讲解ohos.data.preferences的核心 API、ValueType 体系、变更监听机制和实际使用限制并构建一个首选项存储实验室Demo——在页面上完成键值对的写入、读取、删除和实时监听的全流程操作。一、API 架构异步获取实例 同步操作数据1.1 核心设计理念ohos.data.preferences的设计核心是Promise 获取实例 同步操作数据的双模式。导入方式importpreferencesfromohos.data.preferences;所有数据操作都通过Preferences实例进行但获取这个实例需要异步调用getPreferences()// 异步获取实例constctxgetContext(this);preferences.getPreferences(ctx,my_config).then((prefs:preferences.Preferences){// 之后所有操作都是同步的prefs.putSync(theme,dark);prefs.flushSync();});这种设计的原因在于Preferences 实例的创建需要从磁盘加载已有的 XML 文件而文件 I/O 操作哪怕是 XML 解析这样的小文件必须在异步上下文中执行避免阻塞 UI 线程。但一旦实例加载完成内存中的读写操作就可以同步执行了。1.2 Preferences 实例的完整 API 列表通过getPreferences()获取到的Preferences实例提供以下方法方法返回类型说明putSync(key: string, value: ValueType)void写入键值对getSync(key: string, defValue: ValueType)ValueType读取键值不存在时返回默认值hasSync(key: string)boolean检查键是否存在deleteSync(key: string)void删除指定键flushSync()void强制将内存数据写入磁盘 XML 文件on(change, callback)void注册数据变更监听off(change, callback?)void移除数据变更监听所有 Sync 方法都是同步的不会抛出 Promise——但如果传入非法参数如键名超过 80 字符会直接抛出异常需要通过 try/catch 保护。1.3 ValueType 的 9 种支持类型ValueType是 Preferences 支持的数据类型联合类型typeValueTypenumber|string|boolean|Arraynumber|Arraystring|Arrayboolean|Uint8Array|object|bigint;这意味着你可以存储几乎任何常见的数据类型// 字符串prefs.putSync(username,Alice);// 数字prefs.putSync(fontSize,16);// 布尔prefs.putSync(autoSave,true);// 对象会被序列化prefs.putSync(userProfile,{name:Alice,age:25,vip:true});// bigintprefs.putSync(maxId,BigInt(9999999999999));// Uint8Array二进制数据prefs.putSync(avatar,newUint8Array([0x89,0x50,0x4E,0x47]));需要注意的是object类型的存储依赖序列化——存储时使用 JSON 序列化读取时反序列化。复杂的对象例如包含函数、Symbol、循环引用不会被正确保留。getSync读取 object 类型时会自动反序列化为 JavaScript 对象。1.4 键名与值的长度限制Preferences 有两个硬性常量限制MAX_KEY_LENGTH 80— 键名最大 80 字符MAX_VALUE_LENGTH 8192— 字符串值最大 8192 字符这些限制确保了单个键值对的内存开销可控。如果需要存储超过 8192 字符的文本应该使用ohos.file.fs的文件读写而非 Preferences。二、数据持久化flushSync 与自动落盘2.1 flushSync 的明确性flushSync()是控制数据何时写入磁盘的关键方法。它强制将内存中的键值数据序列化为 XML 并写入沙箱内的文件。prefs.putSync(theme,dark);prefs.putSync(fontSize,14);prefs.flushSync();// 此时才真正写入磁盘不调用flushSync()时数据仅存在内存中应用崩溃或系统杀死进程可能导致数据丢失。因此在写入关键配置后应该显式调用flushSync()。与 AndroidSharedPreferences的apply()异步写磁盘可能在你最需要时还没完成不同鸿蒙的flushSync()是同步的——调用后数据一定在磁盘上。这是一个语义上更清晰的设计开发者不会混淆我写了数据和数据在磁盘上这两个状态。2.2 数据的磁盘存储位置Preferences 的数据文件存储在应用沙箱内的/data/storage/el2/base/preferences/目录下文件名由getPreferences()的第二个参数决定preferences.getPreferences(ctx,lab_prefs);// → lab_prefs.xml文件格式为 XML?xml version1.0 encodingUTF-8 standaloneno?preferencesstringnameusernameAlice/stringintnamefontSizevalue16/booleannameautoSavevaluetrue//preferences打开这个文件可以让开发者直接查看和验证存储的数据——这是 Preferences 相比数据库存储的一大优势数据可读、可手动修复、可调试。三、变更监听机制on/off(‘change’)3.1 注册与移除变更监听on(change, callback)提供了一个事件驱动的数据变更通知机制。当任何键值对被修改新增、更新、删除时回调函数会被调用// 注册监听prefs.on(change,(data:{key:string}){console.log(键值已变更: data.key);// data.key 是发生变更的键名});// 移除监听prefs.off(change);注意off(change)可以不传回调——这会移除该事件上的所有监听器。如果需要精确控制可以在on时保存回调引用off时传入同一个引用。3.2 变更监听的实际用途变更监听最常见的场景有两个跨页面配置同步页面 A 修改了主题设置页面 B 通过on(change)立即感知并更新 UI调试与审计在开发阶段注册全局监听追踪所有配置变更的来源和时间Demo 中的使用模式开启监听后每次写入或删除操作都会触发 change 事件日志中即时显示变更信息。privatetoggleListener():void{if(this.listenOn){this.prefs.off(change);this.listenOnfalse;}else{this.prefs.on(change,(){this.addLog(Preferences 数据已变更 (change 事件),success);this.loadAllKeys();// 自动刷新已存储键值列表});this.listenOntrue;}}四、实战 Demo首选项存储实验室4.1 页面设计首选项存储实验室页面围绕 Preferences 的核心 API 设计了六个功能区域状态栏显示 Preferences 加载状态就绪/加载中和变更监听开关状态ON/OFF变更监听开关本身也是一个 Toggle 按钮写入键值面板提供键名TextInput 值TextInput 类型选择器string/number/boolean 三个切换按钮 保存按钮。类型选择器使用互斥高亮设计——选中类型显示实心背景未选中类型显示浅色背景读取键值面板提供键名TextInput 读取按钮 结果显示行。读取不存在的键时显示 “(不存在)” 并采用灰色文字已存储键值列表展示所有已知键值对键名 值 类型标签 读取/删除按钮。每个条目显示三部分信息键名加粗、值等宽字体、单行省略、类型标签彩色胶囊。每个条目右侧有两个操作按钮——“读取”紫色边框和删除红色边框API 能力说明两个段落分别介绍核心 API 和使用限制作为知识参考卡片操作日志毫秒级时间戳 操作描述 颜色分类success 绿色、error 红色、system 灰色4.2 核心实现状态模型设计StateprefsReady:booleanfalse;// Preferences 是否已加载StatewriteKey:stringusername;// 写入键名默认值StatewriteValue:stringAlice;// 写入值默认值StatewriteType:stringstring;// 写入类型string/number/booleanStatereadKey:string;// 读取键名StatereadResult:string--;// 读取结果StatekvList:KvEntry[][];// 已存储的键值列表StatelistenOn:booleanfalse;// 变更监听开关Statelogs:LogEntry[][];// 操作日志privateprefs:preferences.Preferences|nullnull;设计要点prefsReady区分加载中的异步阶段与就绪后的同步操作阶段prefs使用null初始值所有同步操作前先检查非 nullkvList在每次写入、删除、变更事件后通过loadAllKeys()重新扫描更新异步加载 同步操作模式aboutToAppear():void{constctxgetContext(this);preferences.getPreferences(ctx,lab_prefs).then((p:preferences.Preferences){this.prefsp;this.prefsReadytrue;this.addLog(Preferences 已加载: lab_prefs,success);this.loadAllKeys();}).catch((e:Error){this.addLog(加载 Preferences 失败: e.message,error);});}这是整个页面的核心模式——getPreferences()是异步的在 Promise resolve 后设置prefsReady true之后所有用户交互写入、读取、删除都使用putSync/getSync/deleteSync/flushSync同步方法。写入带类型选择privatesaveValue():void{if(this.prefsnull)return;constkeythis.writeKey.trim();letvalue:preferences.ValueType;switch(this.writeType){casenumber:valueparseFloat(this.writeValue);if(isNaN(value)){this.addLog(请输入有效数字,error);return;}break;caseboolean:valuethis.writeValue.toLowerCase()true;break;default:valuethis.writeValue;break;}this.prefs.putSync(key,value);this.prefs.flushSync();this.addLog(已保存: key value.toString(),success);this.loadAllKeys();}类型转换逻辑number 用parseFloat并验证 NaNboolean 判断字符串是否为 “true”string 直接使用原值。转换后的值作为ValueType传入putSync。键值列表扫描privateloadAllKeys():void{if(this.prefsnull)return;this.kvList[];consttestKeys:string[][username,theme,fontSize,autoSave,lastLogin,score];for(leti0;itestKeys.length;i){try{constvalthis.prefs.getSync(testKeys[i],);if(val!val!undefinedval!null){this.kvList.push({key:testKeys[i],value:val.toString(),vtype:typeofval});}}catch(e){// key doesnt exist, skip}}}Demo 使用预定义的测试键列表来扫描已存储的键值对——这是一个简化方案。在生产代码中Preferences 本身不提供 “列出所有键” 的 API因此你需要在应用层维护一个已使用键名的清单或者使用其他方式追踪。变更监听 ToggleprivatetoggleListener():void{if(this.prefsnull)return;if(this.listenOn){this.prefs.off(change);this.listenOnfalse;this.addLog(变更监听已关闭,system);}else{this.prefs.on(change,(){this.addLog(Preferences 数据已变更 (change 事件),success);this.loadAllKeys();});this.listenOntrue;this.addLog(变更监听已开启,success);}}4.3 交互方式Demo 提供四个核心交互点写入键值对输入键名 → 选择类型string/number/boolean→ 输入值 → 点击保存 → 键值对出现在已存储列表中 → 操作日志记录读取键值对输入键名 → 点击读取 → 结果显示在读取面板中存在显示值不存在显示灰色(不存在)→ 操作日志记录管理已存储键值列表中每个条目显示类型标签紫色胶囊右侧提供读取按钮填充读取面板和删除按钮移除该键值对→ 操作后列表自动更新变更监听开关状态栏中的 Toggle 切换开启后任何写入/删除操作都会触发 change 事件 → 日志中显示Preferences 数据已变更→ 列表自动刷新五、最佳实践与使用限制5.1 何时使用 PreferencesPreferences 最合适的场景是用户配置主题模式dark/light、字体大小、通知开关、自动保存等应用状态首次启动标记、上次登录用户名、引导完成的步骤轻量缓存最近搜索关键词、上次选择的 Tab 页、界面布局偏好不适合使用 Preferences 的场景大量数据 100 个键值对考虑使用ohos.data.relationalStore关系数据库或文件存储大文本或二进制 8KB 单值使用ohos.file.fs文件存储复杂查询按条件筛选/排序使用数据库而非遍历所有键敏感数据密码、Token使用ohos.security.huks通用密钥库加密存储5.2 同步操作中的异常处理虽然 Sync 方法使用方便但它们在错误条件下会直接抛出异常。关键的保护点try{prefs.putSync(key,value);prefs.flushSync();}catch(e){console.error(写入失败: (easError).message);// 可能的原因键名超过 80 字符、值超过 8192 字符、磁盘空间不足}Demo 中所有操作都包裹在 try/catch 中——这在 Preferences 的使用中是必要的因为文件 I/O 错误磁盘满、权限变更可能在运行时发生。5.3 生命周期管理Preferences 实例不需要手动释放——它在getPreferences()返回后由系统管理。但变更监听器需要在组件销毁时移除避免内存泄漏aboutToDisappear():void{if(this.listenOnthis.prefs!null){try{this.prefs.off(change);}catch(e){// ignore}}}如果不移除监听器当组件被销毁后系统仍然会维持对回调函数的引用——造成内存泄漏和潜在的无效回调调用。5.4 数据迁移与版本管理当应用升级时Preferences 文件保留在沙箱内不变。如果你需要修改配置的键名或值格式应该在应用初始化时做迁移preferences.getPreferences(ctx,my_config).then((prefs){if(!prefs.hasSync(version)||prefs.getSync(version,1)2){// 执行从 v1 到 v2 的数据迁移constoldThemeprefs.getSync(theme,light);prefs.putSync(uiTheme,oldTheme);// 重命名键prefs.deleteSync(theme);prefs.putSync(version,2);prefs.flushSync();}});六、总结ohos.data.preferences是 HarmonyOS NEXT 中轻量级配置持久化的首选方案。通过本文的学习你应该已经掌握实例获取getPreferences(context, name): PromisePreferences异步加载返回 Preferences 实例数据写入putSync(key, value)写入键值对flushSync()强制落盘ValueType 支持 9 种类型数据读取getSync(key, defValue)读取键值不存在返回默认值hasSync(key)检查存在性数据管理deleteSync(key)删除单键on/off(change)注册/移除变更监听使用限制MAX_KEY_LENGTH 80字符键名限制MAX_VALUE_LENGTH 8192字符串值限制数据以 XML 存储在应用沙箱内ohos.data.preferences的最佳使用模式可以总结为getPreferences 异步获取实例 → 所有操作使用 Sync 同步方法 → flushSync 确保数据落盘 → on/off 管理变更监听 → aboutToDisappear 中移除监听避免内存泄漏。所有操作 try/catch 保护写入后显式 flushSync组件销毁时 off 清理。在 HarmonyOS 的数据管理体系中ohos.data.preferences定位于轻量级配置存储与ohos.data.relationalStore关系数据库、ohos.data.distributedKVStore分布式键值数据库和ohos.file.fs文件存储形成完整的数据能力栈。它是应用设置和用户偏好存储的第一选择——简单、可靠、零权限、开箱即用。ohos.data.preferences属于kit.ArkData获取实例需要 context所有写操作使用 Sync 方法同步执行读取操作无需任何权限数据在应用卸载时自动清除。