鸿蒙系统PersistentStorage的使用方法

一、基础使用流程

1. 初始化与属性绑定

// 步骤1：导入模块 
import { PersistentStorage } from '@kit.ArkData';
 
// 步骤2：声明持久化属性 
PersistentStorage.persistProp<string>('username', 'Guest'); // 绑定到AppStorage 
PersistentStorage.persistProp<number>('fontSize', 16);

2. UI组件绑定

@Entry 
@Component 
struct UserPage {
  // 双向绑定（数据变更自动持久化）
  @StorageLink('username') username: string = '';
  
  // 单向绑定（仅读取）
  @StorageProp('fontSize') fontSize: number = 16;
 
  build() {
    Column() {
      Text(this.username) // 显示持久化数据 
        .fontSize(this.fontSize)
        .onClick(() => {
          this.username = 'NewUser'; // 修改后自动同步到磁盘 
        })
    }
  }
}

二、数据类型处理

1. 支持的数据类型
   | 类型 | 示例 | 序列化方式 |
   |------------|--------------------------------|----------------|
   | 基本类型 | string, number, boolean | 直接存储 |
   | 简单对象 | {x:1, y:"text"} | JSON.stringify |
   | 数组 | [1, "a", false] | JSON序列化 |

2. 禁止使用的类型

// 不支持的类型示例 
PersistentStorage.persistProp<Map<string, number>>('mapData', new Map()); // ❌ 报错 
PersistentStorage.persistProp<Date>('time', new Date()); // ❌ 报错（需手动转字符串）

三、进阶操作技巧

1. 动态更新数据

// 通过AppStorage修改数据 
AppStorage.set('username', 'UpdatedUser'); // 自动触发持久化 

2. 删除持久化属性

PersistentStorage.delete('username'); // 删除磁盘数据 

3. 批量持久化

PersistentStorage.persistProps({
  'theme': 'dark',
  'notifyEnabled': true,
  'lastLogin': JSON.stringify(new Date()) // 复杂类型手动序列化 
});

四、关键注意事项

1. 初始化时机
   必须在UI实例加载完成后调用persistProp，否则持久化失败：

   loadContent(() => {
     PersistentStorage.persistProp('key', value); // ✅ 正确位置 
   });
   

2. 性能优化

   • 单条数据建议 < 2KB
   • 避免高频写入（每秒超过10次可能引发卡顿）

3. 数据类型转换
   Date对象建议手动转换：

   // 存储时 
   const dateStr = new Date().toISOString();
   PersistentStorage.persistProp('lastUpdate', dateStr);
   
   // 读取时 
   const date = new Date(AppStorage.get('lastUpdate'));
   

五、调试与数据查看

1. 查看持久化文件路径

const context = getContext();
const path = context.filesDir + '/PersistentStorage'; // 文件存储位置 

2. 数据加密（敏感信息）

PersistentStorage.persistProp('token', 'secret', {
  encrypt: true, // 启用AES-256加密 
  alias: 'user_credentials'
});

六、常见问题解决

1. 数据不同步问题
   检查是否通过AppStorage.set()修改数据，直接操作PersistentStorage无效

2. 应用首次启动逻辑
   首次安装时数据初始化顺序：

完整代码示例可参考华为开发者文档，实际开发中建议结合AppStorage的状态管理机制设计数据流。