HarmonyOS鸿蒙NEXT首选项（Preferences）存储详解

鸿蒙首选项（Preferences）存储详解

1. 存储核心特性

2. ArkTS 操作示例

// 导入首选项模块
import preferences from '@ohos.data.preferences';

@Component
struct SettingsPage {
  // 创建首选项实例
  private pref: preferences.Preferences = await preferences.getPreferences(this.context, 'userSettings');

  // 存储数据
  async saveSettings() {
    try {
      // 存储键值对
      await this.pref.put('theme', 'dark');         // 字符串
      await this.pref.put('notifications', true);   // 布尔值
      await this.pref.put('fontSize', 16);          // 数值
      await this.pref.put('tags', ['urgent', 'work']); // 数组
      
      // 提交更改（异步刷盘）
      await this.pref.flush();
      console.info('首选项保存成功');
    } catch (err) {
      console.error(`保存失败: ${err.code}, ${err.message}`);
    }
  }

  // 读取数据
  async loadSettings() {
    try {
      // 获取值（带默认值）
      const theme: string = await this.pref.get('theme', 'light');
      const notify: boolean = await this.pref.get('notifications', false);
      const size: number = await this.pref.get('fontSize', 14);
      const tags: string[] = await this.pref.get('tags', ['default']);

      // 更新UI状态
      AppStorage.setOrCreate('currentTheme', theme);
      AppStorage.setOrCreate('fontSize', size);
    } catch (err) {
      console.error(`读取失败: ${err.code}, ${err.message}`);
    }
  }

  // 删除数据
  async clearToken() {
    await this.pref.delete('authToken');
    await this.pref.flush();
  }

  // 生命周期：页面显示时加载
  onPageShow() {
    this.loadSettings();
  }

  build() {
    Column() {
      Toggle({ type: ToggleType.Checkbox, isOn: $rawApp('notifications') })
        .onChange(async (checked: boolean) => {
          await this.pref.put('notifications', checked);
        })
    }
  }
}

3. 最佳实践

命名规范

// 使用业务语义化前缀
const pref = await preferences.getPreferences(this.context, 'payment_settings');

敏感数据加密

import { BusinessError } from '@ohos.base';
import cryptoFramework from '@ohos.security.cryptoFramework';

async storeSensitiveData(key: string, value: string) {
  const cipher = await cryptoFramework.createCipher('AES256|ECB|PKCS7');
  // ... 加密流程
  await this.pref.put(key, encryptedValue);
}

数据监听（ArkUI联动）

// 注册数据变更监听
this.pref.on('change', (key: string) => {
  if (key === 'theme') {
    // 自动更新UI
    AppStorage.set('currentTheme', this.pref.getSync('theme'));
  }
});

4. 文件存储位置

应用沙箱路径示例： /data/app/el2/100/base/com.example.myapp/database/userSettings.pref

文件结构：

• Header (元信息)
• Key1: Value1 (二进制编码)
• Key2: Value2
• …

5. 适用场景

关键限制：

• 单文件大小限制 1MB（超大数据需用RDB关系型数据库）
• 键名长度上限 80字节，字符串值上限 8192字节
• 数组/对象会被序列化为字符串存储（需自行管理序列化）

6. 与AppStorage联动

// 将首选项绑定到ArkUI全局状态
AppStorage.linkPreference(this.context, 'notifications', 'userSettings', 'notifications');

// 组件内直接使用
@StorageLink('notifications') notifyEnabled: boolean = false;

build() {
  Toggle({ isOn: this.notifyEnabled })
    .onChange((val) => {
      // 自动更新首选项
      this.notifyEnabled = val;
    })
}

对比其他存储方案