前言

用户首选项（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 安装依赖

ohpm install @pura/harmony-utils

2.2 写入首选项

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 读取首选项

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;
    }
  })

三、完整页面示例

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 设置管理器

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 登录状态管理

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

五、注意事项

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

六、常见问题

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

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

Q2: 如何存储复杂对象？

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

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

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

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

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

总结

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

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