鸿蒙三方库 | harmony-utils之PreferencesUtil用户首选项读写详解

前言

用户首选项（Preferences）是HarmonyOS提供的轻量级键值存储方案，适合存储少量数据，如用户设置、登录状态等。@pura/harmony-utils 的 PreferencesUtil 封装了首选项的读写方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、PreferencesUtil读写核心API

PreferencesUtil 提供了以下首选项读写方法：

方法	说明	返回类型	使用场景
`putString(key, value)`	写入字符串	void	用户名、Token
`getString(key, defValue)`	读取字符串	string	获取配置
`putNumber(key, value)`	写入数字	void	计数器、版本号
`getNumber(key, defValue)`	读取数字	number	获取数值
`putBoolean(key, value)`	写入布尔值	void	开关状态
`getBoolean(key, defValue)`	读取布尔值	boolean	获取状态
`flush()`	持久化到磁盘	void	确保数据落盘

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
多类型支持：支持字符串、数字、布尔值三种基本类型

1.2 数据类型对照

类型	写入方法	读取方法	默认值
字符串	putString	getString	''
数字	putNumber	getNumber	0
布尔值	putBoolean	getBoolean	false

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 写入首选项

typescript 复制代码

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

Button('写入首选项')
  .width('100%')
  .onClick(async () => {
    try {
      await PreferencesUtil.putString('username', '张三');
      await PreferencesUtil.putNumber('age', 25);
      await PreferencesUtil.putBoolean('login', true);
      await PreferencesUtil.flush();
      this.result = '写入成功 ✅\n已持久化到磁盘';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 读取首选项

typescript 复制代码

Button('读取首选项')
  .width('100%')
  .onClick(async () => {
    try {
      let name = await PreferencesUtil.getString('username', '默认值');
      let age = await PreferencesUtil.getNumber('age', 0);
      let login = await PreferencesUtil.getBoolean('login', false);
      this.result = `姓名: ${name}\n年龄: ${age}\n登录: ${login}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

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

@Entry
@Component
struct PreferencesDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('保存设置').width('100%').onClick(async () => {
        await PreferencesUtil.putString('theme', 'dark');
        await PreferencesUtil.flush();
        this.result = '设置已保存';
      });
      Button('读取设置').width('100%').onClick(async () => {
        let theme = await PreferencesUtil.getString('theme', 'light');
        this.result = `主题: ${theme}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 设置管理器

typescript 复制代码

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

class SettingsManager {
  static async saveTheme(theme: string): Promise<void> {
    await PreferencesUtil.putString('app_theme', theme);
    await PreferencesUtil.flush();
  }

  static async getTheme(): Promise<string> {
    return await PreferencesUtil.getString('app_theme', 'light');
  }

  static async isFirstLaunch(): Promise<boolean> {
    let isFirst = await PreferencesUtil.getBoolean('first_launch', true);
    if (isFirst) {
      await PreferencesUtil.putBoolean('first_launch', false);
      await PreferencesUtil.flush();
    }
    return isFirst;
  }
}

4.2 登录状态管理

typescript 复制代码

async function saveLoginState(token: string): Promise<void> {
  await PreferencesUtil.putString('auth_token', token);
  await PreferencesUtil.putBoolean('is_logged_in', true);
  await PreferencesUtil.flush();
}

五、注意事项

数据量：Preferences适合少量数据，大量数据建议使用数据库
flush调用：写入后需调用flush确保数据持久化
Key命名：建议使用有意义的key命名，避免冲突
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
异步操作：读写方法为异步，需使用await

六、常见问题

Q1: flush()不调用数据会丢失吗？

不调用flush时数据保存在内存中，应用异常退出可能丢失。

Q2: 如何存储复杂对象？

可以将对象JSON序列化后以字符串形式存储。

Q3: 多个页面可以共享数据吗？

可以，Preferences是应用级存储，所有页面共享同一份数据。

Q4: 如何清除所有首选项数据？

可以逐个删除key，或清除应用数据。

总结

PreferencesUtil 的首选项读写方法为轻量级数据存储提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用首选项存储用户设置、登录状态等简单数据。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。