鸿蒙三方库 | harmony-utils之PreferencesUtil首选项数据监听详解
前言
首选项数据监听可以让应用实时感知配置变化，如主题切换、语言变更等。@pura/harmony-utils的PreferencesUtil封装了数据变化监听方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。
一、PreferencesUtil监听核心API
PreferencesUtil提供了以下数据监听方法：
| 方法 | 说明 | 参数 | 使用场景 |
|---|---|---|---|
onDataChange(callback) | 订阅数据变化 | callback | 实时配置感知 |
offDataChange(callback) | 取消数据变化订阅 | callback | 释放资源 |
1.1 核心特性
- 简洁易用：封装复杂API为一行调用，降低使用门槛
- 类型安全：完整的TypeScript类型定义，编译期即可发现错误
- 异常处理：内置异常捕获机制，避免运行时崩溃
- 实时感知：数据变化时立即触发回调
1.2 监听应用场景
| 场景 | 监听Key | 响应行为 |
|---|---|---|
| 主题切换 | theme | 更新UI主题 |
| 语言变更 | language | 刷新文本 |
| 登录状态 | is_logged_in | 更新导航栏 |
二、完整使用步骤
2.1 安装依赖
ohpminstall@pura/harmony-utils2.2 订阅数据变化
import{PreferencesUtil}from'@pura/harmony-utils';privatedataCallback=(key:string)=>{this.result=`数据变化:${key}`;};aboutToAppear(){PreferencesUtil.onDataChange(this.dataCallback);}aboutToDisappear(){PreferencesUtil.offDataChange(this.dataCallback);}2.3 实时响应配置变化
PreferencesUtil.onDataChange((key)=>{if(key==='theme'){this.loadTheme();}elseif(key==='language'){this.loadLanguage();}});三、完整页面示例
import{PreferencesUtil}from'@pura/harmony-utils';@Entry@Componentstruct PrefListenerDemo{@Stateresult:string='等待数据变化...';aboutToAppear(){PreferencesUtil.onDataChange((key)=>{this.result=`数据变化:${key}`;});}aboutToDisappear(){PreferencesUtil.offDataChange();}build(){Column({space:12}){Button('修改数据触发监听').width('100%').onClick(async()=>{awaitPreferencesUtil.putString('test_key','new_value');awaitPreferencesUtil.flush();});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}四、进阶用法
4.1 配置变化管理器
import{PreferencesUtil}from'@pura/harmony-utils';classConfigManager{privatestatichandlers:Record<string,Function>={};staticinit():void{PreferencesUtil.onDataChange((key:string)=>{lethandler=ConfigManager.handlers[key];if(handler)handler();});}staticregister(key:string,handler:Function):void{ConfigManager.handlers[key]=handler;}}4.2 主题切换响应
ConfigManager.register('theme',()=>{lettheme=PreferencesUtil.getString('theme','light');AppStorage.setOrCreate('currentTheme',theme);});五、注意事项
- 回调引用：注册和取消需使用同一回调引用
- 生命周期：页面销毁时务必取消订阅
- 性能：回调中避免耗时操作
- 初始化依赖：使用前需确保
AppUtil.init()已调用 - flush触发：数据变化需flush后才触发回调
六、常见问题
Q1: 数据变化后回调不触发？
确保调用了flush()方法，只有持久化后才会触发变化通知。
Q2: 可以监听特定key的变化吗？
回调参数包含变化的key，可以在回调中判断具体key。
Q3: 多次订阅会触发多次吗？
是的，每个订阅的回调都会触发，注意避免重复订阅。
Q4: 取消订阅后还会收到回调吗？
不会，取消订阅后不再触发回调。
总结
PreferencesUtil的数据监听方法为配置变化实时感知提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用数据监听，可以实现主题切换、语言变更等实时响应功能。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。