HarmonyOS：数据持久化（一）：用户首选项

一，什么是用户首选项（Prefereces）

熟悉Android 的小伙伴都知道Android中有个SharedPreferences，Preferences和Android 中的SharedPreferences类似。Preferences是以Key-Value的形式将数据存储在应用内存和本地文件中，该文件保存在应用沙箱内部。Preferences将数据缓存在内存中，因此读取速度快。当需要将数据持久化时，通过flush()将数据写入本地文件中。Preferences会随着存储数据量的增大导致应用占用内存越大，因此，Preferences不适合存放过多的数据，并且也不支持加密。

二，运作机制

Prefereces的实例可以通过上下文Context和文件名获取，该文件名是数据存储在本地文件的文件命名，该文件存储在应用沙箱内部(路径：context.getApplicationContext().preferencesDir)。注意：如果要将数据进行分文件管理，文件名称不可重复。每个文件对应唯一一个Preferences实例，系统会通过静态容器将实例存储在内存中以确保实例的唯一性。通过put()将数据存储在Preferences实例中，调用flush()，将数据持久化到文件。如果只调用了put(),未调用flush()，数据只会存储在内存中，应用关闭重新打开时数据会丢失。通过get()从Preferences实例中获取指定的数据。

三，Api说明

1，preferences.getPreferencesSync(context: Context, options: Options): Preferences

获取Preferences实例

参数options：

{

  name（string）：Preferences实例的名称

 dataGroupId（string|null|undefined）：应用组ID，需要向应用市场获取，暂不支持

}

2，preferences.deletePreferences(context: Context, options: Options):Promise<void>

从缓存中移除指定的Preferences实例，并删除对应的持久化文件。

注意：调用该api后，该Preferences实例不可再使用，将该Preferences置为null，系统将统一回收。

3，preferences.removePreferencesFromCacheSync(context: Context, name: string):void

从缓存中移除指定的Preferences实例，不会删除对应的持久化文件。

注意：

a，调用该api后，该Preferences实例不可再使用，将该Preferences置为null，系统将统一回收。

b，如果再次使用该Preferences实例，要再次调用preferences.getPreferencesSync 重新获取实例。

4，getSync(key: string, defValue: ValueType): ValueType

从缓存的Preferences实例中获取键对应的值，如果值为null或者是不支持的数据类型，返回默认数据defValue

5，getAllSync(): Object

从缓存的Preferences实例中获取所有的键。返回的数据类型是Object，可以使用：Object.keys(object) 获取所有的Key。

6，putSync(key: string, value: ValueType): void

将数据写入缓存的Preferences实例中。

注意：

a，当对应的值已经存在，会覆盖原来的值；

b，值只会存在于内存中，使用flush()可将值写入到本地文件中。

7，hasSync(key: string): boolean

检查缓存的Preferences实例中是否包含指定的Key

8，deleteSync(key: string): void

从缓存的Preferences实例中删除指定的键值对

注意：只删除了缓存中的键值对，本地文件中还有。若想连同本地文件里的键值对一起删除，需调用flush()。

9，flush(): Promise<void>

将缓存的Preferences实例中的数据异步存储到本地文件中

10，clearSync(): void

清除缓存的Preferences实例中的所有数据

注意：只是清除了缓存中的数据，若想连同本地文件里的数据一起清除，需调用flush()。

11，on(type: 'change', callback: Callback<string>): void

订阅数据变更。

参数：

type：事件类型，固定值'change'，表示数据变更

callback：事件回调，（key:string）=>{}

注意：触发callback回调必须满足两个条件：数据发生了变更；调用flush()

12，on(type: 'multiProcessChange', callback: Callback<string>): void

订阅进程间数据变更。

参数：type：事件类型，固定值'multiProcessChange'，表示多进程间的数据变更

注意：多个进程持有同一个首选项文件时，value值在任意一个进程发生变更后，执行flush方法后，触发callback回调

13，on(type: 'dataChange', keys: Array<string>, callback: Callback<Record<string, ValueType>>): void

订阅指定key对应的value发生变更

参数：

type：事件类型，固定值'dataChange'，表示精确的数据变更。

keys：需要订阅的key数组

注意：触发callback回调必须满足两个条件：发生变更的value所对应的key要在订阅的key数组中；调用flush()。

14，off('type')

取消订阅。

参数：type：事件类型，可取：change，multiProcessChange，dataChange。 

四，使用限制

1，Key的最大长度限制为1024个字节，Value的最大长度限制为16 * 1024 * 1024个字节。

2，Key的数据类型是string，value的数据类型支持：number，string，boolean，Array<string>，Array<number>，Array<boolean>，Uint8Array，object，bigint。

3，首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。

4，内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据不超过一万条，否则会在内存方面产生较大的开销

五，代码示例

工具类