HarmonyOS 鸿蒙Next中用户首选项（Preferences）使用

作为鸿蒙轻量数据持久化的首选，Preferences 以文本形式存储键值对，应用启动时全量加载到内存，读写效率极高，但不适合存储大量数据（内存占用会随数据量增长而增大）。​

❶ 适用场景快速判断​

适用存储场景（如下图中 1、2、3、5、6、10、11） 针对于小白开发者来说可以推敲下为什么这些场景要用Preferences来存储而不是api接口直接获取展示🤔。

快速判断标准：​

单条数据（原始类型 / 单个对象）→ 直接用 Preferences​

多条对象 / 复杂结构数据 → 切换关系型数据库

❷ 基础开发 3 步走（快速上手）​

2.1. 导入核心模块​

import { preferences } from '@kit.ArkData';

2.2. 获取 Preferences 实例​

通过上下文创建实例，name为存储到磁盘的文件名：​

// 简洁写法
const dataPreferences = preferences.getPreferencesSync(this.context, { name: 'myStore' });

2.33. 核心 API 使用（存 / 读 / 删）​

存储​ putSync(键, 值) + flush()​ putSync写入内存，flush()同步到磁盘（实现持久化）​

读取 ​getSync(键, 默认值)​  从内存中读取，应用重启后会从磁盘加载到内存​

删除 ​deleteSync(键)​  从内存中删除，需配合flush()同步到磁盘​

​⚠️ 关键提醒：

Preferences 数据持久化功能必须在模拟器或真机上运行，预览模式无法生效！​

Preferences 数据持久化功能必须在模拟器或真机上运行，预览模式无法生效！​

Preferences 数据持久化功能必须在模拟器或真机上运行，预览模式无法生效！​

磁盘文件路径：/data/app/el2/100/base/应用唯一标识/haps/entry/preferences/文件名（可通过 Device File Browser 查看）​

❸ 实战封装：PreferencesUtil 工具类

3.1 工具类代码（utils/PreferencesUtil.ets）

工作推荐api改成异步 这里为了减少代码用的同步 

import { common } from '@kit.AbilityKit';
import { preferences } from '@kit.ArkData';
 
class PreferencesUtil {
  // 私有实例，避免外部修改
  private dataPreferences: preferences.Preferences | null = null;
 
  /**
   * 初始化 Preferences（在entryability中调用）
   * @param context 上下文环境
   */
  loadPreferences(context: common.UIAbilityContext) {
    if (!this.dataPreferences) {
      this.dataPreferences = preferences.getPreferencesSync(context, { name: 'myStore' });
    }
  }
 
  /**
   * 存储数据到内存（需配合flush同步到磁盘）
   * @param key 键
   * @param value 值（支持原始类型/单个对象）
   */
  put(key: string, value: preferences.ValueType) {
    this.dataPreferences?.putSync(key, value);
  }
 
  /**
   * 从内存读取数据
   * @param key 键
   * @param defaultValue 默认值
   * @returns 存储的值或默认值
   */
  get(key: string, defaultValue: preferences.ValueType) {
    return this.dataPreferences?.getSync(key, defaultValue) ?? defaultValue;
  }
 
  /**
   * 存储并同步到磁盘（推荐优先使用）
   * @param key 键
   * @param value 值
   */
  flush(key: string, value: preferences.ValueType) {
    this.put(key, value);
    this.dataPreferences?.flushSync(); // 同步到磁盘，确保持久化
  }
}
 
// 导出单例对象（全局唯一）
export const preferencesUtil = new PreferencesUtil();

3.2 初始化工具类（entryability 中）

import { preferencesUtil } from '../utils/PreferencesUtil';
 
export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage) {
    // 初始化 Preferences（仅需调用一次）
    preferencesUtil.loadPreferences(this.context);
    // ...其他逻辑
  }
}

3.3 使用

import { preferencesUtil } from '../utils/PreferencesUtil';
 
@Entry
@Component
struct Index {
  build() {
    Column({ space: 10 })
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center) {
        Button('存储用户信息').onClick(() => {
          preferencesUtil.flush('userName', '神龙教主');
          preferencesUtil.flush('isLogin', true);
        });
 
        Button('读取用户信息').onClick(() => {
          const userName = preferencesUtil.get('userName', '匿名用户');
          const isLogin = preferencesUtil.get('isLogin', false);
          console.log(`用户名：${userName}，登录状态：${isLogin}`);
        });
      }
}