HarmonyOS鸿蒙Next中如何解决Preferences存储时报错的问题

【问题现象】

Preferences存储json格式字符串时报错：Parameter error. The type of ‘value’ must be ValueType。

【背景知识】

Preferences的运行机制如下图所示，用户程序通过ArkTS接口调用用户首选项读写对应的数据文件。开发者可以将用户首选项持久化文件的内容加载到Preferences实例，每个文件唯一对应到一个Preferences实例，系统会通过静态容器将该实例存储在内存中，直到主动从内存中移除该实例或者删除该文件。

应用首选项的持久化文件保存在应用沙箱内部，可以通过context获取其路径。具体可见获取应用文件路径。

Preferences在使用过程中会存在以下约束限制：

• 首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。
• Key键为string类型，要求非空且长度不超过1024个字节。
• 如果Value值为string类型，请使用UTF-8编码格式，可以为空，不为空时长度不超过16 * 1024 * 1024个字节。
• 内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据不超过一万条，否则会在内存方面产生较大的开销。

【定位思路】

@Entry
@Component
struct AAPage {
  dataPreferences: preferences.Preferences | null = null;
  aboutToAppear(): void {
    let options: preferences.Options = { name: 'myStore' };
    this.dataPreferences = preferences.getPreferencesSync(getContext(this), options);
  }
  build() {
    Column() {
      Button('新增首选项-少')
        .onClick(() => {
          try {
            // 当字符串有特殊字符时，需要将字符串转为Uint8Array类型再存储
            let uInt8Array1 = new util.TextEncoder().encodeInto("~！@# ￥%……&*（）——+？");
            this.dataPreferences?.putSync('small', uInt8Array1);
            console.log('新增small成功')
          } catch (e) {
            console.log('新增small异常', JSON.stringify(e))
          }

          this.dataPreferences?.flush((err: BusinessError) => {
            if (err) {
              console.error(`刷入失败. Code:${err.code}, message:${err.message}`);
              return;
            }
            console.info('刷入成功');
          })
        })
      Button('新增首选项-多')
        .onClick(() => {
          try {
            let key = '一段超长文本（自行添加）'
            this.dataPreferences?.putSync(key, 'value');
            console.log('新增big成功')
          } catch (e) {
            console.log('新增big异常', JSON.stringify(e))
          }
          this.dataPreferences?.flush((err: BusinessError) => {
            if (err) {
              console.error(`刷入失败. Code:${err.code}, message:${err.message}`);
              return;
            }
            console.info('刷入成功');
          })
        }
        )
    }
  }
}

点击“新增首选项-少”按钮可以正常添加，点击“新增首选项-多”会出现错误，根据错误提示来定位问题。

根据官网文档提示，表明传入的参数错误。可能的原因：

1. 强制参数未指定;
2. 参数类型不正确;
3. 参数校验失败。

通过对传入的参数进行校验，发现传入的Key超过了最大上限。

【解决方案】

1. Preferences的Key键为string类型，要求非空且长度不超过1024个字节。
2. 如果Preferences的Value值为string类型，请使用UTF-8编码格式，可以为空，不为空时长度不超过16 * 1024 * 1024个字节。

根据上述限制，修改保存进Preferences的key名称，防止超过最大长度。比如采用小驼峰式简洁的命名方式：let key = ‘myKey’。