鸿蒙操作系统使用 Preferences 实现用户首选项键值存储实战(本文已在AtomGit仓库开源)
一、背景说明
鸿蒙装机量突破 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 等加密方案处理,避免明文落盘。
六、扩展建议
- 配置分组:用不同
name拆分多个 Preferences 文件(如user_settings与app_settings),降低单文件膨胀与写冲突; - 加密配置:敏感字段可先经 Crypto Architecture Kit 加密再存入,或直接改用 Asset Store Kit 关键资产存储;
- 备份恢复:配置内容序列化成 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 全文。
更多推荐



所有评论(0)