一、背景说明

鸿蒙装机量突破 1 亿台后,腾讯 AI 助手 Marvis 等重量级应用接连完成鸿蒙原生适配,应用本地配置的存取是最基础的能力之一。本文聚焦一个具体技术点:使用 ArkData 的 @ohos.data.preferences(用户首选项)模块,实现应用配置的键值存储——读写、默认值兜底、批量删除、变更监听与磁盘落盘的完整闭环,全部代码可直接编译运行(本文源码已在 AtomGit 仓库开源,见文末)。

二、技术原理

用户首选项(Preferences)是轻量级 Key-Value 存储方案,适合存放应用启动参数、用户设置等少量配置数据,核心概念:

  • Preferences 实例:通过 dataPreferences.getPreferences(context, { name }) 获取,一个文件对应一个实例;同文件建议只创建一次并缓存复用。
  • 内存态与磁盘态:put() 只更新内存态,必须调用 flush() 才会异步落盘——这是数据"丢失"问题的第一根源。
  • get 的默认值:get(key, default) 在 key 不存在时返回传入的默认值,首次启动的配置兜底全靠它。
  • 变更监听:on('change', callback) 订阅当前实例的数据变化,多页面共享配置时无需手动通知。
  • 同步接口:putSync/getSync 等同步版本适合小数据量高频读写,避免回调嵌套。

与 RDB(关系型数据库)的分工:结构化、多行多列数据用 RDB;少量零散配置项(开关状态、主题色、上次滚动位置)用 Preferences,读写更轻。数据流:

getPreferences(name) → put(key, value) → flush 落盘 →(下次启动)get(key, defaultValue) → on('change') 联动刷新 UI。

三、实现步骤

工程为 Stage 模型(API 12+),无任何权限要求,module.json5 保持默认。

1. 配置管理类 PrefsManager.ets
import { dataPreferences } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const FILE_NAME = 'app_settings';

export class PrefsManager {
  private static pref: dataPreferences.Preferences | null = null;

  // 初始化:整个应用只创建一次实例并缓存
  static async init(context: common.UIAbilityContext): Promise<void> {
    const options: dataPreferences.Options = { name: FILE_NAME };
    PrefsManager.pref = await dataPreferences.getPreferences(context, options);
    // 订阅变更:任意 key 变化时通知(多页面共享配置场景)
    PrefsManager.pref.on('change', (key: string) => {
      console.info(`config changed: ${key}`);
    });
  }

  // 写入字符串配置(put 只更新内存,flush 才落盘)
  static async putString(key: string, value: string): Promise<void> {
    await PrefsManager.pref!.put(key, value);
    await PrefsManager.pref!.flush();
  }

  // 读取字符串配置,key 不存在时返回默认值
  static getString(key: string, defaultValue: string): string {
    return PrefsManager.pref!.getSync(key, defaultValue) as string;
  }

  // 写入布尔配置(开关类)
  static async putBoolean(key: string, value: boolean): Promise<void> {
    await PrefsManager.pref!.put(key, value);
    await PrefsManager.pref!.flush();
  }

  static getBoolean(key: string, defaultValue: boolean): boolean {
    return PrefsManager.pref!.getSync(key, defaultValue) as boolean;
  }

  // 删除单个配置项
  static async removeKey(key: string): Promise<void> {
    await PrefsManager.pref!.delete(key);
    await PrefsManager.pref!.flush();
  }

  // 清空全部配置
  static async clearAll(): Promise<void> {
    await PrefsManager.pref!.clear();
    await PrefsManager.pref!.flush();
  }
}
2. UI 调用示例 Index.ets
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { PrefsManager } from '../model/PrefsManager';

@Entry
@Component
struct Index {
  @State userName: string = '';
  @State darkMode: boolean = false;
  @State log: string = '';
  private context = getContext(this) as common.UIAbilityContext;

