本文详解HarmonyOS中Preferences存储轻量级数据的初始化、写入、读取及删除方法，帮助开发者实现应用配置数据的本地持久化，避免数据丢失。
在HarmonyOS开发中，保存用户主题、登录状态等少量配置信息是常见需求。本文将介绍如何使用Preferences实现本地持久化，确保应用重启后数据依然可用。
一、初始化Preferences实例
要开始使用 Preferences，第一步是确保正确初始化实例。请在文件头部导入 @ohos.data.preferences 模块。随后，需要定义一个全局的偏好文件名，例如 PREF_NAME。注意：该名称必须严格遵循全小写字母加下划线的规则，且长度不得超过 32 个字符，否则后续操作可能会因命名不规范而报错。
- 上下文获取时机：获取 Context 对象是关键环节。建议在 Ability 的 onCreate 生命周期或页面的 onPageShow 中调用 getContext(this)。注意：切勿在构造函数中提前获取，因为此时上下文可能尚未完全就绪，会导致获取失败。
拿到 Context 后，调用 getPreferences(context, PREF_NAME) 来异步获取实例。该方法返回一个 Promise 对象，因此必须使用 then/catch 或 async/await 处理结果。在 then 回调中拿到的 Preferences 对象才是后续读写数据的“钥匙”。只有确保这一步成功执行，才能安全地进行后续的数据持久化操作。
二、写入数据与类型支持
拿到 Preferences 实例后，就可以开始写入数据了。Preferences 支持同步和异步两种写入模式，开发者可根据业务场景灵活选择。对于简单的配置项保存，同步写入更为直观便捷。调用 putSync(key, value) 方法即可将数据写入内存，支持 string、number、boolean 及数组等基础类型。但这里有一个极其容易被忽视的细节：putSync 仅仅是将数据暂存在内存中，若不及时调用 flushSync()，一旦应用进程被杀或设备重启，数据将直接丢失。因此，同步写入后紧跟 flushSync 是确保数据落盘的标准动作。
在异步场景下，推荐使用 await prefs.put(key, value) 进行非阻塞写入，随后务必执行 await prefs.flush() 触发异步落盘机制。注意：仅调用 put 而不执行 flush，数据永远不会写入磁盘文件，这在调试阶段极易造成“数据已保存但重启后消失”的假象。
当需要一次性保存多个配置项时，使用批量写入效率更高。通过构建键值对对象并调用对应的批量方法，可以减少多次 IO 操作的开销。无论采用何种写入方式，养成“写入必刷盘”的习惯，是防止轻量级数据丢失的关键所在。完成数据持久化后，后续章节将介绍如何读取这些数据以及执行删除操作。
三、读取删除与数据清空
数据落盘后，如何准确取回是开发中的另一关键环节。在读取数据时，必须为 get 或 getSync 方法提供第二个参数，即默认值。例如执行 get('theme', 'light')，若键 'theme' 存在则返回存储的值，若不存在则返回 'light'。这一机制至关重要，它能避免键缺失时返回 undefined，从而防止 UI 组件因数据异常而渲染失败或崩溃。
当应用逻辑变更或用户退出登录时，可能需要移除特定的配置项。调用 removeSync('token') 可删除指定键值对。与写入类似，若需确保删除操作立即同步至磁盘，应紧接调用 flushSync()，防止进程异常退出后旧数据残留。
对于需要重置应用状态的场景，clearSync() 方法可以一次性清空当前 Preferences 文件内的所有键值对。注意：该操作不可逆，执行后所有本地配置将永久消失。因此在调用前，务必确认业务场景确实需要重置，或提前做好数据备份，以免误删关键用户数据。
