鸿蒙三方库 | 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 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 订阅数据变化

typescript 复制代码

import { PreferencesUtil } from '@pura/harmony-utils';

private dataCallback = (key: string) => {
  this.result = `数据变化: ${key}`;
};

aboutToAppear() {
  PreferencesUtil.onDataChange(this.dataCallback);
}

aboutToDisappear() {
  PreferencesUtil.offDataChange(this.dataCallback);
}

2.3 实时响应配置变化

typescript 复制代码

PreferencesUtil.onDataChange((key) => {
  if (key === 'theme') {
    this.loadTheme();
  } else if (key === 'language') {
    this.loadLanguage();
  }
});

三、完整页面示例

typescript 复制代码

import { PreferencesUtil } from '@pura/harmony-utils';

@Entry
@Component
struct PrefListenerDemo {
  @State result: string = '等待数据变化...';

  aboutToAppear() {
    PreferencesUtil.onDataChange((key) => {
      this.result = `数据变化: ${key}`;
    });
  }

  aboutToDisappear() {
    PreferencesUtil.offDataChange();
  }

  build() {
    Column({ space: 12 }) {
      Button('修改数据触发监听').width('100%').onClick(async () => {
        await PreferencesUtil.putString('test_key', 'new_value');
        await PreferencesUtil.flush();
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 配置变化管理器

typescript 复制代码

import { PreferencesUtil } from '@pura/harmony-utils';

class ConfigManager {
  private static handlers: Record<string, Function> = {};

  static init(): void {
    PreferencesUtil.onDataChange((key: string) => {
      let handler = ConfigManager.handlers[key];
      if (handler) handler();
    });
  }

  static register(key: string, handler: Function): void {
    ConfigManager.handlers[key] = handler;
  }
}

4.2 主题切换响应

typescript 复制代码

ConfigManager.register('theme', () => {
  let theme = 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 工具库，更多功能请参考官方文档与后续系列文章。