  build() {
    Column({ space: 12 }) {
      Text('用户首选项(Preferences)').fontSize(16).fontWeight(FontWeight.Bold)

      TextInput({ placeholder: '输入用户名' })
        .width('90%')
        .onChange((value: string) => { this.userName = value; })

      Row({ space: 16 }) {
        Button('保存').onClick(async () => {
          try {
            await PrefsManager.putString('user_name', this.userName);
            this.log = '已保存';
          } catch (err) {
            this.log = `保存失败 code=${(err as BusinessError).code}`;
          }
        })

        Button('读取').onClick(() => {
          // 不存在时得到默认值 '游客',首次启动不会报错
          const name = PrefsManager.getString('user_name', '游客');
          this.log = `用户名:${name}`;
        })

        Toggle({ type: ToggleType.Switch, isOn: this.darkMode })
          .onChange(async (isOn: boolean) => {
            this.darkMode = isOn;
            await PrefsManager.putBoolean('dark_mode', isOn);
            this.log = `深色模式:${isOn ? '开' : '关'}`;
          })
      }

      Button('清空配置').onClick(async () => {
        await PrefsManager.clearAll();
        this.log = '已清空全部配置';
      })

      Text(this.log || '操作日志')
        .fontSize(13)
        .width('90%')
        .height(120)
        .backgroundColor('#F2F3F5')
        .padding(10)
        .borderRadius(8)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}
3. 启动时恢复配置(EntryAbility.ets)

在 Ability 创建后第一时间初始化并恢复配置,页面即可同步拿到值:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { PrefsManager } from '../model/PrefsManager';

export default class EntryAbility extends UIAbility {
  async onWindowStageCreate(windowStage): Promise<void> {
    await PrefsManager.init(this.context);
    const name = PrefsManager.getString('user_name', '游客');
    console.info(`restore config, user_name=${name}`);
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) { console.error(`loadContent failed: ${err.code}`); }
    });
  }
}
四、应用场景示例

首选项天然适合"启动引导页只显示一次"的场景,配合布尔值一行解决:

// 首次启动判断:show_guide 不存在时 getSync 返回 true
const needGuide = PrefsManager.getBoolean('show_guide', true);
if (needGuide) {
  await PrefsManager.putBoolean('show_guide', false); // 立即标记已展示
  // router.pushUrl({ url: 'pages/Guide' }); // 跳转引导页
}
五、技术要点
1. put 后必须 flush

put() 只写内存,进程被杀而未 flush() 的数据会丢失。正确的节奏是:高频小改动可先攒在内存、在页面 onPause/退出时机统一 flush();低频关键配置立即 flush()。

2. 实例缓存与并发

同一 name 的文件应只调用一次 getPreferences 并持有实例;重复获取虽不会报错,但多实例并发写入同一文件时建议串行化。Preferences 内部有写文件队列,flush 不要在循环里高频调用。

3. 错误处理
try {
  await PrefsManager.putString('theme', 'dark');
} catch (err) {
  const e = err as BusinessError;
  if (e.code === 15500000) {
    console.error('内部错误:实例可能已被 close');
  } else if (e.code === 401) {
    console.error('参数错误:key 为空或类型不合法');
  }
}
4. 使用限制
  • 官方建议单文件数据量控制在 1 万条以内、总大小尽量小于 8MB,超出请改用 RDB;
  • value 仅支持 number、string、boolean 三种标量类型,对象/数组需先 JSON 序列化成字符串;
  • 数据无加密保护,敏感内容应先经 Asset Store Kit 等加密方案处理,避免明文落盘。
六、扩展建议
  1. 配置分组:用不同 name 拆分多个 Preferences 文件(如 user_settings 与 app_settings),降低单文件膨胀与写冲突;
  2. 加密配置:敏感字段可先经 Crypto Architecture Kit 加密再存入,或直接改用 Asset Store Kit 关键资产存储;
  3. 备份恢复:配置内容序列化成 JSON 后写入沙箱文件,配合应用迁移场景实现配置导出导入:
// 导出全部配置为 JSON 字符串(示例:遍历已知 key 集合)
const keys = ['user_name', 'dark_mode'];
const dump: Record<string, object> = {};
keys.forEach((k: string) => {
  dump[k] = PrefsManager.getString(k, '') as object;
});
const json = JSON.stringify(dump); // 写入沙箱文件即可完成导出
结语

本文用 @ohos.data.preferences 完成了鸿蒙应用配置从初始化、读写、变更监听到清空的完整实现,核心代码约 120 行,均已开源到文末 AtomGit 仓库。理解内存态与磁盘态的边界、用好默认值兜底与变更监听,轻量配置存储就有了简洁可靠的系统级方案。

代码仓库

本文完整工程已在 AtomGit 开源:https://atomgit.com/NJPJI_Yang/hm-article-20261121-preferences-atomgit

仓库包含可直接用 DevEco Studio 打开编译的完整鸿蒙 Stage 工程(AppScope 应用配置、entry 模块、hvigor 构建脚本齐全),以及与 CSDN 发布内容一致的 article.md 全文。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