HarmonyOS 用户首选项完全指南：轻量级数据存储与会话管理

引言在应用开发中既存在轻量级数据也存在大量复杂关系数据。HarmonyOS 提供了多种数据存储机制需要根据场景选择合适方案以提升开发效率与资源利用率。针对体积小、访问频率高、有加载速度要求的轻量化数据如用户偏好、应用配置参数使用传统关系型数据库存储过于笨重会引入不必要的开销。本节课将系统讲解用户首选项Preferences轻量级存储方案的概念、特性、运行原理、核心 API 与完整开发流程并通过字体大小调节案例演示实际开发方法。核心内容用户首选项基础认知适用场景适用于数据体积小、访问频率高、有加载速度要求的轻量级数据存储典型场景包括用户偏好设置、应用配置参数如字体大小、主题模式等。不适合存储大量数据与敏感数据。核心特性Key-Value 键值数据结构Key 为不重复的关键字用于索引Value 存储具体数据值。实例名KeyValuemyPreferencesappFontSize16非关系型数据库不保证遵循 ACID原子性、一致性、隔离性、持久性特性数据之间无关联关系不采用关系模型组织数据。数据存储量小数据默认存储在内存中存储量过大会导致应用占用内存过多。不支持数据加密目前无法通过配置实现数据加密不支持分布式同步。支持订阅数据变化的通知功能。用户首选项运行机制私有化存储原理整体架构采用分层架构分层调用关系如下上层用户程序通过 ArkTS 接口调用用户首选项。中层每个持久化文件唯一关联一个Preferences实例实例存储在内存中。下层文件目录存储用户首选项持久化文件。数据读写流程读取将持久化文件内容加载到Preferences实例再从中读取数据。写入修改Preferences实例数据后通过持久化操作写回磁盘文件。实例获取逻辑应用通过 UIAbility 上下文获取Preferences实例只要应用上下文一致读取的持久化文件就一致保证了数据读取的准确性。用户首选项核心 API接口名称功能描述getPreferencesSync(context: Context, options: Options): Preferences同步获取Preferences实例存在对应异步接口putSync(key: string, value: ValueType): void同步将键值对写入Preferences实例可调用flush完成持久化存在异步接口hasSync(key: string): boolean同步检查实例是否包含指定 KeyKey 不能为空存在异步接口getSync(key: string, defValue: ValueType): ValueType同步获取指定 Key 对应的值不存在则返回默认值defValue存在异步接口deleteSync(key: string): void同步删除指定 Key 的键值对存在异步接口flush(callback: AsyncCallbackvoid): void将当前实例的数据异步存储到持久化文件on(type: change, callback: Callbackstring): void订阅数据变更数据变更执行flush后触发回调off(type: change, callback?: Callbackstring): void取消订阅数据变更deletePreferences(context: Context, options: Options, callback: AsyncCallbackvoid): void从内存删除指定实例同时删除对应持久化文件用户首选项开发流程完整流程导入模块→获取 Preferences 实例→保存数据→读取数据→数据持久化步骤 1导入模块需要先从kit.ArkData导入 preferences 模块。import { preferences } from kit.ArkData;步骤 2获取 Preferences 实例使用getPreferencesSync同步方法获取实例传入应用上下文和配置选项配置选项用于指定实例名称。let dataPreferences: preferences.Preferences | null null; class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage) { let options: preferences.Options { name: myStore }; dataPreferences preferences.getPreferencesSync(this.context, options); } }第一个参数context决定了实例的作用范围必须从正确的组件获取上下文。步骤 3保存数据使用putSync同步方法写入键值对支持多种数据类型类型说明number数字string字符串boolean布尔值Arraynumber数字数组Arrayboolean布尔数组Arraystring字符串数组Uint8ArrayAPI 118 位无符号整型数组objectAPI 12对象bigintAPI 12任意精度整数dataPreferences.putSync(startup, auto);步骤 4读取数据使用getSync同步方法读取数据第二个参数为查询失败时返回的默认值。let value: preferences.ValueType dataPreferences.getSync(startup, default);步骤 5数据持久化除了系统自动持久化外可主动调用flush方法将内存数据写入持久化文件通过回调判断持久化结果。import { BusinessError } from kit.BasicServicesKit; dataPreferences.flush((err: BusinessError) { if (err) { console.error(Failed to flush. code err.code , message err.message); return; } console.info(Succeeded in flushing.); });主动调用flush可以避免应用异常退出导致的数据丢失修改关键配置后建议主动持久化。开发实践字体大小调节功能功能需求实现可保存的字体大小调节功能用户重新打开应用后自动加载之前的偏好设置。封装工具类将用户首选项操作封装为一个工具类简化调用export class FontPreferenceUtils { private preference: preferences.Preferences | null null; // 封装获取实例方法 getFontPreference(context: Context): void { try { this.preference preferences.getPreferencesSync(context, { name: fontPreference }); } catch (error) { console.error(Failed to get preference: JSON.stringify(error)); } } // 封装读取字体大小方法 getFontSize(): number { if (!this.preference) { return 0; } return this.preference.getSync(appFontSize, 0) as number; } // 封装保存字体大小方法 saveFontSize(value: number): void { if (!this.preference) { return; } this.preference.putSync(appFontSize, value); this.preference.flush((err: BusinessError) { if (err) { console.error(Failed to flush: JSON.stringify(err)); } }); } }页面整合逻辑应用启动时获取Preferences实例。从实例中读取之前保存的字体大小偏移量保存到全局状态变量初始化 UI 字体大小。用户调整字体后获取新的偏移量调用putSync写入实例调用flush完成持久化。更新状态变量触发 UI 重新渲染动态调整全局字体大小。Entry Component struct SettingsPage { State fontSizeOffset: number 0; private fontUtils: FontPreferenceUtils new FontPreferenceUtils(); aboutToAppear(): void { this.fontUtils.getFontPreference(getContext(this)); this.fontSizeOffset this.fontUtils.getFontSize(); } build() { Column() { Text(字体大小调节) .fontSize(16 this.fontSizeOffset) Slider({ value: this.fontSizeOffset, min: -4, max: 10, step: 1 }) .onChange((value: number) { this.fontSizeOffset value; this.fontUtils.saveFontSize(value); }) } } }偏移量为负数时字体缩小正数时字体放大实现根据用户偏好动态调整字体大小。总结本节课讲解了用户首选项的核心知识概念与特性用户首选项是 HarmonyOS 提供的轻量级键值型存储方案采用 Key-Value 结构、非关系型、数据存储量小、不支持加密。适用于小体积、高频访问的非敏感配置数据。运行原理采用分层架构每个持久化文件唯一关联一个Preferences实例实例存储在内存中。应用通过 UIAbility 上下文获取实例上下文一致则数据一致。核心 APIgetPreferencesSync获取实例、putSync写入数据、getSync读取数据、flush主动持久化、on/off订阅/取消数据变更、deletePreferences删除实例和文件。完整开发流程导入模块 → 获取实例 → 保存数据 → 读取数据 → 数据持久化。修改关键配置后建议主动调用flush避免数据丢失。字体大小调节案例封装工具类统一管理用户首选项操作从实例读取保存的字体偏移量初始化 UI用户调整后写入实例并主动持久化实现偏好记忆功能。